Test::Stream::Manual::FromTestBuilder(3)

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/