1Test::Stream(3)       User Contributed Perl Documentation      Test::Stream(3)
2
3
4

NAME

6       Test::Stream - **DEPRECATED** See Test2-Suite instead
7

DEPRECATED

9       This distribution is deprecated in favor of Test2, Test2::Suite, and
10       Test2::Workflow.
11
12       See Test::Stream::Manual::ToTest2 for a conversion guide.
13

***READ THIS FIRST***

15       This is not a drop-in replacement for Test::More.
16
17       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
22       See Test::Stream::Manual::FromTestBuilder if you are coming from
23       Test::More or Test::Simple and want a quick translation.
24

***COMBINING WITH OLD TOOLS***

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

MANUAL

32       The manual is still being written, but a couple pages are already
33       available.
34
35       Migrating from Test::More
36           Test::Stream::Manual::FromTestBuilder
37
38       How to write tools for Test::Stream
39           Test::Stream::Manual::Tooling
40
41       Overview of Test-Stream components
42           Test::Stream::Manual::Components
43

DESCRIPTION

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
51       Bundles and plugins can be used directly, it is not necessary to use
52       Test::Stream to load them.
53

SYNOPSIS

55           use Test::Stream -Classic;
56
57           ok(1, "This is a pass");
58           ok(0, "This is a fail");
59
60           done_testing;
61
62       The '-' above means load the specified bundle, this is the same as:
63
64           use Test::Stream::Bundle::Classic;
65
66           ok(1, "This is a pass");
67           ok(0, "This is a fail");
68
69           done_testing;
70
71   SUBCLASS
72           package My::Loader;
73           use strict;
74           use warnings;
75
76           use parent 'Test::Stream';
77
78           # 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
88           1;
89

IMPORTANT NOTE

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
96       '-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
100           See Test::Stream::Bundle::Classic.
101
102       '-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
108           See Test::Stream::Bundle::V1.
109
110   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

PLUGINS, BUNDLES, AND OPTIONS

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
126       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
132       Plugins and bundles can be distinguished easily:
133
134           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
145       Explanation:
146
147       '-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
153       ':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
160           This is a good way to create bundles useful to your project, but
161           not really worth putting on CPAN.
162
163       '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
168       '+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
174       '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
181           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
187               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
193       '!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
200       'WantEverything' => '*'
201           This will load the plugin with all options. The '*' gets turned
202           into "['-all']" for you.
203
204       '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
209           To define an option in your subclass simply add a "sub opt_NAME()"
210           method. The method will receive several arguments:
211
212               sub opt_foo {
213                   my $class = shift;
214                   my %params = @_;
215
216                   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
221                   # Pull our arguments off the list given at load time
222                   my $foos_arg = shift @$list;
223
224                   # 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
228                   # Set the args for the plugin
229                   $args->{Foo} = [$foos_arg];
230
231                   $skip{Fox} = 1; # Make sure the Fox plugin never loads.
232               }
233
234   AVAILABLE OPTIONS
235       class => $CLASS
236           Shortcut for the Test::Stream::Plugin::Class plugin.
237
238       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
245           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
249       srand => $SEED
250           Shortcut to set the random seed.
251
252   SEE ALSO
253       For more about plugins and bundles see the following docs:
254
255       plugins
256           Test::Stream::Plugin - Provides tools to help write plugins.
257
258       bundles
259           Test::Stream::Bundle - Provides tools to help write bundles.
260
261   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
269       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

ENVIRONMENT VARIABLES

276       This is a list of environment variables Test::Stream looks at:
277
278       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
283           Normally 'Test::Stream::Formatter::' is prefixed to the value in
284           the environment variable:
285
286               $ 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
289           If you want to specify a full module name you use the '+' prefix:
290
291               $ TS_FORMATTER='+Foo::Bar' perl test.t     # Use the Foo::Bar formatter
292
293       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
298       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
302       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
307       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
313       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
319       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
323       HARNESS_ACTIVE
324           This is typically set by TAP::Harness and other harnesses. You
325           should not need to set this yourself.
326
327       HARNESS_IS_VERBOSE
328           This is typically set by TAP::Harness and other harnesses. You
329           should not need to set this yourself.
330
331       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

SOURCE

338       The source code repository for Test::Stream can be found at
339       http://github.com/Test-More/Test-Stream/.
340

MAINTAINERS

342       Chad Granum <exodist@cpan.org>
343

AUTHORS

345       Chad Granum <exodist@cpan.org>
346
348       Copyright 2015 Chad Granum <exodist7@gmail.com>.
349
350       This program is free software; you can redistribute it and/or modify it
351       under the same terms as Perl itself.
352
353       See http://dev.perl.org/licenses/
354
355
356
357perl v5.28.0                      2016-02-05                   Test::Stream(3)
Impressum