1Test::Stream(3) User Contributed Perl Documentation Test::Stream(3)
2
6 Test::Stream - **DEPRECATED** See Test2-Suite instead
7
9 This distribution is deprecated in favor of Test2, Test2::Suite, and
10 Test2::Workflow.
11 See Test::Stream::Manual::ToTest2 for a conversion guide.
13
15 This is not a drop-in replacement for Test::More.
16 Adoption of Test::Stream instead of continuing to use Test::More is a
18 choice. Liberty has been taken to make significant API changes.
19 Replacing "use Test::More;" with "use Test::Stream;" will not work for
20 more than the most trivial of test files.
21 See Test::Stream::Manual::FromTestBuilder if you are coming from
23 Test::More or Test::Simple and want a quick translation.
24
26 At the moment you cannot use Test::Stream and Test::Builder based tools
27 in the same test scripts unless you install the TRIAL Test::More
28 version. Once the Test::More trials go stable you will be able to
29 combine tools from both frameworks.
30
32 The manual is still being written, but a couple pages are already
33 available.
34 Migrating from Test::More
36 Test::Stream::Manual::FromTestBuilder
37 How to write tools for Test::Stream
39 Test::Stream::Manual::Tooling
40 Overview of Test-Stream components
42 Test::Stream::Manual::Components
43
45 This is the primary interface for loading Test::Stream based tools.
46 This module is responsible for loading bundles and plugins for the
47 tools you want. By default you are required to specify at least 1
48 plugin or bundle to load. You can subclass Test::Stream to have your
49 own default plugins or bundles.
50 Bundles and plugins can be used directly, it is not necessary to use
52 Test::Stream to load them.
53
55 use Test::Stream -Classic;
56 ok(1, "This is a pass");
58 ok(0, "This is a fail");
59 done_testing;
61 The '-' above means load the specified bundle, this is the same as:
63 use Test::Stream::Bundle::Classic;
65 ok(1, "This is a pass");
67 ok(0, "This is a fail");
68 done_testing;
70 SUBCLASS
72 package My::Loader;
73 use strict;
74 use warnings;
75 use parent 'Test::Stream';
77 # The 'default' sub just returns a list of import arguments to use byu
79 # default.
80 sub default {
81 return qw{
82 -Bundle1
83 Plugin1
84 ...
85 };
86 }
87 1;
89
91 "use Test::Stream;" will fail. You MUST specify at least one bundle or
92 plugin. If you do not specify any then none would be imported and that
93 is obviously not what you want. If you are new to Test::Stream then you
94 should probably start with one of the pre-made bundles:
95 '-Classic' - The 'Classic' bundle.
97 This one is probably your best bet when just starting out. This
98 plugin closely resembles the functionality of Test::More.
99 See Test::Stream::Bundle::Classic.
101 '-V1' - The bundle used in Test::Streams tests.
103 This one provides a lot more than the 'Classic' bundle, but is
104 probably not suited to begginers. There are several notable
105 differences from Test::More that can trip you up if you do not pay
106 attention.
107 See Test::Stream::Bundle::V1.
109 WHY NOT MAKE A DEFAULT BUNDLE OR SET OF PLUGINS?
111 Future Proofing. If we decide in the future that a specific plugin or
112 tool is harmful we would like to be able to remove it. Making a tool
113 part of the default set will effectively make it unremovable as doing
114 so would break compatability. Instead we have the bundle system, and a
115 set of starter bundles, if a bundle proves ot be harmful we can change
116 the recommendation of the docs.
117
119 Test::Stream tools should be created as plugins. This is not enforced,
120 nothing prevents you from writing Test::Stream tools that are not
121 plugins. However writing your tool as a plugin will help your module
122 to play well with other tools. Writing a plugin also makes it easier
123 for you to create private or public bundles that reduce your
124 boilerplate.
125 Bundles are very simple. At its core a bundle is simply a list of other
127 bundles, plugins, and arguments to those plugins. Much like hash
128 declaration a 'last wins' approach is used; if you load 2 bundles that
129 share a plugin with different arguments, the last set of arguments
130 wins.
131 Plugins and bundles can be distinguished easily:
133 use Test::Stream(
135 '-Bundle', # Bundle ('-')
136 ':Project', # Project specific bundle (':')
137 'MyPlugin', # Plugin name (no prefix)
138 '+Fully::Qualified::Plugin', # (Plugin in unusual path)
139 'SomePlugin' => ['arg1', ...], # (Plugin with args)
140 '!UnwantedPlugin', # Do not load this plugin
141 'WantEverything' => '*', # Load the plugin with all options
142 'option' => ..., # Option to the loader (Test::Stream)
143 );
144 Explanation:
146 '-Bundle',
148 The "-" prefix indicates that the specified item is a bundle.
149 Bundles live in the "Test::Stream::Bundle::" namespace. Each bundle
150 is an independant module. You can specify any number of bundles,
151 or none at all.
152 ':Project'
154 The ':' prefix indicates we are loading a project specific bundle,
155 which means the module must be located in "t/lib/", "lib/", or the
156 paths provided in the "TS_LB_PATH" environment variable. In the
157 case of ':Project' it will look for "Test/Stream/Bundle/Project.pm"
158 in "TS_LB_PATH", "t/lib/", then "lib/".
159 This is a good way to create bundles useful to your project, but
161 not really worth putting on CPAN.
162 'MyPlugin'
164 Arguments without a prefix are considered to be plugin names.
165 Plugins are assumed to be in "Test::Stream::Plugin::", which is
166 prefixed automatically for you.
167 '+Fully::Qualified::Plugin'
169 If you write a plugin, but put it in a non-standard namespace, you
170 can use the fully qualified plugin namespace prefixed by '+'. Apart
171 from the namespace treatment there is no difference in how the
172 plugin is loaded or used.
173 'SomePlugin' => \@ARGS
175 Most plugins provide a fairly sane set of defaults when loaded.
176 However some provide extras you need to request. When loading a
177 plugin directly these would be the import arguments. If your plugin
178 is followed by an arrayref the ref contents will be used as load
179 arguments.
180 Bundles may also specify arguments for plugins. You can override
182 the bundles arguments by specifying your own. In these cases last
183 wins, arguments are never merged. If multiple bundles are loaded,
184 and several specify arguments to the same plugin, the same rules
185 apply.
186 use Test::Stream(
188 '-BundleFoo', # Arguments to 'Foo' get squashed by the next bundle
189 '-BundleAlsoWithFoo', # Arguments to 'Foo' get squashed by the next line
190 'Foo' => [...], # These args win
191 );
192 '!UnwantedPlugin'
194 This will blacklist the plugin so that it will not be used. The
195 blacklist will block the plugin regardless of where it is listed.
196 The blacklist only effects the statement in which it appears; if
197 you load Test::Stream twice, the blacklist will only apply to the
198 load in which it appears. You cannot override the blacklist items.
199 'WantEverything' => '*'
201 This will load the plugin with all options. The '*' gets turned
202 into "['-all']" for you.
203 'option' => ...
205 Uncapitalized options without a "+", "-", or ":" prefix are
206 reserved for use by the loader. Loaders that subclass Test::Stream
207 can add options of their own.
208 To define an option in your subclass simply add a "sub opt_NAME()"
210 method. The method will receive several arguments:
211 sub opt_foo {
213 my $class = shift;
214 my %params = @_;
215 my $list = $params{list}; # List of remaining plugins/args
217 my $args = $params{args}; # Hashref of {plugin => \@args}
218 my $order = $params{order}; # Plugins to load, in order
219 my $skip = $params{skip}; # Hashref of plugins to skip {plugin => $bool}
220 # Pull our arguments off the list given at load time
222 my $foos_arg = shift @$list;
223 # Add the 'Foo' plugin to the list of plugins to load, unless it is
225 # present in the $args hash in which case it is already in order.
226 push @$order => 'Foo' unless $args{'Foo'};
227 # Set the args for the plugin
229 $args->{Foo} = [$foos_arg];
230 $skip{Fox} = 1; # Make sure the Fox plugin never loads.
232 }
233 AVAILABLE OPTIONS
235 class => $CLASS
236 Shortcut for the Test::Stream::Plugin::Class plugin.
237 skip_without => $MODULE
239 skip_without => 'v5.008'
240 skip_without => [$MODULE => $VERSION]
241 Shortcut for the Test::Stream::Plugin::SkipWithout plugin. Unlike
242 normal specification of a plugin, this APPENDS arguments. This one
243 can be called several time and the arguments will be appended.
244 Note: specifying 'SkipWithout' the normal way after a call to
246 'skip_without' will wipe out the argument that have accumulated so
247 far.
248 srand => $SEED
250 Shortcut to set the random seed.
251 SEE ALSO
253 For more about plugins and bundles see the following docs:
254 plugins
256 Test::Stream::Plugin - Provides tools to help write plugins.
257 bundles
259 Test::Stream::Bundle - Provides tools to help write bundles.
260 EXPLANATION AND HISTORY
262 Test::Stream has learned from Test::Builder. For a time it was common
263 for people to write "Test::*" tools that bundled other "Test::*" tools
264 with them when loaded. For a short time this seemed like a good idea.
265 This was quickly seen to be a problem when people wanted to use
266 features of multiple testing tools that both made incompatible
267 assumptions about other modules you might want to load.
268 Test::Stream does not recreate this wild west approach to testing tools
270 and bundles. Test::Stream recognises the benefits of bundles, but
271 provides a much more sane approach. Bundles and Tools are kept
272 separate, this way you can always use tools without being forced to
273 adopt the authors ideal bundle.
274
276 This is a list of environment variables Test::Stream looks at:
277 TS_FORMATTER="Foo"
279 TS_FORMATTER="+Foo::Bar"
280 This can be used to set the output formatter. By default
281 Test::Stream::Formatter::TAP is used.
282 Normally 'Test::Stream::Formatter::' is prefixed to the value in
284 the environment variable:
285 $ TS_FORMATTER='TAP' perl test.t # Use the Test::Stream::Formatter::TAP formatter
287 $ TS_FORMATTER='Foo' perl test.t # Use the Test::Stream::Formatter::Foo formatter
288 If you want to specify a full module name you use the '+' prefix:
290 $ TS_FORMATTER='+Foo::Bar' perl test.t # Use the Foo::Bar formatter
292 TS_KEEP_TEMPDIR=1
294 Some IPC drivers make use of temporary directories, this variable
295 will tell Test::Stream to keep the directory when the tests are
296 complete.
297 TS_LB_PATH="./:./lib/:..."
299 This allows you to provide paths where Test::Stream will search for
300 project specific bundles. These paths are NOT added to @INC.
301 TS_MAX_DELTA=25
303 This is used by the Test::Stream::Plugin::Compare plugin. This
304 specifies the max number of differences to show when data
305 structures do not match.
306 TS_TERM_SIZE=80
308 This is used to set the width of the terminal. This is used when
309 building tables of diagnostics. The default is 80, unless
310 Term::ReadKey is installed in which case the value is determined
311 dynamically.
312 TS_WORKFLOW=42
314 TS_WORKFLOW="foo"
315 This is used by the Test::Stream::Plugin::Spec plugin to specify
316 which test block should be run, only the specified block will be
317 run.
318 TS_RAND_SEED=44523
320 This only works when used with the Test::Stream::Plugin::SRand
321 plugin. This lets you specify the random seed to use.
322 HARNESS_ACTIVE
324 This is typically set by TAP::Harness and other harnesses. You
325 should not need to set this yourself.
326 HARNESS_IS_VERBOSE
328 This is typically set by TAP::Harness and other harnesses. You
329 should not need to set this yourself.
330 NO_TRACE_MASK=1
332 This variable is specified by Trace::Mask. Test::Stream uses the
333 Trace::Mask specification to mask some stack frames from traces
334 generated by Trace::Mask compliant tools. Setting this variable
335 will force a full stack trace whenever a trace is produced.
336
338 The source code repository for Test::Stream can be found at
339 http://github.com/Test-More/Test-Stream/.
340
342 Chad Granum <exodist@cpan.org>
343
345 Chad Granum <exodist@cpan.org>
346
348 Copyright 2015 Chad Granum <exodist7@gmail.com>.
349 This program is free software; you can redistribute it and/or modify it
351 under the same terms as Perl itself.
352 See http://dev.perl.org/licenses/
354perl v5.34.0 2021-07-27 Test::Stream(3)