The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.

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 'Classic' bundle:

    use Test::Stream -Classic;

    ...

If you do not like the idea of using Test::Stream as a loader you can load the classic bundle directly:

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

    ...

The 'Classic' bundle is a bundle intended for people who are familiar with Test::More and do not want to change how they do things. You could also take a look at the 'V1' bundle, Test::Stream::Bundle::V1 and see if it is more to your liking.

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.

is

Very little has changed as far as how this is used, but there are a lot of changes under the hood, as well the signature has been changed much like ok()'s in that you can add diagnostics at the end to display in case of failure.

This function will stringify the first 2 arguments and run a stgring comparison. If both arguments are endefined that will also be considered a pass.

isnt

Very little has changed, same changes as is().

is_deeply

Very little has changed as far as how this is used, but there are a lot of changes under the hood, as well the signature has been changed much like ok()'s in that you can add diagnostics at the end to display in case of failure.

This function will do a deep comparison recursing into hashrefs, arrayrefs, and scalar refs. Any other values will be compared using string comparisons.

Diagnostics have been improved as well, you will get a table with all the differences betwene the structures. Normally this will stop at 25 differences, but the number can be tweaked using the $ENV{TS_MAX_DELTA} environment variable.

Note: under the hood this uses the Test::Stream::Compare library, as such it will gladly accept any advanced check objects you produce with that library. In practice this has no effect at all on you unless you use the Compare library tools directly.

like

Not much has changed, added @ to signature for diagnostics.

unlike

Not much has changed, added @ to signature for diagnostics.

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

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

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 '-Classic', 'Subtest' => ['streamed'];

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

cmp_ok

Usage is still the same. Internals have been heavily modified to enhance diagnostics. There is also now a list of supported operators, warnings are issued if you use an unsupported one.

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

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 separate 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.

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 -Classic;
    use utf8;

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

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

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 'Classic' 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

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/