search

Test-More / Test-Stream

DEPRECATED see test2
3 stars 5 forks source link

readme

NAME

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

DEPRECATED

This distribution is deprecated in favor of Test2, Test2::Suite, and Test2::Workflow.

See Test::Stream::Manual::ToTest2 for a conversion guide.

***READ THIS FIRST***

This is not a drop-in replacement for Test::More.

Adoption of Test::Stream instead of continuing to use Test::More is a choice. Liberty has been taken to make significant API changes. Replacing use Test::More; with use Test::Stream; will not work for more than the most trivial of test files.

See Test::Stream::Manual::FromTestBuilder if you are coming from Test::More or Test::Simple and want a quick translation.

***COMBINING WITH OLD TOOLS***

At the moment you cannot use Test::Stream and Test::Builder based tools in the same test scripts unless you install the TRIAL Test::More version. Once the Test::More trials go stable you will be able to combine tools from both frameworks.

MANUAL

The manual is still being written, but a couple pages are already available.

DESCRIPTION

This is the primary interface for loading Test::Stream based tools. This module is responsible for loading bundles and plugins for the tools you want. By default you are required to specify at least 1 plugin or bundle to load. You can subclass Test::Stream to have your own default plugins or bundles.

Bundles and plugins can be used directly, it is not necessary to use Test::Stream to load them.

SYNOPSIS

use Test::Stream -Classic;

ok(1, "This is a pass");
ok(0, "This is a fail");

done_testing;

The '-' above means load the specified bundle, this is the same as:

use Test::Stream::Bundle::Classic;

ok(1, "This is a pass");
ok(0, "This is a fail");

done_testing;

SUBCLASS

package My::Loader;
use strict;
use warnings;

use parent 'Test::Stream';

# The 'default' sub just returns a list of import arguments to use byu
# default.
sub default {
    return qw{
        -Bundle1
        Plugin1
        ...
    };
}

1;

IMPORTANT NOTE

use Test::Stream; will fail. You MUST specify at least one bundle or plugin. If you do not specify any then none would be imported and that is obviously not what you want. If you are new to Test::Stream then you should probably start with one of the pre-made bundles:

WHY NOT MAKE A DEFAULT BUNDLE OR SET OF PLUGINS?

Future Proofing. If we decide in the future that a specific plugin or tool is harmful we would like to be able to remove it. Making a tool part of the default set will effectively make it unremovable as doing so would break compatability. Instead we have the bundle system, and a set of starter bundles, if a bundle proves ot be harmful we can change the recommendation of the docs.

PLUGINS, BUNDLES, AND OPTIONS

Test::Stream tools should be created as plugins. This is not enforced, nothing prevents you from writing Test::Stream tools that are not plugins. However writing your tool as a plugin will help your module to play well with other tools. Writing a plugin also makes it easier for you to create private or public bundles that reduce your boilerplate.

Bundles are very simple. At its core a bundle is simply a list of other bundles, plugins, and arguments to those plugins. Much like hash declaration a 'last wins' approach is used; if you load 2 bundles that share a plugin with different arguments, the last set of arguments wins.

Plugins and bundles can be distinguished easily:

use Test::Stream(
    '-Bundle',                      # Bundle ('-')
    ':Project',                     # Project specific bundle (':')
    'MyPlugin',                     # Plugin name (no prefix)
    '+Fully::Qualified::Plugin',    # (Plugin in unusual path)
    'SomePlugin' => ['arg1', ...],  # (Plugin with args)
    '!UnwantedPlugin',              # Do not load this plugin
    'WantEverything' => '*',        # Load the plugin with all options
    'option' => ...,                # Option to the loader (Test::Stream)
);

Explanation:

AVAILABLE OPTIONS

SEE ALSO

For more about plugins and bundles see the following docs:

EXPLANATION AND HISTORY

Test::Stream has learned from Test::Builder. For a time it was common for people to write Test::* tools that bundled other Test::* tools with them when loaded. For a short time this seemed like a good idea. This was quickly seen to be a problem when people wanted to use features of multiple testing tools that both made incompatible assumptions about other modules you might want to load.

Test::Stream does not recreate this wild west approach to testing tools and bundles. Test::Stream recognises the benefits of bundles, but provides a much more sane approach. Bundles and Tools are kept separate, this way you can always use tools without being forced to adopt the authors ideal bundle.

ENVIRONMENT VARIABLES

This is a list of environment variables Test::Stream looks at:

SOURCE

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

MAINTAINERS

AUTHORS

COPYRIGHT

Copyright 2015 Chad Granum <exodist7@gmail.com>.

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

See http://dev.perl.org/licenses/