Test::Harness(3)					      Test::Harness(3)

NAME    [Toc]    [Back]

     Test::Harness - run perl standard test scripts with statistics

SYNOPSIS    [Toc]    [Back]

     use Test::Harness;

     runtests(@tests);

DESCRIPTION    [Toc]    [Back]

     Perl test scripts print to	standard output	"ok N" for each	single test,
     where N is	an increasing sequence of integers. The	first line output by a
     standard test script is "1..M" with M being the number of tests that
     should be run within the test script. Test::Harness::runtests(@tests)
     runs all the testscripts named as arguments and checks standard output
     for the expected "ok N" strings.

     After all tests have been performed, runtests() prints some performance
     statistics	that are computed by the Benchmark module.

     The test script output    [Toc]    [Back]

     Any output	from the testscript to standard	error is ignored and bypassed,
     thus will be seen by the user. Lines written to standard output
     containing	/^(not\s+)?ok\b/ are interpreted as feedback for runtests().
     All other lines are discarded.

     It	is tolerated if	the test numbers after ok are omitted. In this case
     Test::Harness maintains temporarily its own counter until the script
     supplies test numbers again. So the following test	script

	 print <<END;
	 1..6
	 not ok
	 ok
	 not ok
	 ok
	 ok
	 END

     will generate

	 FAILED	tests 1, 3, 6
	 Failed	3/6 tests, 50.00% okay

     The global	variable $Test::Harness::verbose is exportable and can be used
     to	let runtests() display the standard output of the script without
     altering the behavior otherwise.

     The global	variable $Test::Harness::switches is exportable	and can	be
     used to set perl command line options used	for running the	test
     script(s).	The default value is -w.




									Page 1






Test::Harness(3)					      Test::Harness(3)

EXPORT    [Toc]    [Back]

     &runtests is exported by Test::Harness per	default.

DIAGNOSTICS    [Toc]    [Back]

     All tests successful.\nFiles=%d,  Tests=%d, %s
	 If all	tests are successful some statistics about the performance are
	 printed.

     FAILED tests %s\n\tFailed %d/%d tests, %.2f%% okay.
	 For any single	script that has	failing	subtests statistics like the
	 above are printed.

     Test returned status %d (wstat %d)
	 Scripts that return a non-zero	exit status, both $? >>	8 and $? are
	 printed in a message similar to the above.

     Failed 1 test, %.2f%% okay. %s

     Failed %d/%d tests, %.2f%%	okay. %s
	 If not	all tests were successful, the script dies with	one of the
	 above messages.

SEE ALSO    [Toc]    [Back]

     See the Benchmark manpage for the underlying timing routines.

AUTHORS    [Toc]    [Back]

     Either Tim	Bunce or Andreas Koenig, we don't know.	What we	know for sure
     is, that it was inspired by Larry Wall's TEST script that came with perl
     distributions for ages. Numerous anonymous	contributors exist. Current
     maintainer	is Andreas Koenig.

BUGS    [Toc]    [Back]

     Test::Harness uses	$^X to determine the perl binary to run	the tests
     with. Test	scripts	running	via the	shebang	(#!) line may not be portable
     because $^X is not	consistent for shebang scripts across platforms. This
     is	no problem when	Test::Harness is run with an absolute path to the perl
     binary or when $^X	can be found in	the path.


















									Page 2






Test::Harness(3)					      Test::Harness(3)


									PPPPaaaaggggeeee 3333