Debian Codegraph @

upstream/mageia-cauldron/man3pm/Test2::Manual::Testing::Migrating.3pm

raw
1 .\" -*- mode: troff; coding: utf-8 -*-
2 .\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45)
3 .\"
4 .\" Standard preamble:
5 .\" ========================================================================
6 .de Sp \" Vertical space (when we can't use .PP)
7 .if t .sp .5v
8 .if n .sp
9 ..
10 .de Vb \" Begin verbatim text
11 .ft CW
12 .nf
13 .ne \\$1
14 ..
15 .de Ve \" End verbatim text
16 .ft R
17 .fi
18 ..
19 .\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
20 .ie n \{\
21 . ds C` ""
22 . ds C' ""
23 'br\}
24 .el\{\
25 . ds C`
26 . ds C'
27 'br\}
28 .\"
29 .\" Escape single quotes in literal strings from groff's Unicode transform.
30 .ie \n(.g .ds Aq \(aq
31 .el .ds Aq '
32 .\"
33 .\" If the F register is >0, we'll generate index entries on stderr for
34 .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
35 .\" entries marked with X<> in POD. Of course, you'll have to process the
36 .\" output yourself in some meaningful fashion.
37 .\"
38 .\" Avoid warning from groff about undefined register 'F'.
39 .de IX
40 ..
41 .nr rF 0
42 .if \n(.g .if rF .nr rF 1
43 .if (\n(rF:(\n(.g==0)) \{\
44 . if \nF \{\
45 . de IX
46 . tm Index:\\$1\t\\n%\t"\\$2"
47 ..
48 . if !\nF==2 \{\
49 . nr % 0
50 . nr F 2
51 . \}
52 . \}
53 .\}
54 .rr rF
55 .\"
56 .\" Required to disable full justification in groff 1.23.0.
57 .if n .ds AD l
58 .\" ========================================================================
59 .\"
60 .IX Title "Test2::Manual::Testing::Migrating 3pm"
61 .TH Test2::Manual::Testing::Migrating 3pm 2025-06-24 "perl v5.42.0" "Perl Programmers Reference Guide"
62 .\" For nroff, turn off justification. Always turn off hyphenation; it makes
63 .\" way too many mistakes in technical documents.
64 .if n .ad l
65 .nh
66 .SH NAME
67 Test2::Manual::Testing::Migrating \- How to migrate existing tests from
68 Test::More to Test2.
69 .SH DESCRIPTION
70 .IX Header "DESCRIPTION"
71 This tutorial covers the conversion of an existing test. This tutorial assumes
72 you have a test written using Test::More.
73 .SH "LEGACY TEST"
74 .IX Header "LEGACY TEST"
75 This tutorial will be converting this example test one section at a time:
76 .PP
77 \&\f(CW\*(C`t/example.t\*(C'\fR:
78 .PP
79 .Vb 2
80 \& #####################
81 \& # Boilerplate
82 \&
83 \& use strict;
84 \& use warnings;
85 \&
86 \& use Test::More tests => 14;
87 \&
88 \& use_ok \*(AqScalar::Util\*(Aq;
89 \& require_ok \*(AqExporter\*(Aq;
90 \&
91 \& #####################
92 \& # Simple assertions (no changes)
93 \&
94 \& ok(1, "pass");
95 \&
96 \& is("apple", "apple", "Simple string compare");
97 \&
98 \& like("foo bar baz", qr/bar/, "Regex match");
99 \&
100 \& #####################
101 \& # Todo
102 \&
103 \& {
104 \& local $TODO = "These are todo";
105 \&
106 \& ok(0, "oops");
107 \& }
108 \&
109 \& #####################
110 \& # Deep comparisons
111 \&
112 \& is_deeply([1, 2, 3], [1, 2, 3], "Deep comparison");
113 \&
114 \& #####################
115 \& # Comparing references
116 \&
117 \& my $ref = [1];
118 \& is($ref, $ref, "Check that we have the same ref both times");
119 \&
120 \& #####################
121 \& # Things that are gone
122 \&
123 \& ok(eq_array([1], [1]), "array comparison");
124 \& ok(eq_hash({a => 1}, {a => 1}), "hash comparison");
125 \& ok(eq_set([1, 3, 2], [1, 2, 3]), "set comparison");
126 \&
127 \& note explain([1, 2, 3]);
128 \&
129 \& {
130 \& package THING;
131 \& sub new { bless({}, shift) }
132 \& }
133 \&
134 \& my $thing = new_ok(\*(AqTHING\*(Aq);
135 \&
136 \& #####################
137 \& # Tools that changed
138 \&
139 \& isa_ok($thing, \*(AqTHING\*(Aq, \*(Aq$thing\*(Aq);
140 \&
141 \& can_ok(_\|_PACKAGE_\|_, qw/ok is/);
142 .Ve
143 .SH BOILERPLATE
144 .IX Header "BOILERPLATE"
145 BEFORE:
146 .PP
147 .Vb 2
148 \& use strict;
149 \& use warnings;
150 \&
151 \& use Test::More tests => 14;
152 \&
153 \& use_ok \*(AqScalar::Util\*(Aq;
154 \& require_ok \*(AqExporter\*(Aq;
155 .Ve
156 .PP
157 AFTER:
158 .PP
159 .Vb 2
160 \& use Test2::V0;
161 \& plan(11);
162 \&
163 \& use Scalar::Util;
164 \& require Exporter;
165 .Ve
166 .IP "Replace Test::More with Test2::V0" 4
167 .IX Item "Replace Test::More with Test2::V0"
168 Test2::V0 is the recommended bundle. In a full migration you
169 will want to replace Test::More with the Test2::V0 bundle.
170 .Sp
171 \&\fBNote:\fR You should always double check the latest Test2 to see if there is
172 a new recommended bundle. When writing a new test you should always use the
173 newest Test::V# module. Higher numbers are newer version.
174 .IP "NOTE: srand" 4
175 .IX Item "NOTE: srand"
176 When srand is on (default) it can cause problems with things like File::Temp
177 which will end up attempting the same "random" filenames for every test process
178 started on a given day (or sharing the same seed).
179 .Sp
180 If this is a problem for you then please disable srand when loading
181 Test2::V0:
182 .Sp
183 .Vb 1
184 \& use Test2::V0 \-no_srand => 1;
185 .Ve
186 .IP "Stop using \fBuse_ok()\fR" 4
187 .IX Item "Stop using use_ok()"
188 \&\f(CWuse_ok()\fR has been removed. a \f(CW\*(C`use MODULE\*(C'\fR statement will throw an exception
189 on failure anyway preventing the test from passing.
190 .Sp
191 If you \fIREALLY\fR want/need to assert that the file loaded you can use the ok
192 module:
193 .Sp
194 .Vb 1
195 \& use ok \*(AqScalar::Util\*(Aq;
196 .Ve
197 .Sp
198 The main difference here is that there is a space instead of an underscore.
199 .IP "Stop using \fBrequire_ok()\fR" 4
200 .IX Item "Stop using require_ok()"
201 \&\f(CW\*(C`require_ok\*(C'\fR has been removed just like \f(CW\*(C`use_ok\*(C'\fR. There is no ok module
202 equivalent here. Just use \f(CW\*(C`require\*(C'\fR.
203 .IP "Remove strict/warnings (optional)" 4
204 .IX Item "Remove strict/warnings (optional)"
205 The Test2::V0 bundle turns strict and warnings on for you.
206 .IP "Change where the plan is set" 4
207 .IX Item "Change where the plan is set"
208 Test2 does not allow you to set the plan at import. In the old code you would
209 pass \f(CW\*(C`tests => 11\*(C'\fR as an import argument. In Test2 you either need to
210 use the \f(CWplan()\fR function to set the plan, or use \f(CWdone_testing()\fR at the end
211 of the test.
212 .Sp
213 If your test already uses \f(CWdone_testing()\fR you can keep that and no plan
214 changes are necessary.
215 .Sp
216 \&\fBNote:\fR We are also changing the plan from 14 to 11, that is because we
217 dropped \f(CW\*(C`use_ok\*(C'\fR, \f(CW\*(C`require_ok\*(C'\fR, and we will be dropping one more later on.
218 This is why \f(CWdone_testing()\fR is recommended over a set plan.
219 .SH "SIMPLE ASSERTIONS"
220 .IX Header "SIMPLE ASSERTIONS"
221 The vast majority of assertions will not need any changes:
222 .PP
223 .Vb 2
224 \& #####################
225 \& # Simple assertions (no changes)
226 \&
227 \& ok(1, "pass");
228 \&
229 \& is("apple", "apple", "Simple string compare");
230 \&
231 \& like("foo bar baz", qr/bar/, "Regex match");
232 .Ve
233 .SH TODO
234 .IX Header "TODO"
235 .Vb 2
236 \& {
237 \& local $TODO = "These are todo";
238 \&
239 \& ok(0, "oops");
240 \& }
241 .Ve
242 .PP
243 The \f(CW$TODO\fR package variable is gone. You now have a \f(CWtodo()\fR function.
244 .PP
245 There are 2 ways this can be used:
246 .ie n .IP "todo $reason => sub { ... }" 4
247 .el .IP "todo \f(CW$reason\fR => sub { ... }" 4
248 .IX Item "todo $reason => sub { ... }"
249 .Vb 3
250 \& todo "These are todo" => sub {
251 \& ok(0, "oops");
252 \& };
253 .Ve
254 .Sp
255 This is the cleanest way to do a todo. This will make all assertions inside the
256 codeblock into TODO assertions.
257 .ie n .IP "{ my $TODO = todo $reason; ... }" 4
258 .el .IP "{ my \f(CW$TODO\fR = todo \f(CW$reason\fR; ... }" 4
259 .IX Item "{ my $TODO = todo $reason; ... }"
260 .Vb 2
261 \& {
262 \& my $TODO = todo "These are todo";
263 \&
264 \& ok(0, "oops");
265 \& }
266 .Ve
267 .Sp
268 This is a system that emulates the old way. Instead of modifying a global
269 \&\f(CW$TODO\fR variable you create a todo object with the \f(CWtodo()\fR function and
270 assign it to a lexical variable. Once the todo object falls out of scope the
271 TODO ends.
272 .SH "DEEP COMPARISONS"
273 .IX Header "DEEP COMPARISONS"
274 .Vb 1
275 \& is_deeply([1, 2, 3], [1, 2, 3], "Deep comparison");
276 .Ve
277 .PP
278 Deep comparisons are easy, simply replace \f(CWis_deeply()\fR with \f(CWis()\fR.
279 .PP
280 .Vb 1
281 \& is([1, 2, 3], [1, 2, 3], "Deep comparison");
282 .Ve
283 .SH "COMPARING REFERENCES"
284 .IX Header "COMPARING REFERENCES"
285 .Vb 2
286 \& my $ref = [1];
287 \& is($ref, $ref, "Check that we have the same ref both times");
288 .Ve
289 .PP
290 The \f(CWis()\fR function provided by Test::More forces both arguments into
291 strings, which makes this a comparison of the reference addresses. Test2\*(Aqs
292 \&\f(CWis()\fR function is a deep comparison, so this will still pass, but fails to
293 actually test what we want (that both references are the same exact ref, not
294 just identical structures.)
295 .PP
296 We now have the \f(CWref_is()\fR function that does what we really want, it ensures
297 both references are the same reference. This function does the job better than
298 the original, which could be thrown off by string overloading.
299 .PP
300 .Vb 2
301 \& my $ref = [1];
302 \& ref_is($ref, $ref, "Check that we have the same ref both times");
303 .Ve
304 .SH "TOOLS THAT ARE GONE"
305 .IX Header "TOOLS THAT ARE GONE"
306 .Vb 3
307 \& ok(eq_array([1], [1]), "array comparison");
308 \& ok(eq_hash({a => 1}, {a => 1}), "hash comparison");
309 \& ok(eq_set([1, 3, 2], [1, 2, 3]), "set comparison");
310 \&
311 \& note explain([1, 2, 3]);
312 \&
313 \& {
314 \& package THING;
315 \& sub new { bless({}, shift) }
316 \& }
317 \&
318 \& my $thing = new_ok(\*(AqTHING\*(Aq);
319 .Ve
320 .PP
321 \&\f(CW\*(C`eq_array\*(C'\fR, \f(CW\*(C`eq_hash\*(C'\fR and \f(CW\*(C`eq_set\*(C'\fR have been considered deprecated for a
322 very long time, Test2 does not provide them at all. Instead you can just use
323 \&\f(CWis()\fR:
324 .PP
325 .Vb 2
326 \& is([1], [1], "array comparison");
327 \& is({a => 1}, {a => 1}, "hash comparison");
328 .Ve
329 .PP
330 \&\f(CW\*(C`eq_set\*(C'\fR is a tad more complicated, see Test2::Tools::Compare for an
331 explanation:
332 .PP
333 .Vb 1
334 \& is([1, 3, 2], bag { item 1; item 2; item 3; end }, "set comparison");
335 .Ve
336 .PP
337 \&\f(CWexplain()\fR has a rocky history. There have been arguments about how it should
338 work. Test2 decided to simply not include \f(CWexplain()\fR to avoid the
339 arguments. You can instead directly use Data::Dumper:
340 .PP
341 .Vb 2
342 \& use Data::Dumper;
343 \& note Dumper([1, 2, 3]);
344 .Ve
345 .PP
346 \&\f(CWnew_ok()\fR is gone. The implementation was complicated, and did not add much
347 value:
348 .PP
349 .Vb 4
350 \& {
351 \& package THING;
352 \& sub new { bless({}, shift) }
353 \& }
354 \&
355 \& my $thing = THING\->new;
356 \& ok($thing, "made a new thing");
357 .Ve
358 .PP
359 The complete section after the conversion is:
360 .PP
361 .Vb 3
362 \& is([1], [1], "array comparison");
363 \& is({a => 1}, {a => 1}, "hash comparison");
364 \& is([1, 3, 2], bag { item 1; item 2; item 3; end }, "set comparison");
365 \&
366 \& use Data::Dumper;
367 \& note Dumper([1, 2, 3]);
368 \&
369 \& {
370 \& package THING;
371 \& sub new { bless({}, shift) }
372 \& }
373 \&
374 \& my $thing = THING\->new;
375 \& ok($thing, "made a new thing");
376 .Ve
377 .SH "TOOLS THAT HAVE CHANGED"
378 .IX Header "TOOLS THAT HAVE CHANGED"
379 .Vb 1
380 \& isa_ok($thing, \*(AqTHING\*(Aq, \*(Aq$thing\*(Aq);
381 \&
382 \& can_ok(_\|_PACKAGE_\|_, qw/ok is/);
383 .Ve
384 .PP
385 In Test::More these functions are very confusing, and most people use them
386 wrong!
387 .PP
388 \&\f(CWisa_ok()\fR from Test::More takes a thing, a class/reftype to check, and
389 then uses the third argument as an alternative display name for the first
390 argument (NOT a test name!).
391 .PP
392 \&\f(CWcan_ok()\fR from Test::More is not consistent with \f(CW\*(C`isa_ok\*(C'\fR as all
393 arguments after the first are subroutine names.
394 .PP
395 Test2 fixes this by making both functions consistent and obvious:
396 .PP
397 .Vb 1
398 \& isa_ok($thing, [\*(AqTHING\*(Aq], \*(Aqgot a THING\*(Aq);
399 \&
400 \& can_ok(_\|_PACKAGE_\|_, [qw/ok is/], "have expected subs");
401 .Ve
402 .PP
403 You will note that both functions take a thing, an arrayref as the second
404 argument, then a test name as the third argument.
405 .SH "FINAL VERSION"
406 .IX Header "FINAL VERSION"
407 .Vb 2
408 \& #####################
409 \& # Boilerplate
410 \&
411 \& use Test2::V0;
412 \& plan(11);
413 \&
414 \& use Scalar::Util;
415 \& require Exporter;
416 \&
417 \& #####################
418 \& # Simple assertions (no changes)
419 \&
420 \& ok(1, "pass");
421 \&
422 \& is("apple", "apple", "Simple string compare");
423 \&
424 \& like("foo bar baz", qr/bar/, "Regex match");
425 \&
426 \& #####################
427 \& # Todo
428 \&
429 \& todo "These are todo" => sub {
430 \& ok(0, "oops");
431 \& };
432 \&
433 \& #####################
434 \& # Deep comparisons
435 \&
436 \& is([1, 2, 3], [1, 2, 3], "Deep comparison");
437 \&
438 \& #####################
439 \& # Comparing references
440 \&
441 \& my $ref = [1];
442 \& ref_is($ref, $ref, "Check that we have the same ref both times");
443 \&
444 \& #####################
445 \& # Things that are gone
446 \&
447 \& is([1], [1], "array comparison");
448 \& is({a => 1}, {a => 1}, "hash comparison");
449 \&
450 \& is([1, 3, 2], bag { item 1; item 2; item 3; end }, "set comparison");
451 \&
452 \& use Data::Dumper;
453 \& note Dumper([1, 2, 3]);
454 \&
455 \& {
456 \& package THING;
457 \& sub new { bless({}, shift) }
458 \& }
459 \&
460 \& my $thing = THING\->new;
461 \&
462 \& #####################
463 \& # Tools that changed
464 \&
465 \& isa_ok($thing, [\*(AqTHING\*(Aq], \*(Aqgot a THING\*(Aq);
466 \&
467 \& can_ok(_\|_PACKAGE_\|_, [qw/ok is/], "have expected subs");
468 .Ve
469 .SH "SEE ALSO"
470 .IX Header "SEE ALSO"
471 Test2::Manual \- Primary index of the manual.
472 .SH SOURCE
473 .IX Header "SOURCE"
474 The source code repository for Test2\-Manual can be found at
475 \&\fIhttps://github.com/Test\-More/test\-more/\fR.
476 .SH MAINTAINERS
477 .IX Header "MAINTAINERS"
478 .IP "Chad Granum <[email protected]>" 4
479 .IX Item "Chad Granum <[email protected]>"
480 .SH AUTHORS
481 .IX Header "AUTHORS"
482 .IP "Chad Granum <[email protected]>" 4
483 .IX Item "Chad Granum <[email protected]>"
484 .SH COPYRIGHT
485 .IX Header "COPYRIGHT"
486 Copyright Chad Granum <[email protected]>.
487 .PP
488 This program is free software; you can redistribute it and/or
489 modify it under the same terms as Perl itself.
490 .PP
491 See \fIhttp://dev.perl.org/licenses/\fR