1Test2::Manual::Testing:U:sMeirgrCaotnitnrgi(b3u)ted PerlTeDsotc2u:m:eMnatnautailo:n:Testing::Migrating(3)
2
6 Test2::Manual::Testing::Migrating - How to migrate existing tests from
7 Test::More to Test2.
8
10 This tutorial covers the conversion of an existing test. This tutorial
11 assumes you have a test written using Test::More.
12
14 This tutorial will be converting this example test one section at a
15 time:
16 "t/example.t":
18 #####################
20 # Boilerplate
21 use strict;
23 use warnings;
24 use Test::More tests => 14;
26 use_ok 'Scalar::Util';
28 require_ok 'Exporter';
29 #####################
31 # Simple assertions (no changes)
32 ok(1, "pass");
34 is("apple", "apple", "Simple string compare");
36 like("foo bar baz", qr/bar/, "Regex match");
38 #####################
40 # Todo
41 {
43 local $TODO = "These are todo";
44 ok(0, "oops");
46 }
47 #####################
49 # Deep comparisons
50 is_deeply([1, 2, 3], [1, 2, 3], "Deep comparison");
52 #####################
54 # Comparing references
55 my $ref = [1];
57 is($ref, $ref, "Check that we have the same ref both times");
58 #####################
60 # Things that are gone
61 ok(eq_array([1], [1]), "array comparison");
63 ok(eq_hash({a => 1}, {a => 1}), "hash comparison");
64 ok(eq_set([1, 3, 2], [1, 2, 3]), "set comparison");
65 note explain([1, 2, 3]);
67 {
69 package THING;
70 sub new { bless({}, shift) }
71 }
72 my $thing = new_ok('THING');
74 #####################
76 # Tools that changed
77 isa_ok($thing, 'THING', '$thing');
79 can_ok(__PACKAGE__, qw/ok is/);
81
83 BEFORE:
84 use strict;
86 use warnings;
87 use Test::More tests => 14;
89 use_ok 'Scalar::Util';
91 require_ok 'Exporter';
92 AFTER:
94 use Test2::V0;
96 plan(11);
97 use Scalar::Util;
99 require Exporter;
100 Replace Test::More with Test2::V0
102 Test2::V0 is the recommended bundle. In a full migration you will
103 want to replace Test::More with the Test2::V0 bundle.
104 Note: You should always double check the latest Test2 to see if
106 there is a new recommended bundle. When writing a new test you
107 should always use the newest Test::V# module. Higher numbers are
108 newer version.
109 Stop using use_ok()
111 "use_ok()" has been removed. a "use MODULE" statement will throw an
112 exception on failure anyway preventing the test from passing.
113 If you REALLY want/need to assert that the file loaded you can use
115 the ok module:
116 use ok 'Scalar::Util';
118 The main difference here is that there is a space instead of an
120 underscore.
121 Stop using require_ok()
123 "require_ok" has been removed just like "use_ok". There is no ok
124 module equivalent here. Just use "require".
125 Remove strict/warnings (optional)
127 The Test2::V0 bundle turns strict and warnings on for you.
128 Change where the plan is set
130 Test2 does not allow you to set the plan at import. In the old code
131 you would pass "tests => 11" as an import argument. In Test2 you
132 either need to use the "plan()" function to set the plan, or use
133 "done_testing()" at the end of the test.
134 If your test already uses "done_testing()" you can keep that and no
136 plan changes are necessary.
137 Note: We are also changing the plan from 14 to 11, that is because
139 we dropped "use_ok", "require_ok", and we will be dropping one more
140 later on. This is why "done_testing()" is recommended over a set
141 plan.
142
144 The vast majority of assertions will not need any changes:
145 #####################
147 # Simple assertions (no changes)
148 ok(1, "pass");
150 is("apple", "apple", "Simple string compare");
152 like("foo bar baz", qr/bar/, "Regex match");
154
156 {
157 local $TODO = "These are todo";
158 ok(0, "oops");
160 }
161 The $TODO package variable is gone. You now have a "todo()" function.
163 There are 2 ways this can be used:
165 todo $reason => sub { ... }
167 todo "These are todo" => sub {
168 ok(0, "oops");
169 };
170 This is the cleanest way to do a todo. This will make all
172 assertions inside the codeblock into TODO assertions.
173 { my $TODO = todo $reason; ... }
175 {
176 my $TODO = todo "These are todo";
177 ok(0, "oops");
179 }
180 This is a system that emulates the old way. Instead of modifying a
182 global $TODO variable you create a todo object with the "todo()"
183 function and assign it to a lexical variable. Once the todo object
184 falls out of scope the TODO ends.
185
187 is_deeply([1, 2, 3], [1, 2, 3], "Deep comparison");
188 Deep comparisons are easy, simply replace "is_deeply()" with "is()".
190 is([1, 2, 3], [1, 2, 3], "Deep comparison");
192
194 my $ref = [1];
195 is($ref, $ref, "Check that we have the same ref both times");
196 The "is()" function provided by Test::More forces both arguments into
198 strings, which makes this a comparison of the reference addresses.
199 Test2's "is()" function is a deep comparison, so this will still pass,
200 but fails to actually test what we want (that both references are the
201 same exact ref, not just identical structures.)
202 We now have the "ref_is()" function that does what we really want, it
204 ensures both references are the same reference. This function does the
205 job better than the original, which could be thrown off by string
206 overloading.
207 my $ref = [1];
209 ref_is($ref, $ref, "Check that we have the same ref both times");
210
212 ok(eq_array([1], [1]), "array comparison");
213 ok(eq_hash({a => 1}, {a => 1}), "hash comparison");
214 ok(eq_set([1, 3, 2], [1, 2, 3]), "set comparison");
215 note explain([1, 2, 3]);
217 {
219 package THING;
220 sub new { bless({}, shift) }
221 }
222 my $thing = new_ok('THING');
224 "eq_array", "eq_hash" and "eq_set" have been considered deprecated for
226 a very long time, Test2 does not provide them at all. Instead you can
227 just use "is()":
228 is([1], [1], "array comparison");
230 is({a => 1}, {a => 1}, "hash comparison");
231 "eq_set" is a tad more complicated, see Test2::Tools::Compare for an
233 explanation:
234 is([1, 3, 2], bag { item 1; item 2; item 3; end }, "set comparison");
236 "explain()" has a rocky history. There have been arguments about how it
238 should work. Test2 decided to simply not include "explain()" to avoid
239 the arguments. You can instead directly use Data::Dumper:
240 use Data::Dumper;
242 note Dumper([1, 2, 3]);
243 "new_ok()" is gone. The implementation was complicated, and did not add
245 much value:
246 {
248 package THING;
249 sub new { bless({}, shift) }
250 }
251 my $thing = THING->new;
253 ok($thing, "made a new thing");
254 The complete section after the conversion is:
256 is([1], [1], "array comparison");
258 is({a => 1}, {a => 1}, "hash comparison");
259 is([1, 3, 2], bag { item 1; item 2; item 3; end }, "set comparison");
260 use Data::Dumper;
262 note Dumper([1, 2, 3]);
263 {
265 package THING;
266 sub new { bless({}, shift) }
267 }
268 my $thing = THING->new;
270 ok($thing, "made a new thing");
271
273 isa_ok($thing, 'THING', '$thing');
274 can_ok(__PACKAGE__, qw/ok is/);
276 In Test::More these functions are very confusing, and most people use
278 them wrong!
279 "isa_ok()" from Test::More takes a thing, a class/reftype to check, and
281 then uses the third argument as an alternative display name for the
282 first argument (NOT a test name!).
283 "can_ok()" from Test::More is not consistent with "isa_ok" as all
285 arguments after the first are subroutine names.
286 Test2 fixes this by making both functions consistent and obvious:
288 isa_ok($thing, ['THING'], 'got a THING');
290 can_ok(__PACKAGE__, [qw/ok is/], "have expected subs");
292 You will note that both functions take a thing, an arrayref as the
294 second argument, then a test name as the third argument.
295
297 #####################
298 # Boilerplate
299 use Test2::V0;
301 plan(11);
302 use Scalar::Util;
304 require Exporter;
305 #####################
307 # Simple assertions (no changes)
308 ok(1, "pass");
310 is("apple", "apple", "Simple string compare");
312 like("foo bar baz", qr/bar/, "Regex match");
314 #####################
316 # Todo
317 todo "These are todo" => sub {
319 ok(0, "oops");
320 };
321 #####################
323 # Deep comparisons
324 is([1, 2, 3], [1, 2, 3], "Deep comparison");
326 #####################
328 # Comparing references
329 my $ref = [1];
331 ref_is($ref, $ref, "Check that we have the same ref both times");
332 #####################
334 # Things that are gone
335 is([1], [1], "array comparison");
337 is({a => 1}, {a => 1}, "hash comparison");
338 is([1, 3, 2], bag { item 1; item 2; item 3; end }, "set comparison");
340 use Data::Dumper;
342 note Dumper([1, 2, 3]);
343 {
345 package THING;
346 sub new { bless({}, shift) }
347 }
348 my $thing = THING->new;
350 #####################
352 # Tools that changed
353 isa_ok($thing, ['THING'], 'got a THING');
355 can_ok(__PACKAGE__, [qw/ok is/], "have expected subs");
357
359 Test2::Manual - Primary index of the manual.
360
362 The source code repository for Test2-Manual can be found at
363 https://github.com/Test-More/Test2-Suite/.
364
366 Chad Granum <exodist@cpan.org>
367
369 Chad Granum <exodist@cpan.org>
370
372 Copyright 2018 Chad Granum <exodist@cpan.org>.
373 This program is free software; you can redistribute it and/or modify it
375 under the same terms as Perl itself.
376 See http://dev.perl.org/licenses/
378perl v5.34.0 2021-11-1T6est2::Manual::Testing::Migrating(3)