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.

    Migrating from Test::More
        Test::Stream::Manual::FromTestBuilder

    How to write tools for Test::Stream
        Test::Stream::Manual::Tooling

    Overview of Test-Stream components
        Test::Stream::Manual::Components

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:

    '-Classic' - The 'Classic' bundle.
        This one is probably your best bet when just starting out. This
        plugin closely resembles the functionality of Test::More.

        See Test::Stream::Bundle::Classic.

    '-V1' - The bundle used in Test::Streams tests.
        This one provides a lot more than the 'Classic' bundle, but is
        probably not suited to begginers. There are several notable
        differences from Test::More that can trip you up if you do not pay
        attention.

        See Test::Stream::Bundle::V1.

  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:

    '-Bundle',
        The "-" prefix indicates that the specified item is a bundle.
        Bundles live in the "Test::Stream::Bundle::" namespace. Each bundle
        is an independant module. You can specify any number of bundles, or
        none at all.

    ':Project'
        The ':' prefix indicates we are loading a project specific bundle,
        which means the module must be located in "t/lib/", "lib/", or the
        paths provided in the "TS_LB_PATH" environment variable. In the case
        of ':Project' it will look for "Test/Stream/Bundle/Project.pm" in
        "TS_LB_PATH", "t/lib/", then "lib/".

        This is a good way to create bundles useful to your project, but not
        really worth putting on CPAN.

    'MyPlugin'
        Arguments without a prefix are considered to be plugin names.
        Plugins are assumed to be in "Test::Stream::Plugin::", which is
        prefixed automatically for you.

    '+Fully::Qualified::Plugin'
        If you write a plugin, but put it in a non-standard namespace, you
        can use the fully qualified plugin namespace prefixed by '+'. Apart
        from the namespace treatment there is no difference in how the
        plugin is loaded or used.

    'SomePlugin' => \@ARGS
        Most plugins provide a fairly sane set of defaults when loaded.
        However some provide extras you need to request. When loading a
        plugin directly these would be the import arguments. If your plugin
        is followed by an arrayref the ref contents will be used as load
        arguments.

        Bundles may also specify arguments for plugins. You can override the
        bundles arguments by specifying your own. In these cases last wins,
        arguments are never merged. If multiple bundles are loaded, and
        several specify arguments to the same plugin, the same rules apply.

            use Test::Stream(
                '-BundleFoo',         # Arguments to 'Foo' get squashed by the next bundle
                '-BundleAlsoWithFoo', # Arguments to 'Foo' get squashed by the next line
                'Foo' => [...],       # These args win
            );

    '!UnwantedPlugin'
        This will blacklist the plugin so that it will not be used. The
        blacklist will block the plugin regardless of where it is listed.
        The blacklist only effects the statement in which it appears; if you
        load Test::Stream twice, the blacklist will only apply to the load
        in which it appears. You cannot override the blacklist items.

    'WantEverything' => '*'
        This will load the plugin with all options. The '*' gets turned into
        "['-all']" for you.

    'option' => ...
        Uncapitalized options without a "+", "-", or ":" prefix are reserved
        for use by the loader. Loaders that subclass Test::Stream can add
        options of their own.

        To define an option in your subclass simply add a "sub opt_NAME()"
        method. The method will receive several arguments:

            sub opt_foo {
                my $class = shift;
                my %params = @_;

                my $list  = $params{list};  # List of remaining plugins/args
                my $args  = $params{args};  # Hashref of {plugin => \@args}
                my $order = $params{order}; # Plugins to load, in order
                my $skip  = $params{skip};  # Hashref of plugins to skip {plugin => $bool}

                # Pull our arguments off the list given at load time
                my $foos_arg = shift @$list;

                # Add the 'Foo' plugin to the list of plugins to load, unless it is
                # present in the $args hash in which case it is already in order.
                push @$order => 'Foo' unless $args{'Foo'};

                # Set the args for the plugin
                $args->{Foo} = [$foos_arg];

                $skip{Fox} = 1; # Make sure the Fox plugin never loads.
            }

  AVAILABLE OPTIONS
    class => $CLASS
        Shortcut for the Test::Stream::Plugin::Class plugin.

    skip_without => $MODULE
    skip_without => 'v5.008'
    skip_without => [$MODULE => $VERSION]
        Shortcut for the Test::Stream::Plugin::SkipWithout plugin. Unlike
        normal specification of a plugin, this APPENDS arguments. This one
        can be called several time and the arguments will be appended.

        Note: specifying 'SkipWithout' the normal way after a call to
        'skip_without' will wipe out the argument that have accumulated so
        far.

    srand => $SEED
        Shortcut to set the random seed.

  SEE ALSO
    For more about plugins and bundles see the following docs:

    plugins
        Test::Stream::Plugin - Provides tools to help write plugins.

    bundles
        Test::Stream::Bundle - Provides tools to help write bundles.

  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:

    TS_FORMATTER="Foo"
    TS_FORMATTER="+Foo::Bar"
        This can be used to set the output formatter. By default
        Test::Stream::Formatter::TAP is used.

        Normally 'Test::Stream::Formatter::' is prefixed to the value in the
        environment variable:

            $ TS_FORMATTER='TAP' perl test.t     # Use the Test::Stream::Formatter::TAP formatter
            $ TS_FORMATTER='Foo' perl test.t     # Use the Test::Stream::Formatter::Foo formatter

        If you want to specify a full module name you use the '+' prefix:

            $ TS_FORMATTER='+Foo::Bar' perl test.t     # Use the Foo::Bar formatter

    TS_KEEP_TEMPDIR=1
        Some IPC drivers make use of temporary directories, this variable
        will tell Test::Stream to keep the directory when the tests are
        complete.

    TS_LB_PATH="./:./lib/:..."
        This allows you to provide paths where Test::Stream will search for
        project specific bundles. These paths are NOT added to @INC.

    TS_MAX_DELTA=25
        This is used by the Test::Stream::Plugin::Compare plugin. This
        specifies the max number of differences to show when data structures
        do not match.

    TS_TERM_SIZE=80
        This is used to set the width of the terminal. This is used when
        building tables of diagnostics. The default is 80, unless
        Term::ReadKey is installed in which case the value is determined
        dynamically.

    TS_WORKFLOW=42
    TS_WORKFLOW="foo"
        This is used by the Test::Stream::Plugin::Spec plugin to specify
        which test block should be run, only the specified block will be
        run.

    TS_RAND_SEED=44523
        This only works when used with the Test::Stream::Plugin::SRand
        plugin. This lets you specify the random seed to use.

    HARNESS_ACTIVE
        This is typically set by TAP::Harness and other harnesses. You
        should not need to set this yourself.

    HARNESS_IS_VERBOSE
        This is typically set by TAP::Harness and other harnesses. You
        should not need to set this yourself.

    NO_TRACE_MASK=1
        This variable is specified by Trace::Mask. Test::Stream uses the
        Trace::Mask specification to mask some stack frames from traces
        generated by Trace::Mask compliant tools. Setting this variable will
        force a full stack trace whenever a trace is produced.

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

MAINTAINERS
    Chad Granum <exodist@cpan.org>

AUTHORS
    Chad Granum <exodist@cpan.org>

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/