NAME

Test::Stream::Manual::FromTestBuilder - Translation document for people moving from Test::More, Test::Simple, or other Test::Builder tools.

DESCRIPTION

This document covers things that are meaningful to someone switching from Test::More, Test::Simple, and other Test::Builder based tools. It approaches the situation as though you are converting an old test, or writing a new one. Instead of loading Test::More you will be loading Test::Stream with the recommended bundle:

use Test::Stream -V1;

...

WHAT IS (MOSTLY) THE SAME?

This is the list of stuff that has either not changed, or changed only in ways not likely to be noticed.

FUNCTIONS

ok

The signature is different, instead of ok($$;$) it is now ok($$;$@). The slurpy @ allows you to add diagnostics messages that will only be shown if the test fails. This allows you to attach custom diagnostics directly to a failing test.

Defined in Test::Stream::Plugin::Core.

diag

No differences

Defined in Test::Stream::Plugin::Core.

note

No differences

Defined in Test::Stream::Plugin::Core.

pass

No differences

Defined in Test::Stream::Plugin::Core.

fail

Signature changed from fail($) to fail($;@). Extra arguments are diagnostics that will be shown with your failing test.

Defined in Test::Stream::Plugin::Core.

done_testing

No longer accepts arguments. Most people did not know it could accept arguments in Test::More so it is unlikely to effect many people.

Defined in Test::Stream::Plugin::Core.

BAIL_OUT

No differences

Defined in Test::Stream::Plugin::Core.

skip

No differences

Defined in Test::Stream::Plugin::Core.

can_ok

No differences

Defined in Test::Stream::Plugin::Core.

BEHAVIOR

TAP is still the default output format.
You get similar if not identical diagnostics at the end of a failing test file.
You get file and line number for failed tests.

WHAT IS (SIGNIFICANTLY) DIFFERENT?

This is a list of very notable changes that are likely to hurt you if you are not aware of them.

FUNCTIONS

is

is_deeply

is and is_deeply have been combined. You can now use is for simple scalars, or nested data structures. This also means you can no longer use is to check that hash/array reference are the same exact reference, though you can check that they have the exact same data. If you actually want to check if 2 hash/array refs are the same or different you can use ref_is() or ref_is_not(), both of which are much safer for that purpose than is() ever was.

The signature has also been changed to add a slurpy '@' to the end for specifying extra diagnostics that only show up if the test fails.

The diagnostics have also been improved so that a table is shown with all the differences (default cap of 25 differences, this can be altered with the TS_MAX_DELTA environment variable).

Here is an example of a failing test:

is(
    { a => 1, b => 2, c => [ 'a', 'b', 'c' ]},
    { a => 2, b => 3, c => [ 'x', 'y', 'z' ]},
    "These are clearly different"
);

It produces:

not ok 1 - These are clearly different
# Failed test 'These are clearly different'
# at test.pl line 3.
# +--------+-----+----+-------+
# | PATH   | GOT | OP | CHECK |
# +--------+-----+----+-------+
# | {a}    | 1   | == | 2     |
# | {b}    | 2   | == | 3     |
# | {c}[0] | a   | eq | x     |
# | {c}[1] | b   | eq | y     |
# | {c}[2] | c   | eq | z     |
# +--------+-----+----+-------+

Notice that it gives you all the differences. It tells you the path of each difference within the structure, what it got, and what it was checking against. It also tells you what operator it used for the comparison, that way you will know if the problem is the comparison used rather than the values checked.

The final column is called 'CHECK' because there are extra tools provided by Test::Stream::Plugin::Compare that give you more control over how to compare values and structures, 'EXPECTED' does not work as a heading.

The table is smart about your screen size and formatting values displayed within. All whitespace apart from the ASCII single space is replaced with either its escape sequence, or its unicode number. If there is trailing whitespace the final whitespace character will also be replaced to make it clear to you it is there.

Defined in Test::Stream::Plugin::Compare.

like

like still works like it did before, like($var, qr/.../) will not need to be changed. However it has been changed much like is() in that it can be used to check deep data structures. However like is not as strict as is, and only checks for things you specify. In addition regexes and coderefs appearing in the second structure are used as checks rather than exact comparisons:

like(
    { a => 'aaa', b => 'bbb', c => ['a' .. 'z'], d => 'ddd' },
    {
        a => qr/a/,                  # regex is used to check the value
        b => sub { $_ eq 'bbb' },    # Code is run to check result
        c => [ 'a', 'b', 'c' ],      # Only the first 3 items are checked
        # hash key 'd' is ignored since we did not specify it
    },
    "Parts of the structure we care about match"
);

Defined in Test::Stream::Plugin::Compare.

plan

Only accepts a number of test expected to be run.

plan 5;

See skip_all for skipping an entire test.

Defined in Test::Stream::Plugin::Core.

skip_all

This is the new way to skip an entire test, it takes a reason as its argument.

skip_all 'Broken for now';

Defined in Test::Stream::Plugin::Core.

isa_ok

It was common for people to use this incorrectly in Test::More. It was reasonable to assume it worked like can_ok and accepted several package names. Instead the Test::More implementation used the third argument as an alternate name for the first. This has been changed to be consistent with can_ok and similar tools.

isa_ok($thing, 'My::Class', 'My::Subclass', ...);

Defined in Test::Stream::Plugin::Core.

subtest

Not loaded by default, you must ask for it:

use Test::Stream qw/-V1 Subtest/;

The default output has been changed:

ok 1 - Subtest Name {
    ok 1 - subtest result
    ok 2 - another result
    1..2
# }

The old output format can be used if requested:

use Test::Stream '-V1', 'Subtest' => ['streamed'];

Defined in Test::Stream::Plugin::Subtest.

WHAT IS COMPLETELY GONE?

These are no longer around for you to use.

FUNCTIONS

use_ok

require_ok

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.

new_ok

This is easy enough:

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

The utility of new_ok() is questionable at best.

eq_array

eq_hash

eq_set

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

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.

cmp_ok

It is easy to write:

ok($got == $want, "$got == $want");

cmp_eq did not buy very much more. There were added diagnostics, and they were indeed valuable. The issue is that the implementation for a cmp_ok that accepts arbitrary comparison operators is VERY complex. Further there are a great many edge cases to account for. Warnings that have to do with uninitialized or improper arguments to the operators also report to internals if not handled properly.

All these issues are solvable, but they lead to very complex, slow, and easily broken code. I have fixed bugs in the old cmp_ok implementation, and can tell you it is a mess. I have also written no less than 3 replacements for cmp_ok, all of which proved complex enough that I do not feel it is worth maintaining in Test::Stream core.

If you want cmp_ok badly enough you can write a plugin for it.

VARIABLES

$TODO

The $TODO variable is completely gone. Do not use it. Instead we have the todo() function. There are 2 ways to use the todo function:

Similar to old way:

TODO: {
    # Note, this is a lexical variable, not a package variable. Do not use
    # local. The todo will end when the variable is destroyed (at the end
    # of the scope, or when you assign something else, such as undef, to
    # the variable.
    my $todo = todo "These are not ready yet";

    ok(0, 'todo');
}

Another way:

todo 'These are not ready yet' => sub {
    ok(0, 'todo');
};

$Test::Builder::Level

See Test::Stream::Context for how Test:Stream solves the same problem.

BEHAVIOR

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.

WHAT ELSE DO I GET?

This is some new stuff you get for free!

FUNCTIONS

DOES_ok

Just like isa_ok and can_ok except it checks DOES instead of can or isa. All caps is used to reflect the UNIVERSAL property used, it also helps avoid conflicts with Moose related stuff.

Defined in Test::Stream::Plugin::Core.

ref_ok

Check that something is a ref, and optionally that it is a specific type of ref.

Defined in Test::Stream::Plugin::Core.

imported_ok

Check that the current namespace has the specified functions. This will not find inherited methods, only subs actually defined in the current namespace. It will NOT check that the subs came from another package.

This is a better alternative to can_ok when testing imports.

Defined in Test::Stream::Plugin::Core.

not_imported_ok

This checks that the specified functions are not available in the current namespace. It will ignore inherited methods, is only looks for subs in the current namespace.

Defined in Test::Stream::Plugin::Core.

ref_is

Check that 2 references are the same references, not a deep check, compares addresses of the 2 provided refs. Will fail if either argument is not a reference, or is undef.

Defined in Test::Stream::Plugin::Core.

ref_is_not

Check that 2 references are not the same references, not a deep check, compares addresses of the 2 provided refs. Will fail if either argument is not a reference, or is undef.

Defined in Test::Stream::Plugin::Core.

set_encoding

Can be used to set the encoding of TAP, and possibly other formatters.

use Test::Stream -V1;
use utf8;

set_encoding 'utf8';
# No wide character warnings
ok(1, '†');

Defined in Test::Stream::Plugin::Core.

context

This is the alternative to $Test::Builder::Level. See Test::Stream::Context for more info.

Defined in Test::Stream::Plugin::Context.

mock

This is a 1-stop shop for all your mocking needs. Mock classes, instances, etc. This is the next generation of mocking after Mock::Quick and borrows the good ideas from it. See the Mock plugin for more details, or for access to the capabilities using multiple functions instead of a single monolithic one.

Defined in Test::Stream::Plugin::Mock.

mocked

Used to check if something has been mocked using the Mock plugin.

Defined in Test::Stream::Plugin::Mock.

warning { ... }

Run the code and return the warning it is expected to produce. Dies if it gets too many warnings, or too few.

Defined in Test::Stream::Plugin::Warnings.

warns { ... }

Returns an arrayref of all the warnings from within the codeblock, undef if there are no warnings.

ok(!warns { ... }, "no warnings");

like(
    warns { ... },
    [
        qr/xxx/,
        qr/yyy/,
    ],
    "Got both expected warnings",
);

Defined in Test::Stream::Plugin::Warnings.

no_warnings { ... }

Returns false if the block produces warnings, true if there are none. This will also display the warnings if any occur.

ok(no_warnings { ... }, "got no warnings");

Defined in Test::Stream::Plugin::Warnings.

lives { ... }

Returns true if the block does not throw any exceptions. Returns false and displays the exception as a warning if the block does die.

ok(lives { ... }, "did not die");

Defined in Test::Stream::Plugin::Exception.

dies { ... }

Returns the exception produced by the block, or undef if it did not die.

like(
    dies { ... },
    qr/xxx/,
    "Got excpetion"
);

Defined in Test::Stream::Plugin::Exception.

BEHAVIOR

Forking/Threading support: Forking and threading in your tests will just work (so long as you use the 'IPC' plugin, which is included in the 'V1' bundle).

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

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

To install Test::Stream, copy and paste the appropriate command in to your terminal.

cpanm

cpanm Test::Stream

CPAN shell

perl -MCPAN -e shell
install Test::Stream

For more information on module installation, please visit the detailed CPAN module installation guide.

	Global
`s`	Focus search bar
`?`	Bring up this help dialog

	GitHub
`g` `p`	Go to pull requests
`g` `i`	go to github issues (only if github is preferred repository)

	POD
`g` `a`	Go to author
`g` `c`	Go to changes
`g` `i`	Go to issues
`g` `d`	Go to dist
`g` `r`	Go to repository/SCM
`g` `s`	Go to source
`g` `b`	Go to file browse

	Search terms
module: (e.g. module:Plugin)
distribution: (e.g. distribution:Dancer auth)
author: (e.g. author:SONGMU Redis)
version: (e.g. version:1.00)

NAME

DESCRIPTION

WHAT IS (MOSTLY) THE SAME?

FUNCTIONS

BEHAVIOR

WHAT IS (SIGNIFICANTLY) DIFFERENT?

FUNCTIONS

WHAT IS COMPLETELY GONE?

FUNCTIONS

VARIABLES

BEHAVIOR

WHAT ELSE DO I GET?

FUNCTIONS

BEHAVIOR

SOURCE

MAINTAINERS

AUTHORS

COPYRIGHT

Module Install Instructions