You are viewing the version of this documentation from Perl 5.6.1. View the latest version



Test - provides a simple framework for writing test scripts


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


Test::Harness 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 :-).



Both ok and skip return true if their test succeeds and false otherwise in a scalar context.


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 correspondence 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?)


Test::Harness and, perhaps, test coverage analysis tools.


Copyright (c) 1998-1999 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