1Test::Stream::Manual::FUrsoemrTeCsotnBturiilbduetre(d3T)Peesrtl::DSotcruemaemn:t:aMtainounal::FromTestBuilder(3)
2
3
4

NAME

6       Test::Stream::Manual::FromTestBuilder - Translation document for people
7       moving from Test::More, Test::Simple, or other Test::Builder tools.
8

DESCRIPTION

10       This document covers things that are meaningful to someone switching
11       from Test::More, Test::Simple, and other Test::Builder based tools. It
12       approaches the situation as though you are converting an old test, or
13       writing a new one. Instead of loading Test::More you will be loading
14       Test::Stream with the 'Classic' bundle:
15
16           use Test::Stream -Classic;
17
18           ...
19
20       If you do not like the idea of using Test::Stream as a loader you can
21       load the classic bundle directly:
22
23           use Test::Stream::Bundle::Classic;
24
25           ...
26
27       The 'Classic' bundle is a bundle intended for people who are familiar
28       with Test::More and do not want to change how they do things. You could
29       also take a look at the 'V1' bundle, Test::Stream::Bundle::V1 and see
30       if it is more to your liking.
31

WHAT IS (MOSTLY) THE SAME?

33       This is the list of stuff that has either not changed, or changed only
34       in ways not likely to be noticed.
35
36   FUNCTIONS
37       ok  The signature is different, instead of "ok($$;$)" it is now
38           "ok($$;$@)". The slurpy "@" allows you to add diagnostics messages
39           that will only be shown if the test fails. This allows you to
40           attach custom diagnostics directly to a failing test.
41
42           Defined in Test::Stream::Plugin::Core.
43
44       is  Very little has changed as far as how this is used, but there are a
45           lot of changes under the hood, as well the signature has been
46           changed much like "ok()"'s in that you can add diagnostics at the
47           end to display in case of failure.
48
49           This function will stringify the first 2 arguments and run a
50           stgring comparison. If both arguments are endefined that will also
51           be considered a pass.
52
53       isnt
54           Very little has changed, same changes as "is()".
55
56       is_deeply
57           Very little has changed as far as how this is used, but there are a
58           lot of changes under the hood, as well the signature has been
59           changed much like "ok()"'s in that you can add diagnostics at the
60           end to display in case of failure.
61
62           This function will do a deep comparison recursing into hashrefs,
63           arrayrefs, and scalar refs. Any other values will be compared using
64           string comparisons.
65
66           Diagnostics have been improved as well, you will get a table with
67           all the differences betwene the structures. Normally this will stop
68           at 25 differences, but the number can be tweaked using the
69           $ENV{TS_MAX_DELTA} environment variable.
70
71           Note: under the hood this uses the Test::Stream::Compare library,
72           as such it will gladly accept any advanced check objects you
73           produce with that library.  In practice this has no effect at all
74           on you unless you use the Compare library tools directly.
75
76       like
77           Not much has changed, added @ to signature for diagnostics.
78
79       unlike
80           Not much has changed, added @ to signature for diagnostics.
81
82       diag
83           No differences
84
85           Defined in Test::Stream::Plugin::Core.
86
87       note
88           No differences
89
90           Defined in Test::Stream::Plugin::Core.
91
92       pass
93           No differences
94
95           Defined in Test::Stream::Plugin::Core.
96
97       fail
98           Signature changed from fail($) to "fail($;@)". Extra arguments are
99           diagnostics that will be shown with your failing test.
100
101           Defined in Test::Stream::Plugin::Core.
102
103       done_testing
104           No longer accepts arguments. Most people did not know it could
105           accept arguments in Test::More so it is unlikely to effect many
106           people.
107
108           Defined in Test::Stream::Plugin::Core.
109
110       BAIL_OUT
111           No differences
112
113           Defined in Test::Stream::Plugin::Core.
114
115       skip
116           No differences
117
118           Defined in Test::Stream::Plugin::Core.
119
120       can_ok
121           No differences
122
123           Defined in Test::Stream::Plugin::Core.
124
125   BEHAVIOR
126       TAP is still the default output format.
127       You get similar if not identical diagnostics at the end of a failing
128       test file.
129       You get file and line number for failed tests.
130

WHAT IS (SIGNIFICANTLY) DIFFERENT?

132       This is a list of very notable changes that are likely to hurt you if
133       you are not aware of them.
134
135   FUNCTIONS
136       plan
137           Only accepts a number of test expected to be run.
138
139               plan 5;
140
141           See "skip_all" for skipping an entire test.
142
143           Defined in Test::Stream::Plugin::Core.
144
145       skip_all
146           This is the new way to skip an entire test, it takes a reason as
147           its argument.
148
149               skip_all 'Broken for now';
150
151           Defined in Test::Stream::Plugin::Core.
152
153       isa_ok
154           It was common for people to use this incorrectly in Test::More. It
155           was reasonable to assume it worked like "can_ok" and accepted
156           several package names. Instead the Test::More implementation used
157           the third argument as an alternate name for the first. This has
158           been changed to be consistent with "can_ok" and similar tools.
159
160               isa_ok($thing, 'My::Class', 'My::Subclass', ...);
161
162           Defined in Test::Stream::Plugin::Core.
163
164       subtest
165           The default output has been changed:
166
167               ok 1 - Subtest Name {
168                   ok 1 - subtest result
169                   ok 2 - another result
170                   1..2
171               # }
172
173           The old output format can be used if requested:
174
175               use Test::Stream '-Classic', 'Subtest' => ['streamed'];
176
177           Defined in Test::Stream::Plugin::Subtest.
178
179       cmp_ok
180           Usage is still the same. Internals have been heavily modified to
181           enhance diagnostics. There is also now a list of supported
182           operators, warnings are issued if you use an unsupported one.
183
184           Defined in Test::Stream::Plugin::Core.
185

WHAT IS COMPLETELY GONE?

187       These are no longer around for you to use.
188
189   FUNCTIONS
190       use_ok
191       require_ok
192           Errors loading modules cause the test to die anyway, so just load
193           them, if they do not work the test will fail. Making a separate API
194           for this is a wasted effort. Also doing this requires the functions
195           to guess if you provided a module name, or filename, and then
196           munging the input to figure out what actually needs to be loaded.
197
198       new_ok
199           This is easy enough:
200
201               ok(my $one = $class->new(@args), "NAME");
202
203           The utility of "new_ok()" is questionable at best.
204
205       eq_array
206       eq_hash
207       eq_set
208           Test::More itself discourages you from using these, so we are not
209           carrying them forward.
210
211       explain
212           This method was copied in an API-incompatible way from Test::Most.
213           This created an incompatability issue between the 2 libraries and
214           made a real mess of things. There is value in a tool like this, but
215           if it is added it will be added with a new name to avoid conflicts.
216
217   VARIABLES
218       $TODO
219           The $TODO variable is completely gone. Do not use it. Instead we
220           have the "todo()" function. There are 2 ways to use the todo
221           function:
222
223           Similar to old way:
224
225               TODO: {
226                   # Note, this is a lexical variable, not a package variable. Do not use
227                   # local. The todo will end when the variable is destroyed (at the end
228                   # of the scope, or when you assign something else, such as undef, to
229                   # the variable.
230                   my $todo = todo "These are not ready yet";
231
232                   ok(0, 'todo');
233               }
234
235           Another way:
236
237               todo 'These are not ready yet' => sub {
238                   ok(0, 'todo');
239               };
240
241       $Test::Builder::Level
242           See Test::Stream::Context for how <Test:Stream> solves the same
243           problem.
244
245   BEHAVIOR
246       plan at import
247           "done_testing" is the preferred way to plan. However if you really
248           want a plan you can use the "plan()" or "skip_all" functions.
249           Setting the plan at compile time resulted in bugs in the past
250           (primarily with subtests that loaded external files), moving away
251           from that API shortcut helps to make things cleaner.
252

WHAT ELSE DO I GET?

254       This is some new stuff you get for free!
255
256   FUNCTIONS
257       DOES_ok
258           Just like "isa_ok" and "can_ok" except it checks "DOES" instead of
259           "can" or "isa". All caps is used to reflect the UNIVERSAL property
260           used, it also helps avoid conflicts with Moose related stuff.
261
262           Defined in Test::Stream::Plugin::Core.
263
264       ref_ok
265           Check that something is a ref, and optionally that it is a specific
266           type of ref.
267
268           Defined in Test::Stream::Plugin::Core.
269
270       imported_ok
271           Check that the current namespace has the specified functions. This
272           will not find inherited methods, only subs actually defined in the
273           current namespace. It will NOT check that the subs came from
274           another package.
275
276           This is a better alternative to "can_ok" when testing imports.
277
278           Defined in Test::Stream::Plugin::Core.
279
280       not_imported_ok
281           This checks that the specified functions are not available in the
282           current namespace. It will ignore inherited methods, is only looks
283           for subs in the current namespace.
284
285           Defined in Test::Stream::Plugin::Core.
286
287       ref_is
288           Check that 2 references are the same references, not a deep check,
289           compares addresses of the 2 provided refs. Will fail if either
290           argument is not a reference, or is undef.
291
292           Defined in Test::Stream::Plugin::Core.
293
294       ref_is_not
295           Check that 2 references are not the same references, not a deep
296           check, compares addresses of the 2 provided refs. Will fail if
297           either argument is not a reference, or is undef.
298
299           Defined in Test::Stream::Plugin::Core.
300
301       set_encoding
302           Can be used to set the encoding of TAP, and possibly other
303           formatters.
304
305               use Test::Stream -Classic;
306               use utf8;
307
308               set_encoding 'utf8';
309               # No wide character warnings
310               ok(1, '†');
311
312           Defined in Test::Stream::Plugin::Core.
313
314   BEHAVIOR
315       Forking/Threading support
316           Forking and threading in your tests will just work (so long as you
317           use the 'IPC' plugin, which is included in the 'Classic' bundle).
318

SOURCE

320       The source code repository for Test::Stream can be found at
321       http://github.com/Test-More/Test-Stream/.
322

MAINTAINERS

324       Chad Granum <exodist@cpan.org>
325

AUTHORS

327       Chad Granum <exodist@cpan.org>
328
330       Copyright 2015 Chad Granum <exodist7@gmail.com>.
331
332       This program is free software; you can redistribute it and/or modify it
333       under the same terms as Perl itself.
334
335       See http://dev.perl.org/licenses/
336
337
338
339perl v5.32.1                      2021-T0e1s-t2:7:Stream::Manual::FromTestBuilder(3)
Impressum