1Test::Stream::Manual::FUrsoemrTeCsotnBturiilbduetre(d3T)Peesrtl::DSotcruemaemn:t:aMtainounal::FromTestBuilder(3)
2
6 Test::Stream::Manual::FromTestBuilder - Translation document for people
7 moving from Test::More, Test::Simple, or other Test::Builder tools.
8
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 use Test::Stream -Classic;
17 ...
19 If you do not like the idea of using Test::Stream as a loader you can
21 load the classic bundle directly:
22 use Test::Stream::Bundle::Classic;
24 ...
26 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
33 This is the list of stuff that has either not changed, or changed only
34 in ways not likely to be noticed.
35 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 Defined in Test::Stream::Plugin::Core.
43 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 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 isnt
54 Very little has changed, same changes as "is()".
55 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 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 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 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 like
77 Not much has changed, added @ to signature for diagnostics.
78 unlike
80 Not much has changed, added @ to signature for diagnostics.
81 diag
83 No differences
84 Defined in Test::Stream::Plugin::Core.
86 note
88 No differences
89 Defined in Test::Stream::Plugin::Core.
91 pass
93 No differences
94 Defined in Test::Stream::Plugin::Core.
96 fail
98 Signature changed from fail($) to "fail($;@)". Extra arguments are
99 diagnostics that will be shown with your failing test.
100 Defined in Test::Stream::Plugin::Core.
102 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 Defined in Test::Stream::Plugin::Core.
109 BAIL_OUT
111 No differences
112 Defined in Test::Stream::Plugin::Core.
114 skip
116 No differences
117 Defined in Test::Stream::Plugin::Core.
119 can_ok
121 No differences
122 Defined in Test::Stream::Plugin::Core.
124 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
132 This is a list of very notable changes that are likely to hurt you if
133 you are not aware of them.
134 FUNCTIONS
136 plan
137 Only accepts a number of test expected to be run.
138 plan 5;
140 See "skip_all" for skipping an entire test.
142 Defined in Test::Stream::Plugin::Core.
144 skip_all
146 This is the new way to skip an entire test, it takes a reason as
147 its argument.
148 skip_all 'Broken for now';
150 Defined in Test::Stream::Plugin::Core.
152 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 isa_ok($thing, 'My::Class', 'My::Subclass', ...);
161 Defined in Test::Stream::Plugin::Core.
163 subtest
165 The default output has been changed:
166 ok 1 - Subtest Name {
168 ok 1 - subtest result
169 ok 2 - another result
170 1..2
171 # }
172 The old output format can be used if requested:
174 use Test::Stream '-Classic', 'Subtest' => ['streamed'];
176 Defined in Test::Stream::Plugin::Subtest.
178 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 Defined in Test::Stream::Plugin::Core.
185
187 These are no longer around for you to use.
188 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 new_ok
199 This is easy enough:
200 ok(my $one = $class->new(@args), "NAME");
202 The utility of "new_ok()" is questionable at best.
204 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 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 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 Similar to old way:
224 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 ok(0, 'todo');
233 }
234 Another way:
236 todo 'These are not ready yet' => sub {
238 ok(0, 'todo');
239 };
240 $Test::Builder::Level
242 See Test::Stream::Context for how <Test:Stream> solves the same
243 problem.
244 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
254 This is some new stuff you get for free!
255 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 Defined in Test::Stream::Plugin::Core.
263 ref_ok
265 Check that something is a ref, and optionally that it is a specific
266 type of ref.
267 Defined in Test::Stream::Plugin::Core.
269 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 This is a better alternative to "can_ok" when testing imports.
277 Defined in Test::Stream::Plugin::Core.
279 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 Defined in Test::Stream::Plugin::Core.
286 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 Defined in Test::Stream::Plugin::Core.
293 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 Defined in Test::Stream::Plugin::Core.
300 set_encoding
302 Can be used to set the encoding of TAP, and possibly other
303 formatters.
304 use Test::Stream -Classic;
306 use utf8;
307 set_encoding 'utf8';
309 # No wide character warnings
310 ok(1, '†');
311 Defined in Test::Stream::Plugin::Core.
313 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
320 The source code repository for Test::Stream can be found at
321 http://github.com/Test-More/Test-Stream/.
322
324 Chad Granum <exodist@cpan.org>
325
327 Chad Granum <exodist@cpan.org>
328
330 Copyright 2015 Chad Granum <exodist7@gmail.com>.
331 This program is free software; you can redistribute it and/or modify it
333 under the same terms as Perl itself.
334 See http://dev.perl.org/licenses/
336perl v5.36.0 2022-T0e7s-t2:2:Stream::Manual::FromTestBuilder(3)