« blib/lib/Test2/Manual/Testing/Introduction.pm
↑ Summary
blib/lib/Test2/Manual/Testing/Planning.pm »
| 1 | package Test2::Manual::Testing::Migrating; | ||
| 2 | use strict; | ||
| 3 | use warnings; | ||
| 4 | |||
| 5 | our $VERSION = '1.302226'; | ||
| 6 | |||
| 7 | 1; | ||
| 8 | |||
| 9 | =head1 NAME | ||
| 10 | |||
| 11 | Test2::Manual::Testing::Migrating - How to migrate existing tests from | ||
| 12 | Test::More to Test2. | ||
| 13 | |||
| 14 | =head1 DESCRIPTION | ||
| 15 | |||
| 16 | This tutorial covers the conversion of an existing test. This tutorial assumes | ||
| 17 | you have a test written using L<Test::More>. | ||
| 18 | |||
| 19 | =head1 LEGACY TEST | ||
| 20 | |||
| 21 | This tutorial will be converting this example test one section at a time: | ||
| 22 | |||
| 23 | C<t/example.t>: | ||
| 24 | |||
| 25 | ##################### | ||
| 26 | # Boilerplate | ||
| 27 | |||
| 28 | use strict; | ||
| 29 | use warnings; | ||
| 30 | |||
| 31 | use Test::More tests => 14; | ||
| 32 | |||
| 33 | use_ok 'Scalar::Util'; | ||
| 34 | require_ok 'Exporter'; | ||
| 35 | |||
| 36 | ##################### | ||
| 37 | # Simple assertions (no changes) | ||
| 38 | |||
| 39 | ok(1, "pass"); | ||
| 40 | |||
| 41 | is("apple", "apple", "Simple string compare"); | ||
| 42 | |||
| 43 | like("foo bar baz", qr/bar/, "Regex match"); | ||
| 44 | |||
| 45 | ##################### | ||
| 46 | # Todo | ||
| 47 | |||
| 48 | { | ||
| 49 | local $TODO = "These are todo"; | ||
| 50 | |||
| 51 | ok(0, "oops"); | ||
| 52 | } | ||
| 53 | |||
| 54 | ##################### | ||
| 55 | # Deep comparisons | ||
| 56 | |||
| 57 | is_deeply([1, 2, 3], [1, 2, 3], "Deep comparison"); | ||
| 58 | |||
| 59 | ##################### | ||
| 60 | # Comparing references | ||
| 61 | |||
| 62 | my $ref = [1]; | ||
| 63 | is($ref, $ref, "Check that we have the same ref both times"); | ||
| 64 | |||
| 65 | ##################### | ||
| 66 | # Things that are gone | ||
| 67 | |||
| 68 | ok(eq_array([1], [1]), "array comparison"); | ||
| 69 | ok(eq_hash({a => 1}, {a => 1}), "hash comparison"); | ||
| 70 | ok(eq_set([1, 3, 2], [1, 2, 3]), "set comparison"); | ||
| 71 | |||
| 72 | note explain([1, 2, 3]); | ||
| 73 | |||
| 74 | { | ||
| 75 | package THING; | ||
| 76 | sub new { bless({}, shift) } | ||
| 77 | } | ||
| 78 | |||
| 79 | my $thing = new_ok('THING'); | ||
| 80 | |||
| 81 | ##################### | ||
| 82 | # Tools that changed | ||
| 83 | |||
| 84 | isa_ok($thing, 'THING', '$thing'); | ||
| 85 | |||
| 86 | can_ok(__PACKAGE__, qw/ok is/); | ||
| 87 | |||
| 88 | =head1 BOILERPLATE | ||
| 89 | |||
| 90 | BEFORE: | ||
| 91 | |||
| 92 | use strict; | ||
| 93 | use warnings; | ||
| 94 | |||
| 95 | use Test::More tests => 14; | ||
| 96 | |||
| 97 | use_ok 'Scalar::Util'; | ||
| 98 | require_ok 'Exporter'; | ||
| 99 | |||
| 100 | AFTER: | ||
| 101 | |||
| 102 | use strict; | ||
| 103 | use warnings; | ||
| 104 | |||
| 105 | use Test2::V1 '-import'; | ||
| 106 | plan(11); | ||
| 107 | |||
| 108 | use Scalar::Util; | ||
| 109 | require Exporter; | ||
| 110 | |||
| 111 | =over 4 | ||
| 112 | |||
| 113 | =item Replace Test::More with Test2::V1 | ||
| 114 | |||
| 115 | L<Test2::V1> is the recommended bundle. In a full migration you | ||
| 116 | will want to replace L<Test::More> with the L<Test2::V1> bundle. | ||
| 117 | |||
| 118 | B<Note:> You should always double check the latest L<Test2> to see if there is | ||
| 119 | a new recommended bundle. When writing a new test you should always use the | ||
| 120 | newest Test::V# module. Higher numbers are newer version. | ||
| 121 | |||
| 122 | You probably want the C<-import> argument when using L<Test2::V0> as it will | ||
| 123 | populate your namespace with all the tools you expect from a test helper | ||
| 124 | module. However if you want your namespace left clean you can omit the | ||
| 125 | argument, in which case C<T2()> is the only thing added to your namespace, and | ||
| 126 | it can be used to access the tools: | ||
| 127 | |||
| 128 | use Test2::V1; | ||
| 129 | |||
| 130 | T2->ok(1, "pass"); | ||
| 131 | |||
| 132 | T2->done_testing; | ||
| 133 | |||
| 134 | =item NOTE: srand | ||
| 135 | |||
| 136 | When srand is on (not default in V1, but Default in older V0) it can cause | ||
| 137 | problems with things like L<File::Temp> which will end up attempting the same | ||
| 138 | "random" filenames for every test process started on a given day (or sharing | ||
| 139 | the same seed). | ||
| 140 | |||
| 141 | If this is a problem for you then please disable srand when loading | ||
| 142 | |||
| 143 | For L<Test2::V0>: | ||
| 144 | |||
| 145 | use Test2::V0 -no_srand => 1; | ||
| 146 | |||
| 147 | For L<Test2::V1> simply do not use the C<-P>, or C<-Plugins> import option and it will not be loaded. | ||
| 148 | |||
| 149 | |||
| 150 | =item Stop using use_ok() | ||
| 151 | |||
| 152 | C<use_ok()> has been removed. a C<use MODULE> statement will throw an exception | ||
| 153 | on failure anyway preventing the test from passing. | ||
| 154 | |||
| 155 | If you I<REALLY> want/need to assert that the file loaded you can use the L<ok> | ||
| 156 | module: | ||
| 157 | |||
| 158 | use ok 'Scalar::Util'; | ||
| 159 | |||
| 160 | The main difference here is that there is a space instead of an underscore. | ||
| 161 | |||
| 162 | =item Stop using require_ok() | ||
| 163 | |||
| 164 | C<require_ok> has been removed just like C<use_ok>. There is no L<ok> module | ||
| 165 | equivalent here. Just use C<require>. | ||
| 166 | |||
| 167 | =item (optional) remove strict/warnings | ||
| 168 | |||
| 169 | In the L<Test2::V0> bundle turns strict and warnings on for you. | ||
| 170 | |||
| 171 | In the L<Test2::V1> bundle you must ask for strict and warnings with one of the | ||
| 172 | following import args: C<-p>, C<-pragmas>, C<-strict>, C<-warnings>. | ||
| 173 | |||
| 174 | =item Change where the plan is set | ||
| 175 | |||
| 176 | Test2 does not allow you to set the plan at import. In the old code you would | ||
| 177 | pass C<< tests => 11 >> as an import argument. In L<Test2> you either need to | ||
| 178 | use the C<plan()> function to set the plan, or use C<done_testing()> at the end | ||
| 179 | of the test. | ||
| 180 | |||
| 181 | If your test already uses C<done_testing()> you can keep that and no plan | ||
| 182 | changes are necessary. | ||
| 183 | |||
| 184 | B<Note:> We are also changing the plan from 14 to 11, that is because we | ||
| 185 | dropped C<use_ok>, C<require_ok>, and we will be dropping one more later on. | ||
| 186 | This is why C<done_testing()> is recommended over a set plan. | ||
| 187 | |||
| 188 | =back | ||
| 189 | |||
| 190 | =head1 SIMPLE ASSERTIONS | ||
| 191 | |||
| 192 | The vast majority of assertions will not need any changes: | ||
| 193 | |||
| 194 | ##################### | ||
| 195 | # Simple assertions (no changes) | ||
| 196 | |||
| 197 | ok(1, "pass"); | ||
| 198 | |||
| 199 | is("apple", "apple", "Simple string compare"); | ||
| 200 | |||
| 201 | like("foo bar baz", qr/bar/, "Regex match"); | ||
| 202 | |||
| 203 | =head1 TODO | ||
| 204 | |||
| 205 | { | ||
| 206 | local $TODO = "These are todo"; | ||
| 207 | |||
| 208 | ok(0, "oops"); | ||
| 209 | } | ||
| 210 | |||
| 211 | The C<$TODO> package variable is gone. You now have a C<todo()> function. | ||
| 212 | |||
| 213 | There are 2 ways this can be used: | ||
| 214 | |||
| 215 | =over 4 | ||
| 216 | |||
| 217 | =item todo $reason => sub { ... } | ||
| 218 | |||
| 219 | todo "These are todo" => sub { | ||
| 220 | ok(0, "oops"); | ||
| 221 | }; | ||
| 222 | |||
| 223 | This is the cleanest way to do a todo. This will make all assertions inside the | ||
| 224 | codeblock into TODO assertions. | ||
| 225 | |||
| 226 | =item { my $TODO = todo $reason; ... } | ||
| 227 | |||
| 228 | { | ||
| 229 | my $TODO = todo "These are todo"; | ||
| 230 | |||
| 231 | ok(0, "oops"); | ||
| 232 | } | ||
| 233 | |||
| 234 | This is a system that emulates the old way. Instead of modifying a global | ||
| 235 | C<$TODO> variable you create a todo object with the C<todo()> function and | ||
| 236 | assign it to a lexical variable. Once the todo object falls out of scope the | ||
| 237 | TODO ends. | ||
| 238 | |||
| 239 | =back | ||
| 240 | |||
| 241 | =head1 DEEP COMPARISONS | ||
| 242 | |||
| 243 | is_deeply([1, 2, 3], [1, 2, 3], "Deep comparison"); | ||
| 244 | |||
| 245 | Deep comparisons are easy, simply replace C<is_deeply()> with C<is()>. | ||
| 246 | |||
| 247 | is([1, 2, 3], [1, 2, 3], "Deep comparison"); | ||
| 248 | |||
| 249 | =head1 COMPARING REFERENCES | ||
| 250 | |||
| 251 | my $ref = [1]; | ||
| 252 | is($ref, $ref, "Check that we have the same ref both times"); | ||
| 253 | |||
| 254 | The C<is()> function provided by L<Test::More> forces both arguments into | ||
| 255 | strings, which makes this a comparison of the reference addresses. L<Test2>'s | ||
| 256 | C<is()> function is a deep comparison, so this will still pass, but fails to | ||
| 257 | actually test what we want (that both references are the same exact ref, not | ||
| 258 | just identical structures.) | ||
| 259 | |||
| 260 | We now have the C<ref_is()> function that does what we really want, it ensures | ||
| 261 | both references are the same reference. This function does the job better than | ||
| 262 | the original, which could be thrown off by string overloading. | ||
| 263 | |||
| 264 | my $ref = [1]; | ||
| 265 | ref_is($ref, $ref, "Check that we have the same ref both times"); | ||
| 266 | |||
| 267 | =head1 TOOLS THAT ARE GONE | ||
| 268 | |||
| 269 | ok(eq_array([1], [1]), "array comparison"); | ||
| 270 | ok(eq_hash({a => 1}, {a => 1}), "hash comparison"); | ||
| 271 | ok(eq_set([1, 3, 2], [1, 2, 3]), "set comparison"); | ||
| 272 | |||
| 273 | note explain([1, 2, 3]); | ||
| 274 | |||
| 275 | { | ||
| 276 | package THING; | ||
| 277 | sub new { bless({}, shift) } | ||
| 278 | } | ||
| 279 | |||
| 280 | my $thing = new_ok('THING'); | ||
| 281 | |||
| 282 | C<eq_array>, C<eq_hash> and C<eq_set> have been considered deprecated for a | ||
| 283 | very long time, L<Test2> does not provide them at all. Instead you can just use | ||
| 284 | C<is()>: | ||
| 285 | |||
| 286 | is([1], [1], "array comparison"); | ||
| 287 | is({a => 1}, {a => 1}, "hash comparison"); | ||
| 288 | |||
| 289 | C<eq_set> is a tad more complicated, see L<Test2::Tools::Compare> for an | ||
| 290 | explanation: | ||
| 291 | |||
| 292 | is([1, 3, 2], bag { item 1; item 2; item 3; end }, "set comparison"); | ||
| 293 | |||
| 294 | C<explain()> has a rocky history. There have been arguments about how it should | ||
| 295 | work. L<Test2> decided to simply not include C<explain()> to avoid the | ||
| 296 | arguments. You can instead directly use Data::Dumper: | ||
| 297 | |||
| 298 | use Data::Dumper; | ||
| 299 | note Dumper([1, 2, 3]); | ||
| 300 | |||
| 301 | C<new_ok()> is gone. The implementation was complicated, and did not add much | ||
| 302 | value: | ||
| 303 | |||
| 304 | { | ||
| 305 | package THING; | ||
| 306 | sub new { bless({}, shift) } | ||
| 307 | } | ||
| 308 | |||
| 309 | my $thing = THING->new; | ||
| 310 | ok($thing, "made a new thing"); | ||
| 311 | |||
| 312 | The complete section after the conversion is: | ||
| 313 | |||
| 314 | is([1], [1], "array comparison"); | ||
| 315 | is({a => 1}, {a => 1}, "hash comparison"); | ||
| 316 | is([1, 3, 2], bag { item 1; item 2; item 3; end }, "set comparison"); | ||
| 317 | |||
| 318 | use Data::Dumper; | ||
| 319 | note Dumper([1, 2, 3]); | ||
| 320 | |||
| 321 | { | ||
| 322 | package THING; | ||
| 323 | sub new { bless({}, shift) } | ||
| 324 | } | ||
| 325 | |||
| 326 | my $thing = THING->new; | ||
| 327 | ok($thing, "made a new thing"); | ||
| 328 | |||
| 329 | =head1 TOOLS THAT HAVE CHANGED | ||
| 330 | |||
| 331 | isa_ok($thing, 'THING', '$thing'); | ||
| 332 | |||
| 333 | can_ok(__PACKAGE__, qw/ok is/); | ||
| 334 | |||
| 335 | In L<Test::More> these functions are very confusing, and most people use them | ||
| 336 | wrong! | ||
| 337 | |||
| 338 | C<isa_ok()> from L<Test::More> takes a thing, a class/reftype to check, and | ||
| 339 | then uses the third argument as an alternative display name for the first | ||
| 340 | argument (NOT a test name!). | ||
| 341 | |||
| 342 | C<can_ok()> from L<Test::More> is not consistent with C<isa_ok> as all | ||
| 343 | arguments after the first are subroutine names. | ||
| 344 | |||
| 345 | L<Test2> fixes this by making both functions consistent and obvious: | ||
| 346 | |||
| 347 | isa_ok($thing, ['THING'], 'got a THING'); | ||
| 348 | |||
| 349 | can_ok(__PACKAGE__, [qw/ok is/], "have expected subs"); | ||
| 350 | |||
| 351 | You will note that both functions take a thing, an arrayref as the second | ||
| 352 | argument, then a test name as the third argument. | ||
| 353 | |||
| 354 | =head1 FINAL VERSION | ||
| 355 | |||
| 356 | =head2 IMPORTS | ||
| 357 | |||
| 358 | ##################### | ||
| 359 | # Boilerplate | ||
| 360 | |||
| 361 | use strict; | ||
| 362 | use warnings; | ||
| 363 | use Test2::V1 '-import'; | ||
| 364 | plan(11); | ||
| 365 | |||
| 366 | use Scalar::Util; | ||
| 367 | require Exporter; | ||
| 368 | |||
| 369 | ##################### | ||
| 370 | # Simple assertions (no changes) | ||
| 371 | |||
| 372 | ok(1, "pass"); | ||
| 373 | |||
| 374 | is("apple", "apple", "Simple string compare"); | ||
| 375 | |||
| 376 | like("foo bar baz", qr/bar/, "Regex match"); | ||
| 377 | |||
| 378 | ##################### | ||
| 379 | # Todo | ||
| 380 | |||
| 381 | todo "These are todo" => sub { | ||
| 382 | ok(0, "oops"); | ||
| 383 | }; | ||
| 384 | |||
| 385 | ##################### | ||
| 386 | # Deep comparisons | ||
| 387 | |||
| 388 | is([1, 2, 3], [1, 2, 3], "Deep comparison"); | ||
| 389 | |||
| 390 | ##################### | ||
| 391 | # Comparing references | ||
| 392 | |||
| 393 | my $ref = [1]; | ||
| 394 | ref_is($ref, $ref, "Check that we have the same ref both times"); | ||
| 395 | |||
| 396 | ##################### | ||
| 397 | # Things that are gone | ||
| 398 | |||
| 399 | is([1], [1], "array comparison"); | ||
| 400 | is({a => 1}, {a => 1}, "hash comparison"); | ||
| 401 | |||
| 402 | is([1, 3, 2], bag { item 1; item 2; item 3; end }, "set comparison"); | ||
| 403 | |||
| 404 | use Data::Dumper; | ||
| 405 | note Dumper([1, 2, 3]); | ||
| 406 | |||
| 407 | { | ||
| 408 | package THING; | ||
| 409 | sub new { bless({}, shift) } | ||
| 410 | } | ||
| 411 | |||
| 412 | my $thing = THING->new; | ||
| 413 | |||
| 414 | ##################### | ||
| 415 | # Tools that changed | ||
| 416 | |||
| 417 | isa_ok($thing, ['THING'], 'got a THING'); | ||
| 418 | |||
| 419 | can_ok(__PACKAGE__, [qw/ok is/], "have expected subs"); | ||
| 420 | |||
| 421 | =head2 REDUCED BOILERPLATE | ||
| 422 | |||
| 423 | ##################### | ||
| 424 | # Boilerplate | ||
| 425 | |||
| 426 | use Test2::V1 '-ipP'; | ||
| 427 | plan(11); | ||
| 428 | |||
| 429 | use Scalar::Util; | ||
| 430 | require Exporter; | ||
| 431 | |||
| 432 | ##################### | ||
| 433 | # Simple assertions (no changes) | ||
| 434 | |||
| 435 | ok(1, "pass"); | ||
| 436 | |||
| 437 | is("apple", "apple", "Simple string compare"); | ||
| 438 | |||
| 439 | like("foo bar baz", qr/bar/, "Regex match"); | ||
| 440 | |||
| 441 | ##################### | ||
| 442 | # Todo | ||
| 443 | |||
| 444 | todo "These are todo" => sub { | ||
| 445 | ok(0, "oops"); | ||
| 446 | }; | ||
| 447 | |||
| 448 | ##################### | ||
| 449 | # Deep comparisons | ||
| 450 | |||
| 451 | is([1, 2, 3], [1, 2, 3], "Deep comparison"); | ||
| 452 | |||
| 453 | ##################### | ||
| 454 | # Comparing references | ||
| 455 | |||
| 456 | my $ref = [1]; | ||
| 457 | ref_is($ref, $ref, "Check that we have the same ref both times"); | ||
| 458 | |||
| 459 | ##################### | ||
| 460 | # Things that are gone | ||
| 461 | |||
| 462 | is([1], [1], "array comparison"); | ||
| 463 | is({a => 1}, {a => 1}, "hash comparison"); | ||
| 464 | |||
| 465 | is([1, 3, 2], bag { item 1; item 2; item 3; end }, "set comparison"); | ||
| 466 | |||
| 467 | use Data::Dumper; | ||
| 468 | note Dumper([1, 2, 3]); | ||
| 469 | |||
| 470 | { | ||
| 471 | package THING; | ||
| 472 | sub new { bless({}, shift) } | ||
| 473 | } | ||
| 474 | |||
| 475 | my $thing = THING->new; | ||
| 476 | |||
| 477 | ##################### | ||
| 478 | # Tools that changed | ||
| 479 | |||
| 480 | isa_ok($thing, ['THING'], 'got a THING'); | ||
| 481 | |||
| 482 | can_ok(__PACKAGE__, [qw/ok is/], "have expected subs"); | ||
| 483 | |||
| 484 | =head2 CLEAN NAMESPACE | ||
| 485 | |||
| 486 | use Test2::V1; | ||
| 487 | T2->plan(11); | ||
| 488 | |||
| 489 | use Scalar::Util; | ||
| 490 | require Exporter; | ||
| 491 | |||
| 492 | ##################### | ||
| 493 | # Simple assertions (no changes) | ||
| 494 | |||
| 495 | T2->ok(1, "pass"); | ||
| 496 | |||
| 497 | T2->is("apple", "apple", "Simple string compare"); | ||
| 498 | |||
| 499 | T2->like("foo bar baz", qr/bar/, "Regex match"); | ||
| 500 | |||
| 501 | ##################### | ||
| 502 | # Todo | ||
| 503 | |||
| 504 | T2->todo("These are todo" => sub { | ||
| 505 | ok(0, "oops"); | ||
| 506 | }); | ||
| 507 | |||
| 508 | ##################### | ||
| 509 | # Deep comparisons | ||
| 510 | |||
| 511 | T2->is([1, 2, 3], [1, 2, 3], "Deep comparison"); | ||
| 512 | |||
| 513 | ##################### | ||
| 514 | # Comparing references | ||
| 515 | |||
| 516 | my $ref = [1]; | ||
| 517 | T2->ref_is($ref, $ref, "Check that we have the same ref both times"); | ||
| 518 | |||
| 519 | ##################### | ||
| 520 | # Things that are gone | ||
| 521 | |||
| 522 | T2->is([1], [1], "array comparison"); | ||
| 523 | T2->is({a => 1}, {a => 1}, "hash comparison"); | ||
| 524 | |||
| 525 | T2->is([1, 3, 2], bag { item 1; item 2; item 3; end }, "set comparison"); | ||
| 526 | |||
| 527 | use Data::Dumper; | ||
| 528 | T2->note(Dumper([1, 2, 3])); | ||
| 529 | |||
| 530 | { | ||
| 531 | package THING; | ||
| 532 | sub new { bless({}, shift) } | ||
| 533 | } | ||
| 534 | |||
| 535 | my $thing = THING->new; | ||
| 536 | |||
| 537 | ##################### | ||
| 538 | # Tools that changed | ||
| 539 | |||
| 540 | T2->isa_ok($thing, ['THING'], 'got a THING'); | ||
| 541 | |||
| 542 | T2->can_ok(__PACKAGE__, [qw/ok is/], "have expected subs"); | ||
| 543 | |||
| 544 | =head1 SEE ALSO | ||
| 545 | |||
| 546 | L<Test2::Manual> - Primary index of the manual. | ||
| 547 | |||
| 548 | =head1 SOURCE | ||
| 549 | |||
| 550 | The source code repository for Test2-Manual can be found at | ||
| 551 | F<https://github.com/Test-More/test-more/>. | ||
| 552 | |||
| 553 | =head1 MAINTAINERS | ||
| 554 | |||
| 555 | =over 4 | ||
| 556 | |||
| 557 | =item Chad Granum E<lt>exodist@cpan.orgE<gt> | ||
| 558 | |||
| 559 | =back | ||
| 560 | |||
| 561 | =head1 AUTHORS | ||
| 562 | |||
| 563 | =over 4 | ||
| 564 | |||
| 565 | =item Chad Granum E<lt>exodist@cpan.orgE<gt> | ||
| 566 | |||
| 567 | =back | ||
| 568 | |||
| 569 | =head1 COPYRIGHT | ||
| 570 | |||
| 571 | Copyright Chad Granum E<lt>exodist@cpan.orgE<gt>. | ||
| 572 | |||
| 573 | This program is free software; you can redistribute it and/or | ||
| 574 | modify it under the same terms as Perl itself. | ||
| 575 | |||
| 576 | See F<http://dev.perl.org/licenses/> | ||
| 577 | |||
| 578 | =cut | ||
| 579 | |||
| 580 | |||
| 581 |