Section 3: Test
This page was been converted automatically, from Debian GNU/Linux
man pages.
Test(3pm) Perl Programmers Reference Guide Test(3pm)
NAME
Test - provides a simple framework for writing test scripts
SYNOPSIS
use strict;
use Test;
# use a BEGIN block so we print our plan before MyModule is loaded
BEGIN { plan tests => 14, todo => [3,4] }
# load your module...
use MyModule;
ok(0); # failure
ok(1); # success
ok(0); # ok, expected failure (see todo list, above)
ok(1); # surprise success!
ok(0,1); # failure: '0' ne '1'
ok('broke','fixed'); # failure: 'broke' ne 'fixed'
ok('fixed','fixed'); # success: 'fixed' eq 'fixed'
ok('fixed',qr/x/); # success: 'fixed' =~ qr/x/
ok(sub { 1+1 }, 2); # success: '2' eq '2'
ok(sub { 1+1 }, 3); # failure: '2' ne '3'
ok(0, int(rand(2)); # (just kidding :-)
my @list = (0,0);
ok @list, 3, "\@list=".join(',',@list); #extra diagnostics
ok 'segmentation fault', '/(?i)success/'; #regex match
skip($feature_is_missing, ...); #do platform specific test
DESCRIPTION
the Test::Harness manpage expects to see particular output
when it executes tests. This module aims to make writing
proper test scripts just a little bit easier (and less
error prone :-).
TEST TYPES
+ NORMAL TESTS
These tests are expected to succeed. If they don't
something's screwed up!
+ SKIPPED TESTS
Skip is for tests that might or might not be possible
to run depending on the availability of platform
specific features. The first argument should evaluate
to true (think "yes, please skip") if the required
feature is not available. After the first argument,
skip works exactly the same way as do normal tests.
27/Mar/1999 perl 5.005, patch 03 1
Test(3pm) Perl Programmers Reference Guide Test(3pm)
+ TODO TESTS
TODO tests are designed for maintaining an executable
TODO list. These tests are expected NOT to succeed.
If a TODO test does succeed, the feature in question
should not be on the TODO list, now should it?
Packages should NOT be released with succeeding TODO
tests. As soon as a TODO test starts working, it
should be promoted to a normal test and the newly
working feature should be documented in the release
notes or change log.
RETURN VALUE
Both ok and skip return true if their test succeeds and
false otherwise in a scalar context.
ONFAIL
BEGIN { plan test => 4, onfail => sub { warn "CALL 911!" } }
While test failures should be enough, extra diagnostics
can be triggered at the end of a test run. onfail is
passed an array ref of hash refs that describe each test
failure. Each hash will contain at least the following
fields: package, repetition, and result. (The file, line,
and test number are not included because their
correspondance to a particular test is tenuous.) If the
test had an expected value or a diagnostic string, these
will also be included.
The optional onfail hook might be used simply to print out
the version of your package and/or how to report problems.
It might also be used to generate extremely sophisticated
diagnostics for a particularly bizarre test failure.
However it's not a panacea. Core dumps or other
unrecoverable errors prevent the onfail hook from running.
(It is run inside an END block.) Besides, onfail is
probably over-kill in most cases. (Your test code should
be simpler than the code it is testing, yes?)
SEE ALSO
the Test::Harness manpage and, perhaps, test coverage
analysis tools.
AUTHOR
Copyright (c) 1998 Joshua Nathaniel Pritikin. All rights
reserved.
This package is free software and is provided "as is"
without express or implied warranty. It may be used,
redistributed and/or modified under the terms of the Perl
Artistic License (see
http://www.perl.com/perl/misc/Artistic.html)
27/Mar/1999 perl 5.005, patch 03 2
Test(3pm) Perl Programmers Reference Guide Test(3pm)
27/Mar/1999 perl 5.005, patch 03 3