blib/lib/Test2/Manual/Testing/Migrating.pm untested

filter: Statementstmt 0.0% 0 / 7 Branchbran n/a Conditioncond n/a MC/DCmcdc n/a Subroutinesub 0.0% 0 / 2 Podpod n/a totaltotal 0.0% 0 / 9 CC 1 SCAR 6.9
CC
1
Cov
0%
BEGIN
2.0
BEGIN
2.0
CRAP 2.0
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