Debian Codegraph @

upstream/debian-unstable/man3/Test::Harness.3perl

raw
1 .\" -*- mode: troff; coding: utf-8 -*-
2 .\" Automatically generated by Pod::Man 5.0102 (Pod::Simple 3.45)
3 .\"
4 .\" Standard preamble:
5 .\" ========================================================================
6 .de Sp \" Vertical space (when we can't use .PP)
7 .if t .sp .5v
8 .if n .sp
9 ..
10 .de Vb \" Begin verbatim text
11 .ft CW
12 .nf
13 .ne \\$1
14 ..
15 .de Ve \" End verbatim text
16 .ft R
17 .fi
18 ..
19 .\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
20 .ie n \{\
21 . ds C` ""
22 . ds C' ""
23 'br\}
24 .el\{\
25 . ds C`
26 . ds C'
27 'br\}
28 .\"
29 .\" Escape single quotes in literal strings from groff's Unicode transform.
30 .ie \n(.g .ds Aq \(aq
31 .el .ds Aq '
32 .\"
33 .\" If the F register is >0, we'll generate index entries on stderr for
34 .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
35 .\" entries marked with X<> in POD. Of course, you'll have to process the
36 .\" output yourself in some meaningful fashion.
37 .\"
38 .\" Avoid warning from groff about undefined register 'F'.
39 .de IX
40 ..
41 .nr rF 0
42 .if \n(.g .if rF .nr rF 1
43 .if (\n(rF:(\n(.g==0)) \{\
44 . if \nF \{\
45 . de IX
46 . tm Index:\\$1\t\\n%\t"\\$2"
47 ..
48 . if !\nF==2 \{\
49 . nr % 0
50 . nr F 2
51 . \}
52 . \}
53 .\}
54 .rr rF
55 .\" ========================================================================
56 .\"
57 .IX Title "Test::Harness 3perl"
58 .TH Test::Harness 3perl 2025-11-16 "perl v5.40.1" "Perl Programmers Reference Guide"
59 .\" For nroff, turn off justification. Always turn off hyphenation; it makes
60 .\" way too many mistakes in technical documents.
61 .if n .ad l
62 .nh
63 .SH NAME
64 Test::Harness \- Run Perl standard test scripts with statistics
65 .SH VERSION
66 .IX Header "VERSION"
67 Version 3.48
68 .SH SYNOPSIS
69 .IX Header "SYNOPSIS"
70 .Vb 1
71 \& use Test::Harness;
72 \&
73 \& runtests(@test_files);
74 .Ve
75 .SH DESCRIPTION
76 .IX Header "DESCRIPTION"
77 Although, for historical reasons, the Test::Harness distribution
78 takes its name from this module it now exists only to provide
79 TAP::Harness with an interface that is somewhat backwards compatible
80 with Test::Harness 2.xx. If you're writing new code consider using
81 TAP::Harness directly instead.
82 .PP
83 Emulation is provided for \f(CW\*(C`runtests\*(C'\fR and \f(CW\*(C`execute_tests\*(C'\fR but the
84 pluggable 'Straps' interface that previous versions of Test::Harness
85 supported is not reproduced here. Straps is now available as a stand
86 alone module: Test::Harness::Straps.
87 .PP
88 See TAP::Parser, TAP::Harness for the main documentation for this
89 distribution.
90 .SH FUNCTIONS
91 .IX Header "FUNCTIONS"
92 The following functions are available.
93 .ie n .SS "runtests( @test_files )"
94 .el .SS "runtests( \f(CW@test_files\fP )"
95 .IX Subsection "runtests( @test_files )"
96 This runs all the given \fR\f(CI@test_files\fR\fI\fR and divines whether they passed
97 or failed based on their output to STDOUT (details above). It prints
98 out each individual test which failed along with a summary report and
99 a how long it all took.
100 .PP
101 It returns true if everything was ok. Otherwise it will \f(CWdie()\fR with
102 one of the messages in the DIAGNOSTICS section.
103 .SS "execute_tests( tests => \e@test_files, out => \e*FH )"
104 .IX Subsection "execute_tests( tests => @test_files, out => *FH )"
105 Runs all the given \f(CW@test_files\fR (just like \f(CWruntests()\fR) but
106 doesn't generate the final report. During testing, progress
107 information will be written to the currently selected output
108 filehandle (usually \f(CW\*(C`STDOUT\*(C'\fR), or to the filehandle given by the
109 \&\f(CW\*(C`out\*(C'\fR parameter. The \fIout\fR is optional.
110 .PP
111 Returns a list of two values, \f(CW$total\fR and \f(CW$failed\fR, describing the
112 results. \f(CW$total\fR is a hash ref summary of all the tests run. Its
113 keys and values are this:
114 .PP
115 .Vb 5
116 \& bonus Number of individual todo tests unexpectedly passed
117 \& max Number of individual tests ran
118 \& ok Number of individual tests passed
119 \& sub_skipped Number of individual tests skipped
120 \& todo Number of individual todo tests
121 \&
122 \& files Number of test files ran
123 \& good Number of test files passed
124 \& bad Number of test files failed
125 \& tests Number of test files originally given
126 \& skipped Number of test files skipped
127 .Ve
128 .PP
129 If \f(CW\*(C`$total\->{bad} == 0\*(C'\fR and \f(CW\*(C`$total\->{max} > 0\*(C'\fR, you've
130 got a successful test.
131 .PP
132 \&\f(CW$failed\fR is a hash ref of all the test scripts that failed. Each key
133 is the name of a test script, each value is another hash representing
134 how that script failed. Its keys are these:
135 .PP
136 .Vb 6
137 \& name Name of the test which failed
138 \& estat Script\*(Aqs exit value
139 \& wstat Script\*(Aqs wait status
140 \& max Number of individual tests
141 \& failed Number which failed
142 \& canon List of tests which failed (as string).
143 .Ve
144 .PP
145 \&\f(CW$failed\fR should be empty if everything passed.
146 .SH EXPORT
147 .IX Header "EXPORT"
148 \&\f(CW&runtests\fR is exported by \f(CW\*(C`Test::Harness\*(C'\fR by default.
149 .PP
150 \&\f(CW&execute_tests\fR, \f(CW$verbose\fR, \f(CW$switches\fR and \f(CW$debug\fR are
151 exported upon request.
152 .SH "ENVIRONMENT VARIABLES THAT TAP::HARNESS::COMPATIBLE SETS"
153 .IX Header "ENVIRONMENT VARIABLES THAT TAP::HARNESS::COMPATIBLE SETS"
154 \&\f(CW\*(C`Test::Harness\*(C'\fR sets these before executing the individual tests.
155 .ie n .IP """HARNESS_ACTIVE""" 4
156 .el .IP \f(CWHARNESS_ACTIVE\fR 4
157 .IX Item "HARNESS_ACTIVE"
158 This is set to a true value. It allows the tests to determine if they
159 are being executed through the harness or by any other means.
160 .ie n .IP """HARNESS_VERSION""" 4
161 .el .IP \f(CWHARNESS_VERSION\fR 4
162 .IX Item "HARNESS_VERSION"
163 This is the version of \f(CW\*(C`Test::Harness\*(C'\fR.
164 .SH "ENVIRONMENT VARIABLES THAT AFFECT TEST::HARNESS"
165 .IX Header "ENVIRONMENT VARIABLES THAT AFFECT TEST::HARNESS"
166 .ie n .IP """HARNESS_PERL_SWITCHES""" 4
167 .el .IP \f(CWHARNESS_PERL_SWITCHES\fR 4
168 .IX Item "HARNESS_PERL_SWITCHES"
169 Setting this adds perl command line switches to each test file run.
170 .Sp
171 For example, \f(CW\*(C`HARNESS_PERL_SWITCHES=\-T\*(C'\fR will turn on taint mode.
172 \&\f(CW\*(C`HARNESS_PERL_SWITCHES=\-MDevel::Cover\*(C'\fR will run \f(CW\*(C`Devel::Cover\*(C'\fR for
173 each test.
174 .Sp
175 \&\f(CW\*(C`\-w\*(C'\fR is always set. You can turn this off in the test with \f(CW\*(C`BEGIN {
176 $^W = 0 }\*(C'\fR.
177 .ie n .IP """HARNESS_TIMER""" 4
178 .el .IP \f(CWHARNESS_TIMER\fR 4
179 .IX Item "HARNESS_TIMER"
180 Setting this to true will make the harness display the number of
181 milliseconds each test took. You can also use \fIprove\fR's \f(CW\*(C`\-\-timer\*(C'\fR
182 switch.
183 .ie n .IP """HARNESS_VERBOSE""" 4
184 .el .IP \f(CWHARNESS_VERBOSE\fR 4
185 .IX Item "HARNESS_VERBOSE"
186 If true, \f(CW\*(C`Test::Harness\*(C'\fR will output the verbose results of running
187 its tests. Setting \f(CW$Test::Harness::verbose\fR will override this,
188 or you can use the \f(CW\*(C`\-v\*(C'\fR switch in the \fIprove\fR utility.
189 .ie n .IP """HARNESS_OPTIONS""" 4
190 .el .IP \f(CWHARNESS_OPTIONS\fR 4
191 .IX Item "HARNESS_OPTIONS"
192 Provide additional options to the harness. Currently supported options are:
193 .RS 4
194 .ie n .IP """j<n>""" 4
195 .el .IP \f(CWj<n>\fR 4
196 .IX Item "j<n>"
197 Run <n> (default 9) parallel jobs.
198 .ie n .IP """c""" 4
199 .el .IP \f(CWc\fR 4
200 .IX Item "c"
201 Try to color output. See "new" in TAP::Formatter::Base.
202 .ie n .IP """a<file.tgz>""" 4
203 .el .IP \f(CWa<file.tgz>\fR 4
204 .IX Item "a<file.tgz>"
205 Will use TAP::Harness::Archive as the harness class, and save the TAP to
206 \&\f(CW\*(C`file.tgz\*(C'\fR
207 .ie n .IP """fPackage\-With\-Dashes""" 4
208 .el .IP \f(CWfPackage\-With\-Dashes\fR 4
209 .IX Item "fPackage-With-Dashes"
210 Set the formatter_class of the harness being run. Since the \f(CW\*(C`HARNESS_OPTIONS\*(C'\fR
211 is separated by \f(CW\*(C`:\*(C'\fR, we use \f(CW\*(C`\-\*(C'\fR instead.
212 .RE
213 .RS 4
214 .Sp
215 Multiple options may be separated by colons:
216 .Sp
217 .Vb 1
218 \& HARNESS_OPTIONS=j9:c make test
219 .Ve
220 .RE
221 .ie n .IP """HARNESS_SUBCLASS""" 4
222 .el .IP \f(CWHARNESS_SUBCLASS\fR 4
223 .IX Item "HARNESS_SUBCLASS"
224 Specifies a TAP::Harness subclass to be used in place of TAP::Harness.
225 .ie n .IP """HARNESS_SUMMARY_COLOR_SUCCESS""" 4
226 .el .IP \f(CWHARNESS_SUMMARY_COLOR_SUCCESS\fR 4
227 .IX Item "HARNESS_SUMMARY_COLOR_SUCCESS"
228 Determines the Term::ANSIColor for the summary in case it is successful.
229 This color defaults to \f(CW\*(Aqgreen\*(Aq\fR.
230 .ie n .IP """HARNESS_SUMMARY_COLOR_FAIL""" 4
231 .el .IP \f(CWHARNESS_SUMMARY_COLOR_FAIL\fR 4
232 .IX Item "HARNESS_SUMMARY_COLOR_FAIL"
233 Determines the Term::ANSIColor for the failure in case it is successful.
234 This color defaults to \f(CW\*(Aqred\*(Aq\fR.
235 .SH "Taint Mode"
236 .IX Header "Taint Mode"
237 Normally when a Perl program is run in taint mode the contents of the
238 \&\f(CW\*(C`PERL5LIB\*(C'\fR environment variable do not appear in \f(CW@INC\fR.
239 .PP
240 Because \f(CW\*(C`PERL5LIB\*(C'\fR is often used during testing to add build
241 directories to \f(CW@INC\fR \f(CW\*(C`Test::Harness\*(C'\fR passes the names of any
242 directories found in \f(CW\*(C`PERL5LIB\*(C'\fR as \-I switches. The net effect of this
243 is that \f(CW\*(C`PERL5LIB\*(C'\fR is honoured even in taint mode.
244 .SH "SEE ALSO"
245 .IX Header "SEE ALSO"
246 TAP::Harness
247 .SH BUGS
248 .IX Header "BUGS"
249 Please report any bugs or feature requests to
250 \&\f(CW\*(C`bug\-test\-harness at rt.cpan.org\*(C'\fR, or through the web interface at
251 <http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Test\-Harness>. I will be
252 notified, and then you'll automatically be notified of progress on your bug
253 as I make changes.
254 .SH AUTHORS
255 .IX Header "AUTHORS"
256 Andy Armstrong \f(CW\*(C`<[email protected]>\*(C'\fR
257 .PP
258 Test::Harness 2.64 (maintained by Andy Lester and on which this
259 module is based) has this attribution:
260 .PP
261 .Vb 5
262 \& Either Tim Bunce or Andreas Koenig, we don\*(Aqt know. What we know for
263 \& sure is, that it was inspired by Larry Wall\*(Aqs F<TEST> script that came
264 \& with perl distributions for ages. Numerous anonymous contributors
265 \& exist. Andreas Koenig held the torch for many years, and then
266 \& Michael G Schwern.
267 .Ve
268 .SH "LICENCE AND COPYRIGHT"
269 .IX Header "LICENCE AND COPYRIGHT"
270 Copyright (c) 2007\-2011, Andy Armstrong \f(CW\*(C`<[email protected]>\*(C'\fR. All rights reserved.
271 .PP
272 This module is free software; you can redistribute it and/or
273 modify it under the same terms as Perl itself. See perlartistic.