=encoding utf8

=head1 TITLE

Synopsis 24: Testing

=head1 VERSION

    Created: 30 Dec 2010

    Last Modified: 14 August 2014
    Version: 8

=head1 SYNOPSIS

    use Test;

    plan 6; # not needed when using "done"

    ok True, 'True is a true value';
    nok False, 'False is a false value';
    is 'ab'.uc, 'AB', 'successful string comparison';
    diag "we may have some mathematical issues"
      if !is-approx 2.sqrt, 1.4142135623, 'Approximate numeric comparison';
    dies-ok { die "yes"}, 'exceptions';
    dies-ok '1 1', 'two terms in a row are a parse error';

    done;  # not needed when doing "plan"

=head1 DESCRIPTION

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

The testing functions emit output conforming to the Test Anything
Protocol. See L<http://testanything.org>.

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

All of the following functions are exported by default:

    # planning number of tests
    plan($number-of-tests)
    done()

    # unconditional passing/failing/notification
    pass($desc?)
    flunk($desc?)
    diag($desc)

    # skipping
    todo($reason, $count = 1)
    skip($reason, $count = 1)
    skip-rest($reason?)

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

    # comparisons
    is(Mu $got, Mu $expected, $desc?)
    isnt(Mu $got, Mu $expected, $desc?)
    cmp-ok(Mu $got, $op, 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
    isa-ok(Mu $var, Mu $type, $desc?)

    # grouping of tests, ok only if all ok
    subtest(&subtests, $desc?)

    # exception testing
    dies-ok($code, $desc?)
    lives-ok($code, $desc?)
    throws-like($code, $exception-type, $desc?, *%matcher)

=head1 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 C<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 C<plan()> isn't called, C<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 C<plan()> nor
C<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).

=head1 Test functions

All test functions take an optional description argument, which
will be printed along with the C<ok> or C<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 C<multi sub>s. 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.

=head2 pass(), flunk()

    sub pass($desc?) is export { ... }
    sub flunk($desc?) is export { ... }

The C<pass()> function marks a test as passed.  The C<flunk()> function marks a
test as B<not> passed.

=head2 diag()

    sub diag($message) is export { ... }

The C<diag()> function allows specific diagnostic information to be printed
in a TAP-compatible manner on C<$*ERR>.  It is usually used when a particular
test has failed to provide information that the test itself did not provide.
Or it can be used to provide visual markers on how the testing of a test-file
is progressing (which can be important when doing stress testing).

=head2 todo(), skip(), skip-rest()

    sub todo($reason, $count = 1) is export { ... }
    sub skip($reason, $count = 1) is export { ... }
    sub skip-rest($reason?) is export { ... }

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

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

The C<skip-rest()> function can be called conditionally to C<skip($remaining)>
all of the remaining tests.

The C<todo()> and C<skip()> functions are generally automatically generated
by some sort of source code fudging program.

=head2 ok(), nok()

    sub ok(Mu $cond, $desc?) is export { ... }
    sub nok(Mu $cond, $desc?) is export { ... }

The C<ok()> function marks a test as passed if the given condition evaluates
to C<True>.  The C<nok()> function marks a test as passed if the given
condition evaluates to C<False>.

=head2 is(), isnt(), cmp-ok()

    sub is(Mu $got, Mu $expected, $desc?) is export { ... }
    sub isnt(Mu $got, Mu $expected, $desc?) is export { ... }
    sub cmp-ok(Mu $got, $op, Mu $expected, $desc?) is export { ... }

The C<is()> function marks a test as passed if the obtained and expected values
are the same.  If C<$expected> is a type object, then C<$got> is compared
using C<===>.  If C<$expected> is a defined value, then C<$got> is compared
using C<eq>.  The C<isnt()> function marks a test as passed if the obtained
and expected values are B<not> the same (using the same logic as with C<is()>).

The C<cmp-ok()> function compares two values with the given operator and passes
the test if the comparison yields a C<True> value.  For ease of use, operators
may be passed as strings, such as C<'=='> or C<'~~'>.  Note that you can also
pass a custom operator, for special types of comparisons.

These functions are typically used to check scalar values.

=head2 is-deeply()

    sub is-deeply(Mu $got, Mu $expected, $desc?) is export { ... }

The C<is-deeply()> function marks a test as passed if the obtained and expected
values are C<eqv>.  This is the best way to check for equality of (deep) data
structures.

=head2 is-approx()

    sub is-approx(Mu $got, Mu $expected, $desc?) is export { ... }

The C<is-approx()> function marks a test as passed if the obtained and
expected numerical values are within C<1e-5> of each other.

=head2 isa-ok()

    sub isa-ok(Mu $object, Mu $type, $desc?) is export { ... }

The C<isa-ok()> function marks a test as passed if the given object is, or
inherits from the given type.  For convenience, types may also be specified
as a string.

=head2 subtest()

    sub subtest(&subtests, $desc?) is export { ... }

The C<subtest()> function executes the given block, consisting of usually more
than one test, possibly including a C<plan()> or C<done()>.  It will pass the
test only if B<all> tests in the block, pass.

=head2 dies-ok(), lives-ok(), throws-like()

    sub dies-ok(Callable $code, $desc?) is export { ... }
    sub lives-ok(Callable $code, $desc?) is export { ... }
    sub throws-like($code, $exception-type, $desc?, *%matcher) is export { ... }

The C<dies-ok()> passes the test if the given code throws an exception.
The C<lives-ok()> passes the test if the given code B<does not> throw an
exception.

The C<throws-like()> function checks whether the given code (specified as either
something C<Callable>, or as a something to be C<EVAL>led) throws a specific
exception (either specified as a Type object, or as a string).  If an
exception was thrown, it will also try to match the matcher hash, in which
the key is the name of the method to be called on the exception, and the
value is the value it should have to pass.

Please note that you can only use the C<EVAL> form if you are not referencing
any symbols in the surrounding scope.  If you are, you should encapsulate
your string with a block and an EVAL.  For instance:

    throws-like { EVAL q[ fac("foo") ] }, X::TypeCheck::Argument;

=head1 AUTHORS

    Moritz Lenz <moritz@faui2k3.org>
    Carl Mäsak <cmasak@gmail.com>
    Elizabeth Mattijsen <liz@wenzperl.nl>

=for vim:set expandtab sw=4: