The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.
 / 
Perl6-Pugs-6.2.13
River stage zero No dependents
++
/ Test

NAME

Test - Test support module for perl6

SYNOPSIS

  use v6-alpha;
  require Test;

  plan 10;
  force_todo(1, 3 .. 5, 9);

  use_ok('Some::Module');
  use_ok('Some::Other::Module', todo => 1);

  ok(2 + 2 == 4, '2 and 2 make 4');
  is(2 + 2, 4, '2 and 2 make 4');
  isa_ok([1, 2, 3], 'List');

  ok(2 + 2 == 5, '2 and 2 make 5', :todo(1));
  is(2 + 2, 5, desc => '2 and 2 make 5', todo => 1);
  isa_ok({'one' => 1}, 'Hash', :todo(1));

  use_ok('My::Module');

  pass('This test passed');
  flunk('This test failed');

  skip('skip this test for now');

  flunk('this fails, but might work soon', :todo(1));

  diag('some misc comments and documentation');

  # TODO the next test with respect to the "deadline" specified.
  todo :pugs<6.2.13>, :foo<1.23>;
  is foo, bar, '...';

DESCRIPTION

This module was built to facilitate the Pugs test suite. It has the distinction of being the very first module written for Pugs.

It provides a simple set of common test utility functions, and is an implementation of the TAP protocol.

This module, like Pugs, is a work in progress. As new features are added to Pugs, new test functions will be defined to facilitate the testing of those features. For more information see the FUTURE PLANS section of this document.

FUNCTIONS

  plan (Int $number_of_tests) returns Void

All tests need a plan. A plan is simply the number of tests which are expected to run. This should be specified at the very top of your tests.

  force_todo (*@todo_tests) returns Void

If you have some tests which you would like to force into being TODO tests then you can pass them through this function. This is primarily a release tool, but can be useful in other contexts as well.

Testing Functions

use_ok

  use_ok (Str $module, Bool :$todo, Str :$depends) returns Bool

ok

  ok (Bool $cond, Str $desc?, Bool :$todo, Str :$depends) returns Bool

is

isnt

  is   (Str $got, Str $expected, Str $desc?, Bool :$todo, Str :$depends) returns Bool
  isnt (Str $got, Str $expected, Str $desc?, Bool :$todo, Str :$depends) returns Bool

like

unlike

  like   (Str $got, Rule $expected, Str $desc?, Bool :$todo, Str :$depends) returns Bool is export
  unlike (Str $got, Rule $expected, Str $desc?, Bool :$todo, Str :$depends) returns Bool is export

These functions should work with most reg-exps, but given that they are still a somewhat experimental feature in Pugs, it is suggested you don't try anything too funky.

cmp_ok

  cmp_ok (Str $got, Code &compare_func, Str $expected, Str $desc?, Bool :$todo, Str :$depends) returns Bool

This function will compare $got and $expected using &compare_func. This will eventually allow Test::More-style cmp_ok() though the following syntax:

  cmp_ok('test', &infix:<gt>, 'me', '... testing gt on two strings');

However the &infix:<gt> is currently not implemented, so you will have to wait a little while. Until then, you can just write your own functions like this:

  cmp_ok('test', sub ($a, $b) { ?($a gt $b) }, 'me', '... testing gt on two strings');
  isa_ok ($ref, Str $expected_type, Str $desc?, Bool :$todo, Str :$depends) returns Bool

This function currently on checks with WHAT() since we do not yet have object support. Once object support is created, we will add it here, and maintain backwards compatibility as well.

eval_dies_ok

  eval_dies_ok (Str $code, Str $desc?,                Bool :$todo, Str :$depends) returns Bool

This is the function to use if you have a piece of code that would otherwise failed to be parsed. If the code parses, but may die at run time, consider using dies_ok or lives_ok, which have lower overhead.

eval a string - unsuccessful or failure was expected.

The eval does not occur in the context of the caller. Non-global lexicals will not be accessible, and the package will be different.

throws_ok

  throws_ok (Code &code, Any $expected, Str $desc?, Bool :$todo, Str :$depends) returns Bool

This function takes a block of code and runs it. It then smart-matches (~~) any $! value with the $expected value.

dies_ok

lives_ok

  dies_ok  (Code &code, Str $desc?, Bool :$todo, Str :$depends) returns Bool
  lives_ok (Code &code, Str $desc?, Bool :$todo, Str :$depends) returns Bool

These functions both take blocks of code, and test whether they live or die using try

The code must at least be parsable. If the code might not parse, wrap it in eval.

is_deeply

 is_deeply(Any $got, Any $expected, Str $desc?, :$todo, :$depends) returns Bool

Similar to is(), except that if $this and $that are references, it does a deep comparison walking each data structure to see if they are equivalent.

Misc. Functions

todo

  todo (*%deadline) returns Bool is export

If and only if the deadline has been hit (or passed), the next one test will be marked as TODO.

For example:

   todo :pugs<6.28.0>;
   is($got, $expected, $desc);

The call to the todo function will mark the next one test as TODO if and only if the current compiler's $?COMPILER holds a string whose lowercase version equals to 'pugs' and $?VERSION holds a value less than '6.28.0'. The todo functuion will perform partial ordering comparison between version numbers.

More implementation-specific deadlines can be appended to a single todo call:

  todo :pugs<6.28.0>, :p6p5<0.011>, :parrot<0.45>;

skip

  skip (Str $reason?) returns Bool
  skip (Int $count, Str $reason?) returns Bool

If for some reason a test is to be skipped, you can use this function to do so.

pass

flunk

  pass (Str $desc?) returns Bool

Sometimes what you need to test does not fit into one of the standard testing functions. In that case, you can use the rather blunt pass() functions and its compliment the flunk() function.

  flunk (Str $desc?, Bool :$todo) returns Bool

This is the opposite of pass()

diag

  diag (Str $diag)

This will print each string with a '#' character appended to it, this is ignored by the TAP protocol.

Common options

:todo

Sometimes a test is broken because something is not implemented yet. So in order to still allow that to be tested, and those tests to knowingly fail, we provide the todo function to TODO the next one test according to a given deadline. (See below.)

Take the Pugs implementation. When TODOing failing tests before the Pugs release (say, 6.2.12), the following form of todo should be used:

    todo :pugs<6.2.13>;  # version of the next point release

By doing this, temporarily TODO'd tests can get unTODO'd automatically once the the release is done (and the version number gets updated).

The version number fed to todo is optional. If omitted, the corresponding tests won't get expired unless we unTODO them manually.

It is also possible to use the force_todo() function to do large scale TODO-ing of tests.

:depends

The :depends("string") parameter to most of the functions is a way to provide more context in the case of a failure. It should refer to another file or test which must be made to pass before this test can pass (or before an implementation could be started). This is most useful when writing modules and you find there is some language feature missing, or core bug that needs to be sorted out before you can continue.

FUTURE PLANS

This module is still a work in progress. As Pugs grows, so will it's testing needs. This module will be the code support for those needs. The following is a list of future features planned for this module.

- better error handling for cmp_ok

The error handling capabilities need to be expanded more to handle the error reporting needs of the cmp_ok() function.

ENVIRONMENT

Setting the environment variable TEST_ALWAYS_CALLER to force Test.pm to always append the caller information to the test's $desc.

SEE ALSO

The Perl 5 Test modules

- Test

- Test::More

Information about the TAP protocol can be found in the Test::Harness distribution.

AUTHORS

Audrey Tang <autrijus@autrijus.org>

Benjamin Smith

Norman Nunley

Steve Peters

Stevan Little <stevan@iinteractive.com>

Brian Ingerson <ingy@cpan.org>

Jesse Vincent <jesse@bestpractical.com>

Yuval Kogman <nothingmuch@woobling.org>

Darren Duncan <perl@DarrenDuncan.net>

Nathan Gray <kolibrie@graystudios.org>

Max Maischein <corion@cpan.org>

Ingo Blechschmidt <iblech@web.de>

Gaal Yahas <gaal@forum2.org>

Mark Stosberg

Simon Sun <dolmens@gmail.com>

COPYRIGHT

Copyright (c) 2005, 2006. Audrey Tang. All rights reserved.

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