Debian Codegraph @

upstream/mageia-cauldron/man3pm/Test::Harness.3pm

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