


Test(3p)         Perl Programmers Reference Guide        Test(3p)


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
       o NORMAL TESTS
           These tests are expected to succeed.  If they don't
           something's screwed up!

       o SKIPPED TESTS
           Skip is for tests that might or might not be possible
           to run depending on the availability of platform spe-
           cific features.  The first argument should evaluate to
           true (think "yes, please skip") if the required fea-
           ture is not available.  After the first argument, skip
           works exactly the same way as do normal tests.



2000-04-06                 perl v5.6.0                          1





Test(3p)         Perl Programmers Reference Guide        Test(3p)


       o 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 cor-
       respondence 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 prob-
       lems.  It might also be used to generate extremely sophis-
       ticated diagnostics for a particularly bizarre test fail-
       ure.  However it's not a panacea.  Core dumps or other
       unrecoverable errors prevent the `onfail' hook from run-
       ning.  (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-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 http://www.perl.com/perl/misc/Artis-
       tic.html)





2000-04-06                 perl v5.6.0                          2


