1Test::Harness(3) User Contributed Perl Documentation Test::Harness(3)
2
6 Test::Harness - Run Perl standard test scripts with statistics
7
9 Version 3.43
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_PERL_SWITCHES"
100 Setting this adds perl command line switches to each test file run.
101 For example, "HARNESS_PERL_SWITCHES=-T" will turn on taint mode.
103 "HARNESS_PERL_SWITCHES=-MDevel::Cover" will run "Devel::Cover" for
104 each test.
105 "-w" is always set. You can turn this off in the test with "BEGIN
107 { $^W = 0 }".
108 "HARNESS_TIMER"
110 Setting this to true will make the harness display the number of
111 milliseconds each test took. You can also use prove's "--timer"
112 switch.
113 "HARNESS_VERBOSE"
115 If true, "Test::Harness" will output the verbose results of running
116 its tests. Setting $Test::Harness::verbose will override this, or
117 you can use the "-v" switch in the prove utility.
118 "HARNESS_OPTIONS"
120 Provide additional options to the harness. Currently supported
121 options are:
122 "j<n>"
124 Run <n> (default 9) parallel jobs.
125 "c" Try to color output. See "new" in TAP::Formatter::Base.
127 "a<file.tgz>"
129 Will use TAP::Harness::Archive as the harness class, and save
130 the TAP to "file.tgz"
131 "fPackage-With-Dashes"
133 Set the formatter_class of the harness being run. Since the
134 "HARNESS_OPTIONS" is seperated by ":", we use "-" instead.
135 Multiple options may be separated by colons:
137 HARNESS_OPTIONS=j9:c make test
139 "HARNESS_SUBCLASS"
141 Specifies a TAP::Harness subclass to be used in place of
142 TAP::Harness.
143 "HARNESS_SUMMARY_COLOR_SUCCESS"
145 Determines the Term::ANSIColor for the summary in case it is
146 successful. This color defaults to 'green'.
147 "HARNESS_SUMMARY_COLOR_FAIL"
149 Determines the Term::ANSIColor for the failure in case it is
150 successful. This color defaults to 'red'.
151
153 Normally when a Perl program is run in taint mode the contents of the
154 "PERL5LIB" environment variable do not appear in @INC.
155 Because "PERL5LIB" is often used during testing to add build
157 directories to @INC "Test::Harness" passes the names of any directories
158 found in "PERL5LIB" as -I switches. The net effect of this is that
159 "PERL5LIB" is honoured even in taint mode.
160
162 TAP::Harness
163
165 Please report any bugs or feature requests to "bug-test-harness at
166 rt.cpan.org", or through the web interface at
167 <http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Test-Harness>. I will
168 be notified, and then you'll automatically be notified of progress on
169 your bug as I make changes.
170
172 Andy Armstrong "<andy@hexten.net>"
173 Test::Harness 2.64 (maintained by Andy Lester and on which this module
175 is based) has this attribution:
176 Either Tim Bunce or Andreas Koenig, we don't know. What we know for
178 sure is, that it was inspired by Larry Wall's F<TEST> script that came
179 with perl distributions for ages. Numerous anonymous contributors
180 exist. Andreas Koenig held the torch for many years, and then
181 Michael G Schwern.
182
184 Copyright (c) 2007-2011, Andy Armstrong "<andy@hexten.net>". All rights
185 reserved.
186 This module is free software; you can redistribute it and/or modify it
188 under the same terms as Perl itself. See perlartistic.
189perl v5.34.0 2021-07-23 Test::Harness(3)