1Test::Harness(3pm)     Perl Programmers Reference Guide     Test::Harness(3pm)
2
3
4

NAME

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

VERSION

9       Version 3.17
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
41       one 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_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
104       "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
109       "HARNESS_OPTIONS"
110           Provide additional options to the harness. Currently supported
111           options are:
112
113           "j<n>"
114               Run <n> (default 9) parallel jobs.
115
116           "f" Use forked parallelism.
117
118           Multiple options may be separated by colons:
119
120               HARNESS_OPTIONS=j9:f make test
121

Taint Mode

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

SEE ALSO

133       TAP::Harness
134

BUGS

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

AUTHORS

144       Andy Armstrong  "<andy@hexten.net>"
145
146       Test::Harness 2.64 (maintained by Andy Lester and on which this module
147       is based) has this attribution:
148
149           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
159       This module is free software; you can redistribute it and/or modify it
160       under the same terms as Perl itself. See perlartistic.
161
162
163
164perl v5.12.4                      2011-06-07                Test::Harness(3pm)
Impressum