Test::Stream::Manual::FromTestBuilder - Translation document for people moving from Test::More, Test::Simple, or other Test::Builder tools.
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; ...
This is the list of stuff that has either not changed, or changed only in ways not likely to be noticed.
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.
ok($$;$)
ok($$;$@)
@
Defined in Test::Stream::Plugin::Core.
No differences
Signature changed from fail($) to fail($;@). Extra arguments are diagnostics that will be shown with your failing test.
fail($)
fail($;@)
No longer accepts arguments. Most people did not know it could accept arguments in Test::More so it is unlikely to effect many people.
This is a list of very notable changes that are likely to hurt you if you are not aware of them.
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.
is
is_deeply
ref_is()
ref_is_not()
is()
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 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
like($var, qr/.../)
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" );
Only accepts a number of test expected to be run.
plan 5;
See skip_all for skipping an entire test.
skip_all
This is the new way to skip an entire test, it takes a reason as its argument.
skip_all 'Broken for now';
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.
can_ok
isa_ok($thing, 'My::Class', 'My::Subclass', ...);
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.
These are no longer around for you to use.
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.
This is easy enough:
ok(my $one = $class->new(@args), "NAME");
The utility of new_ok() is questionable at best.
new_ok()
Test::More itself discourages you from using these, so we are not carrying them forward.
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.
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.
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:
$TODO
todo()
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'); };
See Test::Stream::Context for how Test:Stream solves the same problem.
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.
done_testing
plan()
This is some new stuff you get for free!
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.
isa_ok
DOES
can
isa
Check that something is a ref, and optionally that it is a specific type of ref.
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.
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.
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.
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.
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, '†');
This is the alternative to $Test::Builder::Level. See Test::Stream::Context for more info.
$Test::Builder::Level
Defined in Test::Stream::Plugin::Context.
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.
Used to check if something has been mocked using the Mock plugin.
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.
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", );
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");
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.
Returns the exception produced by the block, or undef if it did not die.
like( dies { ... }, qr/xxx/, "Got excpetion" );
Forking and threading in your tests will just work (so long as you use the 'IPC' plugin, which is included in the 'V1' bundle).
The source code repository for Test::Stream can be found at http://github.com/Test-More/Test-Stream/.
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
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.