1Test::Harness(3)      User Contributed Perl Documentation     Test::Harness(3)
2
3
4

NAME

6       Test::Harness - Run Perl standard test scripts with statistics
7

VERSION

9       Version 3.48
10

SYNOPSIS

12         use Test::Harness;
13
14         runtests(@test_files);
15

DESCRIPTION

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
23       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
28       See TAP::Parser, TAP::Harness for the main documentation for this
29       distribution.
30

FUNCTIONS

32       The following functions are available.
33
34   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
40       It returns true if everything was ok.  Otherwise it will die() with one
41       of the messages in the DIAGNOSTICS section.
42
43   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
50       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
54           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
60           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
66       If "$total->{bad} == 0" and "$total->{max} > 0", you've got a
67       successful test.
68
69       $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
73           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
80       $failed should be empty if everything passed.
81

EXPORT

83       &runtests is exported by "Test::Harness" by default.
84
85       &execute_tests, $verbose, $switches and $debug are exported upon
86       request.
87

ENVIRONMENT VARIABLES THAT TAP::HARNESS::COMPATIBLE SETS

89       "Test::Harness" sets these before executing the individual tests.
90
91       "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
95       "HARNESS_VERSION"
96           This is the version of "Test::Harness".
97

ENVIRONMENT VARIABLES THAT AFFECT TEST::HARNESS

99       "HARNESS_PERL_SWITCHES"
100           Setting this adds perl command line switches to each test file run.
101
102           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
106           "-w" is always set.  You can turn this off in the test with "BEGIN
107           { $^W = 0 }".
108
109       "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
114       "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
119       "HARNESS_OPTIONS"
120           Provide additional options to the harness. Currently supported
121           options are:
122
123           "j<n>"
124               Run <n> (default 9) parallel jobs.
125
126           "c" Try to color output. See "new" in TAP::Formatter::Base.
127
128           "a<file.tgz>"
129               Will use TAP::Harness::Archive as the harness class, and save
130               the TAP to "file.tgz"
131
132           "fPackage-With-Dashes"
133               Set the formatter_class of the harness being run. Since the
134               "HARNESS_OPTIONS" is separated by ":", we use "-" instead.
135
136           Multiple options may be separated by colons:
137
138               HARNESS_OPTIONS=j9:c make test
139
140       "HARNESS_SUBCLASS"
141           Specifies a TAP::Harness subclass to be used in place of
142           TAP::Harness.
143
144       "HARNESS_SUMMARY_COLOR_SUCCESS"
145           Determines the Term::ANSIColor for the summary in case it is
146           successful.  This color defaults to 'green'.
147
148       "HARNESS_SUMMARY_COLOR_FAIL"
149           Determines the Term::ANSIColor for the failure in case it is
150           successful.  This color defaults to 'red'.
151

Taint Mode

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
156       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

SEE ALSO

162       TAP::Harness
163

BUGS

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

AUTHORS

172       Andy Armstrong  "<andy@hexten.net>"
173
174       Test::Harness 2.64 (maintained by Andy Lester and on which this module
175       is based) has this attribution:
176
177           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
187       This module is free software; you can redistribute it and/or modify it
188       under the same terms as Perl itself. See perlartistic.
189
190
191
192perl v5.38.0                      2023-10-03                  Test::Harness(3)
Impressum