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