1Test2::Manual::Testing:U:sMeirgrCaotnitnrgi(b3u)ted PerlTeDsotc2u:m:eMnatnautailo:n:Testing::Migrating(3)
2
3
4
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
17 "t/example.t":
18
19 #####################
20 # Boilerplate
21
22 use strict;
23 use warnings;
24
25 use Test::More tests => 14;
26
27 use_ok 'Scalar::Util';
28 require_ok 'Exporter';
29
30 #####################
31 # Simple assertions (no changes)
32
33 ok(1, "pass");
34
35 is("apple", "apple", "Simple string compare");
36
37 like("foo bar baz", qr/bar/, "Regex match");
38
39 #####################
40 # Todo
41
42 {
43 local $TODO = "These are todo";
44
45 ok(0, "oops");
46 }
47
48 #####################
49 # Deep comparisons
50
51 is_deeply([1, 2, 3], [1, 2, 3], "Deep comparison");
52
53 #####################
54 # Comparing references
55
56 my $ref = [1];
57 is($ref, $ref, "Check that we have the same ref both times");
58
59 #####################
60 # Things that are gone
61
62 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
66 note explain([1, 2, 3]);
67
68 {
69 package THING;
70 sub new { bless({}, shift) }
71 }
72
73 my $thing = new_ok('THING');
74
75 #####################
76 # Tools that changed
77
78 isa_ok($thing, 'THING', '$thing');
79
80 can_ok(__PACKAGE__, qw/ok is/);
81
83 BEFORE:
84
85 use strict;
86 use warnings;
87
88 use Test::More tests => 14;
89
90 use_ok 'Scalar::Util';
91 require_ok 'Exporter';
92
93 AFTER:
94
95 use Test2::V0;
96 plan(11);
97
98 use Scalar::Util;
99 require Exporter;
100
101 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
105 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
110 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
114 If you REALLY want/need to assert that the file loaded you can use
115 the ok module:
116
117 use ok 'Scalar::Util';
118
119 The main difference here is that there is a space instead of an
120 underscore.
121
122 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
126 Remove strict/warnings (optional)
127 The Test2::V0 bundle turns strict and warnings on for you.
128
129 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
135 If your test already uses "done_testing()" you can keep that and no
136 plan changes are necessary.
137
138 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
146 #####################
147 # Simple assertions (no changes)
148
149 ok(1, "pass");
150
151 is("apple", "apple", "Simple string compare");
152
153 like("foo bar baz", qr/bar/, "Regex match");
154
156 {
157 local $TODO = "These are todo";
158
159 ok(0, "oops");
160 }
161
162 The $TODO package variable is gone. You now have a "todo()" function.
163
164 There are 2 ways this can be used:
165
166 todo $reason => sub { ... }
167 todo "These are todo" => sub {
168 ok(0, "oops");
169 };
170
171 This is the cleanest way to do a todo. This will make all
172 assertions inside the codeblock into TODO assertions.
173
174 { my $TODO = todo $reason; ... }
175 {
176 my $TODO = todo "These are todo";
177
178 ok(0, "oops");
179 }
180
181 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
189 Deep comparisons are easy, simply replace "is_deeply()" with "is()".
190
191 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
197 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
203 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
208 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
216 note explain([1, 2, 3]);
217
218 {
219 package THING;
220 sub new { bless({}, shift) }
221 }
222
223 my $thing = new_ok('THING');
224
225 "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
229 is([1], [1], "array comparison");
230 is({a => 1}, {a => 1}, "hash comparison");
231
232 "eq_set" is a tad more complicated, see Test2::Tools::Compare for an
233 explanation:
234
235 is([1, 3, 2], bag { item 1; item 2; item 3; end }, "set comparison");
236
237 "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
241 use Data::Dumper;
242 note Dumper([1, 2, 3]);
243
244 "new_ok()" is gone. The implementation was complicated, and did not add
245 much value:
246
247 {
248 package THING;
249 sub new { bless({}, shift) }
250 }
251
252 my $thing = THING->new;
253 ok($thing, "made a new thing");
254
255 The complete section after the conversion is:
256
257 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
261 use Data::Dumper;
262 note Dumper([1, 2, 3]);
263
264 {
265 package THING;
266 sub new { bless({}, shift) }
267 }
268
269 my $thing = THING->new;
270 ok($thing, "made a new thing");
271
273 isa_ok($thing, 'THING', '$thing');
274
275 can_ok(__PACKAGE__, qw/ok is/);
276
277 In Test::More these functions are very confusing, and most people use
278 them wrong!
279
280 "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
284 "can_ok()" from Test::More is not consistent with "isa_ok" as all
285 arguments after the first are subroutine names.
286
287 Test2 fixes this by making both functions consistent and obvious:
288
289 isa_ok($thing, ['THING'], 'got a THING');
290
291 can_ok(__PACKAGE__, [qw/ok is/], "have expected subs");
292
293 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
300 use Test2::V0;
301 plan(11);
302
303 use Scalar::Util;
304 require Exporter;
305
306 #####################
307 # Simple assertions (no changes)
308
309 ok(1, "pass");
310
311 is("apple", "apple", "Simple string compare");
312
313 like("foo bar baz", qr/bar/, "Regex match");
314
315 #####################
316 # Todo
317
318 todo "These are todo" => sub {
319 ok(0, "oops");
320 };
321
322 #####################
323 # Deep comparisons
324
325 is([1, 2, 3], [1, 2, 3], "Deep comparison");
326
327 #####################
328 # Comparing references
329
330 my $ref = [1];
331 ref_is($ref, $ref, "Check that we have the same ref both times");
332
333 #####################
334 # Things that are gone
335
336 is([1], [1], "array comparison");
337 is({a => 1}, {a => 1}, "hash comparison");
338
339 is([1, 3, 2], bag { item 1; item 2; item 3; end }, "set comparison");
340
341 use Data::Dumper;
342 note Dumper([1, 2, 3]);
343
344 {
345 package THING;
346 sub new { bless({}, shift) }
347 }
348
349 my $thing = THING->new;
350
351 #####################
352 # Tools that changed
353
354 isa_ok($thing, ['THING'], 'got a THING');
355
356 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
374 This program is free software; you can redistribute it and/or modify it
375 under the same terms as Perl itself.
376
377 See http://dev.perl.org/licenses/
378
379
380
381perl v5.30.0 2019-07-2T6est2::Manual::Testing::Migrating(3)