Debian Codegraph @

upstream/debian-unstable/man3/Test2::Manual::Testing::Migrating.3perl

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