/ 
Test-Stream-1.302027
River stage one • 1 direct dependent • 1 total dependent
/ Test::Stream::Plugin::Core

NAME

Test::Stream::Plugin::Core - Test::Stream implementation of the core testing tools.

DEPRECATED

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

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

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 qw/Core/;

set_encoding('utf8');

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

use Data::Dumper;
imported_ok qw/Dumper/;
not_imported_ok qw/dumper/;

# 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");

# 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;

EXPORTS

All subs are exported by default.

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.

imported_ok(@SUB_NAMES)

Check that the specified subs have been defined in the current namespace. This will NOT find inherited subs, the subs must be in the current namespace.

not_imported_ok(@SUB_NAMES)

Check that the specified subs have NOT been defined in the current namespace. This will NOT find inherited subs, the subs must be in the current namespace.

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.

ref_is($ref1, $ref2, $name)

Verify that 2 references are the exact same reference.

ref_is_not($ref1, $ref2, $name)

Verify that 2 references are not the exact same reference.

cmp_ok($got, $op, $expect)
cmp_ok($got, $op, $expect, $name)
cmp_ok($got, $op, $expect, $name, @diag)

Compare $got to $expect using the operator specified in $op. This is effectively a eval "\$got $op \$expect" with some other stuff to make it more sane. This is useful for comparing numbers, overloaded objects, etc.

Overloading Note: Your input is passed as-is to the comparison. In the event that the comparison fails between 2 overloaded objects, the diagnostics will try to show you the overload form that was used in comparisons. It is possible that the diagnostics will be wrong, though attempts have been made to improve them since Test::More.

Exceptions: If the comparison results in an exception then the test will fail and the exception will be shown.

cmp_ok has an internal list of operators it supports. If you provide an unsupported operator it will issue a warning. You can add operators to the %Test::Stream::Plugin::Core::OPS hash, the key should be the operator, and the value should either be 'str' for string comparison operators, 'num' for numeric operators, or any other true value for other operators.

Supported operators:

== (num)
!= (num)
>= (num)
<= (num)
> (num)
< (num)
<=> (num)
eq (str)
ne (str)
gt (str)
lt (str)
ge (str)
le (str)
cmp (str)
!~ (str)
=~ (str)
&&
||
xor
or
and
//
&
|
~~

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");
}
set_encoding($encoding)

This will set the encoding to whatever you specify. This will only effect the output of the current formatter, which is usually your TAP output formatter.

SEE ALSO

Test::Stream::Plugin::Subtest

Subtest support

Test::Stream::Plugin::Intercept

Tools for intercepting events, exceptions, warnings, etc.

Test::Stream::Bundle::Tester

Tools for testing your test tools

Test::Stream::Plugin::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://dev.perl.org/licenses/