The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.
 / 
Test-Stream-1.302006
River stage one • 1 direct dependent • 1 total dependent
7 ++
/ Test::Stream

NAME

Test::Stream - Experimental successor to Test::More and Test::Builder.

EXPERIMENTAL CODE WARNING

This is an experimental release! Test-Stream, and all its components are still in an experimental phase. This dist has been released to cpan in order to allow testers and early adopters the chance to write experimental new tools with it, or to add experimental support for it into old tools.

PLEASE DO NOT COMPLETELY CONVERT OLD TOOLS YET. This experimental release is very likely to see a lot of code churn. API's may break at any time. Test-Stream should NOT be depended on by any toolchain level tools until the experimental phase is over.

DESCRIPTION

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

The new Testing library to replace Test::More. This library is directly built on new internals instead of Test::Builder.

This module implements most of the same functionality as Test::More, but since changing to this library from Test::More is not automatic, some incompatible API changes have been made. If you decide to replace Test::More in existing test files, you may have to update some function calls.

SYNOPSIS

    use Test::Stream;

    plan($num); # Optional, set a plan

    # skip all tests in some condition
    skip_all("do not run") if $cond;

    if ($passing) {
        pass('a passing test');
    }
    else {
        fail('a failing test');
    }

    ok($x, "simple test");

    is($a, $b, "'eq' test");

    isnt($a, $b, "'ne' test");

    like($x, qr/xxx/, "Check that $x matches the regex");

    unlike($x, qr/xxx/, "Check that $x does not match the regex");

    cmp_ok($a, '==', $b, "Comparison of the specified type");

    is_deeply($a, ..., "deep structure test");

    mostly_like($a, ..., "Less strict, more helpful structure test");

    # Check that the class or object has the specified methods defined.
    can_ok($class_or_obj, @methods);

    # Check that the class or object is or subclasses the specified packages
    isa_ok($class_or_obj, @packages);

    # Check that the class or object consumes the specified roles.
    does_ok($class_or_obj, @roles);

    # Check that $ref is a HASH reference
    ref_ok($ref, 'HASH', 'Must be a hash')

    # The preferred way to plan
    done_testing;

PERFORMANCE NOTE

There is an XS module available that provides a notable performance boost. Test::Stream::XS, when installed, will be used to replace several key subs with xs implementations. The XS module is completely optional.

IPC NOTE

Test::Stream::IPC is loaded by default, as such forking and threading should work fine so long as you did not fork or start your threads before loading Test::Stream.

However! polling is not turned on by default as it can result in significant slowdowns on purely serial code. This means that results from child processes and threads will not usually be seen until the main process/thread is complete. If you want to see results as they happen you need to turn on polling.

This will turn on polling:

    use Test::Stream::IPC 'polling';

An alternative would be to use the cull() function also provided by Test::Stream::IPC to manually cull results where you want them:

    use Test::Stream::IPC 'cull';
    ...
    cull()
    ...

EXPORTS

ASSERTIONS

ok($bool)
ok($bool, $name)
ok($bool, $name, @diag)

Simple assertion. If $bool is true the test passes, if it is false the test fails. The test name is optional, and all arguments after the name are added as diagnostics message if and only if the test fails. If the test passes all the diagnostics arguments will be ignored.

pass()
pass($name)

Fire off a passing test (a single Ok event). The name is optional

fail()
fail($name)
fail($name, @diag)

Fire off a failing test (a single Ok event). The name and diagnostics are optional.

is($a, $b)
is($a, $b, $name)
is($a, $b, $name, @diag)

This does a comparison of $a and $b using the eq operator. This is usually what you want, but can be the wrong choice when comparing numbers that may be equal, but represented differently, ie '1.0' eq '1' will fail.

Name and diag are optional. Diag is only used if the test fails.

isnt($a, $b)
isnt($a, $b, $name)
isnt($a, $b, $name, @diag)

Same as is() except the ne operator is used.

like($string, $pattern)
like($string, $pattern, $name)
like($string, $pattern, $name, @diag)

Check that $string matches $pattern using the =~ operator.

Name and diag are optional. Diag is only used if the test fails.

unlike($string, $pattern)
unlike($string, $pattern, $name)
unlike($string, $pattern, $name, @diag)

Same as like() except that the check is that the string does not match the pattern. The !~ operator is used instead of the =~ operator.

cmp_ok($a, $op, $b)
cmp_ok($a, $op, $b, $name)
cmp_ok($a, $op, $b, $name, @diag)

Compare 2 variables using the specified comparison operator. Name and diag are optional, diag is only used if the check fails.

is_deeply($a, $b)
is_deeply($a, $b, $name)

Do a deep comparison between $a and $b. All hashrefs and arrayrefs are checked element by element. If an element is in one but not the other it will fail. If there is any difference at all the test fails.

This attempts ot be smart about numbers vs string vs references when doing comparions, so it uses eq most times, but == if both sides look like numbers, or if both sides are references other than hash/array.

mostly_like($a, $b)
mostly_like($a, $b, $name)

This is much like is_deeply except that it is more friendly. This will ignore hash elements in $a that are not listed in $b. If you put a regex into $b then the same item in $a will be verified against that regex. If you put a coderef in $b it will be called with the value recieved and its return value will determine if it is a match or not.

    # This passes, 'xxx' is checked against the regex
    mostly_like(
        { a => 'xxx' },
        { a => qr/xxx/ }
    );

    # This passes, the coderef is run
    mostly_like(
        { a => 'xxx' }.
        { a => sub { $_[0] eq 'xxx' } }
    );

    # This passes, the extra fields are ignored
    mostly_like(
        { a => 'xxx', _private => 'stuff' },
        { a => 'xxx' },
    );

    # This does B<NOT> pass, extra array elements are a problem
    mostly_like(
        [ qw/a b c d/ ],
        [ qw/a b c/   ]
    );
can_ok($thing, @methods)

This checks that $thing (either a class name, or a blessed instance) has the specified methods.

isa_ok($thing, @classes)

This checks that $thing (either a class name, or a blessed instance) is or subclasses the specified classes.

does_ok($thing, @roles)

This checks that $thing (either a class name, or a blessed instance) does the specified roles.

ref_ok($thing)
ref_ok($thing, $type)
ref_ok($thing, $type, $name)

This checks that $thing is a reference. If $type is specified then it will check that $thing is that type of reference.

DIAGNOSTICS

diag(@messages)

Write diagnostics messages. All items in @messages will be joined into a single string with no seperator. When using TAP diagnostics are sent to STDERR.

note(@messages)

Write note-diagnostics messages. All items in @messages will be joined into a single string with no seperator. When using TAP note-diagnostics are sent to STDOUT.

PLANNING

plan($num)

Set the number of tests that are expected. This must be done first or last, never in the middle of testing.

skip_all($reason)

Set the plan to 0 with a reason, then exit true. This should be used before any tests are run.

done_testing

Used to mark the end of testing. This is a safe way to have a dynamic or unknown number of tests.

BAIL_OUT($reason)

Something has gone horribly wrong, stop everything, kill all threads and processes, end the process with a false exit status.

META

$todo = todo($reason)
todo $reason => sub { ... }

This is used to mark some results as TODO. TODO means that the test may fail, but will not cause the overall test suite to fail.

There are 2 ways to use this, the first is to use a codeblock, the TODO will only apply to the codeblock.

    ok(1, "before"); # Not TODO

    todo 'this will fail' => sub {
        # This is TODO, as is any other test in this block.
        ok(0, "blah");
    };

    ok(1, "after"); # Not TODO

The other way is to use a scoped variable, TODO will end when the variable is destroyed or set to undef.

    ok(1, "before"); # Not TODO

    {
        my $todo = todo 'this will fail';

        # This is TODO, as is any other test in this block.
        ok(0, "blah");
    };

    ok(1, "after"); # Not TODO

This is the same thing, but without the {...} scope.

    ok(1, "before"); # Not TODO

    my $todo = todo 'this will fail';

    ok(0, "blah"); # TODO

    $todo = undef;

    ok(1, "after"); # Not TODO
skip($why)
skip($why, $count)

This is used to skip some tests. This requires you to wrap your tests in a block labeled SKIP:, this is somewhat magical. If no $count is specified then it will issue a single result. If you specify $count it will issue that many results.

    SKIP: {
        skip "This will wipe your drive";

        # This never gets run:
        ok(!system('sudo rm -rf /'), "Wipe drive");
    }

NOTABLE DIFFERENCES FROM Test::More

API Change: 'strict' and 'warnings' are enabled for you

No more need to type:

    use strict;
    use warnings;

Using Test::Stream does it for you:

    use Test::Stream;
API Change: Cannot set plan at import

done_testing is the preferred way to plan. However if you really want a plan you can use the plan() or skip_all functions. Setting the plan at compile time resulted in bugs in the past (primarily with subtests that loaded external files), moving away from that API shortcut helps to make things cleaner.

API Change: isa_ok($thing, @classes)

isa_ok used to take a thing, a class, and an alternate name for thing. It tried to be overly clever and broke from expectations set by can_ok.

Also changed such that you cannot use this to check the reftype of $thing. See ref_ok() for checking item reftypes.

API Change: done_testing() does not take args

Most people were unaware, but done_testing() in Test::More could take the number of expected tests as an argument. This feature was rarely used, and suprisingly complicated to implement.

API Change: plan() arguments

plan() now only takes the expected number of tests. If you want to skip all the tests use skip_all(). There is no way to set 'no plan', use done_testing() instead.

API Change: subtest is in a different library

Look at Test::Stream::Subtest if you want to use subtests.

API Change: no $TODO variable
API Added: $todo = todo($reason)

$TODO is not imported, and will be ignored. Instead use my $todo = todo($reason). This will work similarly to the old api where $TODO was localized in that the todo goes away when $todo is unset or destroyed.

    {
        my $todo = todo('foo');
        ok(0, "this is todo");
    }
    ok(1, "this is not todo");

Or:

    my $todo = todo('foo');
    ok(0, "this is todo");
    $todo = undef; # Unset todo.
    ok(1, "this is not todo");
API Added: does_ok($class, @roles)

Same as isa_ok and can_ok except that it calls $thing->does(...) instead of $thing->can(...) or $thing->isa(...).

API Added: skip_all

There is now a skip_all() function that can be used to skip all tests.

API Removed: use_ok($class, @args)
API Removed: require_ok($class, $version)

Errors loading modules cause the test to die anyway, so just load them, if they do not work the test will fail. Making a seperate API for this is a wasted effort. Also doing this requires the functions to guess if you provided a module name, or filename, and then munging the input to figure out what actually needs to be loaded.

API Removed: new_ok($class, \@args, $name)

This is easy enough:

    ok(my $one = $class->new(@args), "NAME");

The utility of c<new_ok()> is questionable at best.

API Removed: eq_array eq_hash eq_set

Test::More itself discourages you from using these, so we are not carrying them forward.

API Removed: explain

This method was copied in an API-incompatible way from Test::Most. This created an incompatability issue between the 2 libraries and made a real mess of things. There is value in a tool like this, but if it is added it will be added with a new name to avoid conflicts.

SEE ALSO

Test::Stream::Subtest

Subtest support

Test::Stream::Intercept

Tools for intercepting events, exceptions, warnings, etc.

Test::Stream::Tester

Tools for testing your test tools

Test::Stream::IPC

Use this module directly for more control over concurrency.

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://www.perl.com/perl/misc/Artistic.html