1Test::Harness(3pm) Perl Programmers Reference Guide Test::Harness(3pm)
2
6 Test::Harness - Run Perl standard test scripts with statistics
7
9 Version 3.17
10
12 use Test::Harness;
13 runtests(@test_files);
15
17 Although, for historical reasons, the Test::Harness distribution takes
18 its name from this module it now exists only to provide TAP::Harness
19 with an interface that is somewhat backwards compatible with
20 Test::Harness 2.xx. If you're writing new code consider using
21 TAP::Harness directly instead.
22 Emulation is provided for "runtests" and "execute_tests" but the
24 pluggable 'Straps' interface that previous versions of Test::Harness
25 supported is not reproduced here. Straps is now available as a stand
26 alone module: Test::Harness::Straps.
27 See TAP::Parser, TAP::Harness for the main documentation for this
29 distribution.
30
32 The following functions are available.
33 runtests( @test_files )
35 This runs all the given @test_files and divines whether they passed or
36 failed based on their output to STDOUT (details above). It prints out
37 each individual test which failed along with a summary report and a how
38 long it all took.
39 It returns true if everything was ok. Otherwise it will "die()" with
41 one of the messages in the DIAGNOSTICS section.
42 execute_tests( tests => \@test_files, out => \*FH )
44 Runs all the given @test_files (just like "runtests()") but doesn't
45 generate the final report. During testing, progress information will
46 be written to the currently selected output filehandle (usually
47 "STDOUT"), or to the filehandle given by the "out" parameter. The out
48 is optional.
49 Returns a list of two values, $total and $failed, describing the
51 results. $total is a hash ref summary of all the tests run. Its keys
52 and values are this:
53 bonus Number of individual todo tests unexpectedly passed
55 max Number of individual tests ran
56 ok Number of individual tests passed
57 sub_skipped Number of individual tests skipped
58 todo Number of individual todo tests
59 files Number of test files ran
61 good Number of test files passed
62 bad Number of test files failed
63 tests Number of test files originally given
64 skipped Number of test files skipped
65 If "$total->{bad} == 0" and "$total->{max} > 0", you've got a
67 successful test.
68 $failed is a hash ref of all the test scripts that failed. Each key is
70 the name of a test script, each value is another hash representing how
71 that script failed. Its keys are these:
72 name Name of the test which failed
74 estat Script's exit value
75 wstat Script's wait status
76 max Number of individual tests
77 failed Number which failed
78 canon List of tests which failed (as string).
79 $failed should be empty if everything passed.
81
83 &runtests is exported by "Test::Harness" by default.
84 &execute_tests, $verbose, $switches and $debug are exported upon
86 request.
87
89 "Test::Harness" sets these before executing the individual tests.
90 "HARNESS_ACTIVE"
92 This is set to a true value. It allows the tests to determine if
93 they are being executed through the harness or by any other means.
94 "HARNESS_VERSION"
96 This is the version of "Test::Harness".
97
99 "HARNESS_TIMER"
100 Setting this to true will make the harness display the number of
101 milliseconds each test took. You can also use prove's "--timer"
102 switch.
103 "HARNESS_VERBOSE"
105 If true, "Test::Harness" will output the verbose results of running
106 its tests. Setting $Test::Harness::verbose will override this, or
107 you can use the "-v" switch in the prove utility.
108 "HARNESS_OPTIONS"
110 Provide additional options to the harness. Currently supported
111 options are:
112 "j<n>"
114 Run <n> (default 9) parallel jobs.
115 "f" Use forked parallelism.
117 Multiple options may be separated by colons:
119 HARNESS_OPTIONS=j9:f make test
121
123 Normally when a Perl program is run in taint mode the contents of the
124 "PERL5LIB" environment variable do not appear in @INC.
125 Because "PERL5LIB" is often used during testing to add build
127 directories to @INC "Test::Harness" (actually
128 TAP::Parser::Source::Perl) passes the names of any directories found in
129 "PERL5LIB" as -I switches. The net effect of this is that "PERL5LIB" is
130 honoured even in taint mode.
131
133 TAP::Harness
134
136 Please report any bugs or feature requests to "bug-test-harness at
137 rt.cpan.org", or through the web interface at
138 http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Test-Harness
139 <http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Test-Harness>. I will
140 be notified, and then you'll automatically be notified of progress on
141 your bug as I make changes.
142
144 Andy Armstrong "<andy@hexten.net>"
145 Test::Harness 2.64 (maintained by Andy Lester and on which this module
147 is based) has this attribution:
148 Either Tim Bunce or Andreas Koenig, we don't know. What we know for
150 sure is, that it was inspired by Larry Wall's F<TEST> script that came
151 with perl distributions for ages. Numerous anonymous contributors
152 exist. Andreas Koenig held the torch for many years, and then
153 Michael G Schwern.
154
156 Copyright (c) 2007-2008, Andy Armstrong "<andy@hexten.net>". All rights
157 reserved.
158 This module is free software; you can redistribute it and/or modify it
160 under the same terms as Perl itself. See perlartistic.
161perl v5.12.4 2011-06-07 Test::Harness(3pm)