1Test2::Manual::Testing:U:sMeirgrCaotnitnrgi(b3u)ted PerlTeDsotc2u:m:eMnatnautailo:n:Testing::Migrating(3)
2
3
4

NAME

6       Test2::Manual::Testing::Migrating - How to migrate existing tests from
7       Test::More to Test2.
8

DESCRIPTION

10       This tutorial covers the conversion of an existing test. This tutorial
11       assumes you have a test written using Test::More.
12

LEGACY TEST

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

BOILERPLATE

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

SIMPLE ASSERTIONS

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

TODO

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

DEEP COMPARISONS

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

COMPARING REFERENCES

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

TOOLS THAT ARE GONE

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

TOOLS THAT HAVE CHANGED

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

FINAL VERSION

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

SEE ALSO

359       Test2::Manual - Primary index of the manual.
360

SOURCE

362       The source code repository for Test2-Manual can be found at
363       https://github.com/Test-More/Test2-Suite/.
364

MAINTAINERS

366       Chad Granum <exodist@cpan.org>
367

AUTHORS

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.34.0                      2022-03-0T8est2::Manual::Testing::Migrating(3)
Impressum