Switch branches/tags
Nothing to show
Find file
Fetching contributors…
Cannot retrieve contributors at this time
122 lines (81 sloc) 3.45 KB


Synopsis 24: Testing


Moritz Lenz <>
Carl Mäsak <>


Created: 30 Dec 2010

Last Modified: 17 Oct 2011
Version: 7


use Test;

plan 6;

ok True, 'True is a true value';
nok False, 'False is a false value';
is 'ab'.uc, 'AB', 'successful string comparison';
is_approx 2.sqrt, 1.4142135623, 'Approximate numeric comparison';
dies_ok { die "yes"}, 'exceptions';
eval_dies_ok '1 1', 'two terms in a row are a parse error';


Perl 6 comes with a standard testing module, Test. It is the testing module used by the official spectest suite.

The testing functions emit output conforming to the Test Anything Protocol. See

For the purposes of this document, a test file is a file that does use Test.

Test plans

sub plan($number_of_tests) is export { ... };
sub done() is export { ... };

In order to determine whether a test file ran all its tests, a plan function call can be made somewhere in the test file, providing a count of the total number of tests. A TAP harness can then flag an error condition when the number of tests actually run doesn't match.

If plan isn't called, done can be called at the end of the test file to output an automatically computed tally.

A TAP harness will consider it an error if neither plan nor done was called, or if there was more than one call in the test file, or if the call occurred between calling two test functions (rather than at the beginning or at the end).

Test functions

All test functions take an optional description argument, which will be printed along with the ok or not ok result and the test number. Note that what is displayed as optional parameters in the list below might as well be implemented by some other mechanism, such as several multi subs. Such details are left as implementation-dependent.

The names of positional parameters are non-normative, so supplying the positional arguments to these test files by name is discouraged.

All of the following functions are exported by default:

# unconditional passing/failing

# evaluates $cond in boolean context
ok(Mu $cond, $desc?)
nok(Mu $cond, $desc?)

# string comparison
is(Mu $got, Mu $expected, $desc?)
isnt(Mu $got, Mu $expected, $desc?)

# structural comparison with infix:<eqv>
is_deeply(Mu $got, Mu $expected, $desc?)

# numeric comparison with 1e-5
is_approx(Mu $got, Mu $expected, $desc?)

# class membership testing
# converts the type name to an actual type object
# if $type ~~ Str
isa_ok(Mu $var, Mu $type, $desc?)

# exception testing
lives_ok(Callable $code, $desc?)
dies_ok(Callable $code, $desc?)

# eval + exception testing
eval_lives_ok(Str $code, $desc?)
eval_dies_ok(Str $code, $desc?)

These functions work roughly the same way as the functions of the same name from Perl 5's Test::More and Test::Exception modules.

TODO: more precise explanation

todo() and skip()

todo($reason, $count = 1)
skip($reason, $count = 1)

The todo() function can be called before running other test functions, and marks the next $count tests as TODO.

The skip() function is called instead of the some tests (usually because they would die), and emits $count SKIP markers in the TAP output.