Debian Codegraph @

upstream/debian-unstable/man1/prove.1

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 "PROVE 1"
58 .TH PROVE 1 2026-04-10 "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 prove \- Run tests through a TAP harness.
65 .SH USAGE
66 .IX Header "USAGE"
67 .Vb 1
68 \& prove [options] [files or directories]
69 .Ve
70 .SH OPTIONS
71 .IX Header "OPTIONS"
72 Boolean options:
73 .PP
74 .Vb 10
75 \& \-v, \-\-verbose Print all test lines. Also sets TEST_VERBOSE
76 \& \-l, \-\-lib Add \*(Aqlib\*(Aq to the path for your tests (\-Ilib).
77 \& \-b, \-\-blib Add \*(Aqblib/lib\*(Aq and \*(Aqblib/arch\*(Aq to the path for
78 \& your tests
79 \& \-s, \-\-shuffle Run the tests in random order.
80 \& \-c, \-\-color Colored test output (default).
81 \& \-\-nocolor Do not color test output.
82 \& \-\-count Show the X/Y test count when not verbose
83 \& (default)
84 \& \-\-nocount Disable the X/Y test count.
85 \& \-D \-\-dry Dry run. Show test that would have run.
86 \& \-f, \-\-failures Show failed tests.
87 \& \-o, \-\-comments Show comments.
88 \& \-\-ignore\-exit Ignore exit status from test scripts.
89 \& \-m, \-\-merge Merge test scripts\*(Aq STDERR with their STDOUT.
90 \& \-r, \-\-recurse Recursively descend into directories.
91 \& \-\-reverse Run the tests in reverse order.
92 \& \-q, \-\-quiet Suppress some test output while running tests.
93 \& \-Q, \-\-QUIET Only print summary results.
94 \& \-p, \-\-parse Show full list of TAP parse errors, if any.
95 \& \-\-directives Only show results with TODO or SKIP directives.
96 \& \-\-timer Print elapsed time after each test.
97 \& \-\-trap Trap Ctrl\-C and print summary on interrupt.
98 \& \-\-normalize Normalize TAP output in verbose output
99 \& \-T Enable tainting checks.
100 \& \-t Enable tainting warnings.
101 \& \-W Enable fatal warnings.
102 \& \-w Enable warnings.
103 \& \-h, \-\-help Display this help
104 \& \-?, Display this help
105 \& \-V, \-\-version Display the version
106 \& \-H, \-\-man Longer manpage for prove
107 \& \-\-norc Don\*(Aqt process default .proverc
108 .Ve
109 .PP
110 Options that take arguments:
111 .PP
112 .Vb 10
113 \& \-I Library paths to include.
114 \& \-P Load plugin (searches App::Prove::Plugin::*.)
115 \& \-M Load a module.
116 \& \-e, \-\-exec Interpreter to run the tests (\*(Aq\*(Aq for compiled
117 \& tests.)
118 \& \-\-ext Set the extension for tests (default \*(Aq.t\*(Aq)
119 \& \-\-harness Define test harness to use. See TAP::Harness.
120 \& \-\-formatter Result formatter to use. See FORMATTERS.
121 \& \-\-source Load and/or configure a SourceHandler. See
122 \& SOURCE HANDLERS.
123 \& \-a, \-\-archive out.tgz Store the resulting TAP in an archive file.
124 \& \-j, \-\-jobs N Run N test jobs in parallel (try 9.)
125 \& \-\-state=opts Control prove\*(Aqs persistent state.
126 \& \-\-statefile=file Use \`file\` instead of \`.prove\` for state
127 \& \-\-rc=rcfile Process options from rcfile
128 \& \-\-rules Rules for parallel vs sequential processing.
129 .Ve
130 .SH NOTES
131 .IX Header "NOTES"
132 .SS .proverc
133 .IX Subsection ".proverc"
134 If \fI~/.proverc\fR or \fI./.proverc\fR exist they will be read and any
135 options they contain processed before the command line options. Options
136 in \fI.proverc\fR are specified in the same way as command line options:
137 .PP
138 .Vb 3
139 \& # .proverc
140 \& \-\-state=hot,fast,save
141 \& \-j9
142 .Ve
143 .PP
144 Additional option files may be specified with the \f(CW\*(C`\-\-rc\*(C'\fR option.
145 Default option file processing is disabled by the \f(CW\*(C`\-\-norc\*(C'\fR option.
146 .PP
147 Under Windows and VMS the option file is named \fI_proverc\fR rather than
148 \&\fI.proverc\fR and is sought only in the current directory.
149 .ie n .SS "Reading from ""STDIN"""
150 .el .SS "Reading from \f(CWSTDIN\fP"
151 .IX Subsection "Reading from STDIN"
152 If you have a list of tests (or URLs, or anything else you want to test) in a
153 file, you can add them to your tests by using a '\-':
154 .PP
155 .Vb 1
156 \& prove \- < my_list_of_things_to_test.txt
157 .Ve
158 .PP
159 See the \f(CW\*(C`README\*(C'\fR in the \f(CW\*(C`examples\*(C'\fR directory of this distribution.
160 .SS "Default Test Directory"
161 .IX Subsection "Default Test Directory"
162 If no files or directories are supplied, \f(CW\*(C`prove\*(C'\fR looks for all files
163 matching the pattern \f(CW\*(C`t/*.t\*(C'\fR.
164 .SS "Colored Test Output"
165 .IX Subsection "Colored Test Output"
166 Colored test output using TAP::Formatter::Color is the default, but
167 if output is not to a terminal, color is disabled. You can override this by
168 adding the \f(CW\*(C`\-\-color\*(C'\fR switch.
169 .PP
170 Color support requires Term::ANSIColor and, on windows platforms, also
171 Win32::Console::ANSI. If the necessary module(s) are not installed
172 colored output will not be available.
173 .SS "Exit Code"
174 .IX Subsection "Exit Code"
175 If the tests fail \f(CW\*(C`prove\*(C'\fR will exit with non-zero status.
176 .SS "Arguments to Tests"
177 .IX Subsection "Arguments to Tests"
178 It is possible to supply arguments to tests. To do so separate them from
179 prove's own arguments with the arisdottle, '::'. For example
180 .PP
181 .Vb 1
182 \& prove \-v t/mytest.t :: \-\-url http://example.com
183 .Ve
184 .PP
185 would run \fIt/mytest.t\fR with the options '\-\-url http://example.com'.
186 When running multiple tests they will each receive the same arguments.
187 .ie n .SS """\-\-exec"""
188 .el .SS \f(CW\-\-exec\fP
189 .IX Subsection "--exec"
190 Normally you can just pass a list of Perl tests and the harness will know how
191 to execute them. However, if your tests are not written in Perl or if you
192 want all tests invoked exactly the same way, use the \f(CW\*(C`\-e\*(C'\fR, or \f(CW\*(C`\-\-exec\*(C'\fR
193 switch:
194 .PP
195 .Vb 3
196 \& prove \-\-exec \*(Aq/usr/bin/ruby \-w\*(Aq t/
197 \& prove \-\-exec \*(Aq/usr/bin/perl \-Tw \-mstrict \-Ilib\*(Aq t/
198 \& prove \-\-exec \*(Aq/path/to/my/customer/exec\*(Aq
199 .Ve
200 .ie n .SS """\-\-merge"""
201 .el .SS \f(CW\-\-merge\fP
202 .IX Subsection "--merge"
203 If you need to make sure your diagnostics are displayed in the correct
204 order relative to test results you can use the \f(CW\*(C`\-\-merge\*(C'\fR option to
205 merge the test scripts' STDERR into their STDOUT.
206 .PP
207 This guarantees that STDOUT (where the test results appear) and STDERR
208 (where the diagnostics appear) will stay in sync. The harness will
209 display any diagnostics your tests emit on STDERR.
210 .PP
211 Caveat: this is a bit of a kludge. In particular note that if anything
212 that appears on STDERR looks like a test result the test harness will
213 get confused. Use this option only if you understand the consequences
214 and can live with the risk.
215 .ie n .SS """\-\-trap"""
216 .el .SS \f(CW\-\-trap\fP
217 .IX Subsection "--trap"
218 The \f(CW\*(C`\-\-trap\*(C'\fR option will attempt to trap SIGINT (Ctrl-C) during a test
219 run and display the test summary even if the run is interrupted
220 .ie n .SS """\-\-state"""
221 .el .SS \f(CW\-\-state\fP
222 .IX Subsection "--state"
223 You can ask \f(CW\*(C`prove\*(C'\fR to remember the state of previous test runs and
224 select and/or order the tests to be run based on that saved state.
225 .PP
226 The \f(CW\*(C`\-\-state\*(C'\fR switch requires an argument which must be a comma
227 separated list of one or more of the following options.
228 .ie n .IP """last""" 4
229 .el .IP \f(CWlast\fR 4
230 .IX Item "last"
231 Run the same tests as the last time the state was saved. This makes it
232 possible, for example, to recreate the ordering of a shuffled test.
233 .Sp
234 .Vb 2
235 \& # Run all tests in random order
236 \& $ prove \-b \-\-state=save \-\-shuffle
237 \&
238 \& # Run them again in the same order
239 \& $ prove \-b \-\-state=last
240 .Ve
241 .ie n .IP """failed""" 4
242 .el .IP \f(CWfailed\fR 4
243 .IX Item "failed"
244 Run only the tests that failed on the last run.
245 .Sp
246 .Vb 2
247 \& # Run all tests
248 \& $ prove \-b \-\-state=save
249 \&
250 \& # Run failures
251 \& $ prove \-b \-\-state=failed
252 .Ve
253 .Sp
254 If you also specify the \f(CW\*(C`save\*(C'\fR option newly passing tests will be
255 excluded from subsequent runs.
256 .Sp
257 .Vb 2
258 \& # Repeat until no more failures
259 \& $ prove \-b \-\-state=failed,save
260 .Ve
261 .ie n .IP """passed""" 4
262 .el .IP \f(CWpassed\fR 4
263 .IX Item "passed"
264 Run only the passed tests from last time. Useful to make sure that no
265 new problems have been introduced.
266 .ie n .IP """all""" 4
267 .el .IP \f(CWall\fR 4
268 .IX Item "all"
269 Run all tests in normal order. Multiple options may be specified, so to
270 run all tests with the failures from last time first:
271 .Sp
272 .Vb 1
273 \& $ prove \-b \-\-state=failed,all,save
274 .Ve
275 .ie n .IP """hot""" 4
276 .el .IP \f(CWhot\fR 4
277 .IX Item "hot"
278 Run the tests that most recently failed first. The last failure time of
279 each test is stored. The \f(CW\*(C`hot\*(C'\fR option causes tests to be run in most\-recent\-
280 failure order.
281 .Sp
282 .Vb 1
283 \& $ prove \-b \-\-state=hot,save
284 .Ve
285 .Sp
286 Tests that have never failed will not be selected. To run all tests with
287 the most recently failed first use
288 .Sp
289 .Vb 1
290 \& $ prove \-b \-\-state=hot,all,save
291 .Ve
292 .Sp
293 This combination of options may also be specified thus
294 .Sp
295 .Vb 1
296 \& $ prove \-b \-\-state=adrian
297 .Ve
298 .ie n .IP """todo""" 4
299 .el .IP \f(CWtodo\fR 4
300 .IX Item "todo"
301 Run any tests with todos.
302 .ie n .IP """slow""" 4
303 .el .IP \f(CWslow\fR 4
304 .IX Item "slow"
305 Run the tests in slowest to fastest order. This is useful in conjunction
306 with the \f(CW\*(C`\-j\*(C'\fR parallel testing switch to ensure that your slowest tests
307 start running first.
308 .Sp
309 .Vb 1
310 \& $ prove \-b \-\-state=slow \-j9
311 .Ve
312 .ie n .IP """fast""" 4
313 .el .IP \f(CWfast\fR 4
314 .IX Item "fast"
315 Run test tests in fastest to slowest order.
316 .ie n .IP """new""" 4
317 .el .IP \f(CWnew\fR 4
318 .IX Item "new"
319 Run the tests in newest to oldest order based on the modification times
320 of the test scripts.
321 .ie n .IP """old""" 4
322 .el .IP \f(CWold\fR 4
323 .IX Item "old"
324 Run the tests in oldest to newest order.
325 .ie n .IP """fresh""" 4
326 .el .IP \f(CWfresh\fR 4
327 .IX Item "fresh"
328 Run those test scripts that have been modified since the last test run.
329 .ie n .IP """save""" 4
330 .el .IP \f(CWsave\fR 4
331 .IX Item "save"
332 Save the state on exit. The state is stored in a file called \fI.prove\fR
333 (\fI_prove\fR on Windows and VMS) in the current directory.
334 .PP
335 The \f(CW\*(C`\-\-state\*(C'\fR switch may be used more than once.
336 .PP
337 .Vb 1
338 \& $ prove \-b \-\-state=hot \-\-state=all,save
339 .Ve
340 .SS \-\-rules
341 .IX Subsection "--rules"
342 The \f(CW\*(C`\-\-rules\*(C'\fR option is used to control which tests are run sequentially and
343 which are run in parallel, if the \f(CW\*(C`\-\-jobs\*(C'\fR option is specified. The option may
344 be specified multiple times, and the order matters.
345 .PP
346 The most practical use is likely to specify that some tests are not
347 "parallel-ready". Since mentioning a file with \-\-rules doesn't cause it to
348 be selected to run as a test, you can "set and forget" some rules preferences in
349 your .proverc file. Then you'll be able to take maximum advantage of the
350 performance benefits of parallel testing, while some exceptions are still run
351 in parallel.
352 .PP
353 \fI\-\-rules examples\fR
354 .IX Subsection "--rules examples"
355 .PP
356 .Vb 2
357 \& # All tests are allowed to run in parallel, except those starting with "p"
358 \& \-\-rules=\*(Aqseq=t/p*.t\*(Aq \-\-rules=\*(Aqpar=**\*(Aq
359 \&
360 \& # All tests must run in sequence except those starting with "p", which should be run parallel
361 \& \-\-rules=\*(Aqpar=t/p*.t\*(Aq
362 .Ve
363 .PP
364 \fI\-\-rules resolution\fR
365 .IX Subsection "--rules resolution"
366 .IP \(bu 4
367 By default, all tests are eligible to be run in parallel. Specifying any of your own rules removes this one.
368 .IP \(bu 4
369 "First match wins". The first rule that matches a test will be the one that applies.
370 .IP \(bu 4
371 Any test which does not match a rule will be run in sequence at the end of the run.
372 .IP \(bu 4
373 The existence of a rule does not imply selecting a test. You must still specify the tests to run.
374 .IP \(bu 4
375 Specifying a rule to allow tests to run in parallel does not make them run in parallel. You still need specify the number of parallel \f(CW\*(C`jobs\*(C'\fR in your Harness object.
376 .PP
377 \fI\-\-rules Glob-style pattern matching\fR
378 .IX Subsection "--rules Glob-style pattern matching"
379 .PP
380 We implement our own glob-style pattern matching for \-\-rules. Here are the
381 supported patterns:
382 .PP
383 .Vb 5
384 \& ** is any number of characters, including /, within a pathname
385 \& * is zero or more characters within a filename/directory name
386 \& ? is exactly one character within a filename/directory name
387 \& {foo,bar,baz} is any of foo, bar or baz.
388 \& \e is an escape character
389 .Ve
390 .PP
391 \fIMore advanced specifications for parallel vs sequence run rules\fR
392 .IX Subsection "More advanced specifications for parallel vs sequence run rules"
393 .PP
394 If you need more advanced management of what runs in parallel vs in sequence, see
395 the associated 'rules' documentation in TAP::Harness and TAP::Parser::Scheduler.
396 If what's possible directly through \f(CW\*(C`prove\*(C'\fR is not sufficient, you can write your own
397 harness to access these features directly.
398 .ie n .SS @INC
399 .el .SS \f(CW@INC\fP
400 .IX Subsection "@INC"
401 prove introduces a separation between "options passed to the perl which
402 runs prove" and "options passed to the perl which runs tests"; this
403 distinction is by design. Thus the perl which is running a test starts
404 with the default \f(CW@INC\fR. Additional library directories can be added
405 via the \f(CW\*(C`PERL5LIB\*(C'\fR environment variable, via \-Ifoo in \f(CW\*(C`PERL5OPT\*(C'\fR or
406 via the \f(CW\*(C`\-Ilib\*(C'\fR option to \fIprove\fR.
407 .SS "Taint Mode"
408 .IX Subsection "Taint Mode"
409 Normally when a Perl program is run in taint mode the contents of the
410 \&\f(CW\*(C`PERL5LIB\*(C'\fR environment variable do not appear in \f(CW@INC\fR.
411 .PP
412 Because \f(CW\*(C`PERL5LIB\*(C'\fR is often used during testing to add build
413 directories to \f(CW@INC\fR prove passes the names of any directories found
414 in \f(CW\*(C`PERL5LIB\*(C'\fR as \-I switches. The net effect of this is that
415 \&\f(CW\*(C`PERL5LIB\*(C'\fR is honoured even when prove is run in taint mode.
416 .SH FORMATTERS
417 .IX Header "FORMATTERS"
418 You can load a custom TAP::Parser::Formatter:
419 .PP
420 .Vb 1
421 \& prove \-\-formatter MyFormatter
422 .Ve
423 .SH "SOURCE HANDLERS"
424 .IX Header "SOURCE HANDLERS"
425 You can load custom TAP::Parser::SourceHandlers, to change the way the
426 parser interprets particular \fIsources\fR of TAP.
427 .PP
428 .Vb 1
429 \& prove \-\-source MyHandler \-\-source YetAnother t
430 .Ve
431 .PP
432 If you want to provide config to the source you can use:
433 .PP
434 .Vb 4
435 \& prove \-\-source MyCustom \e
436 \& \-\-source Perl \-\-perl\-option \*(Aqfoo=bar baz\*(Aq \-\-perl\-option avg=0.278 \e
437 \& \-\-source File \-\-file\-option extensions=.txt \-\-file\-option extensions=.tmp t
438 \& \-\-source pgTAP \-\-pgtap\-option pset=format=html \-\-pgtap\-option pset=border=2
439 .Ve
440 .PP
441 Each \f(CW\*(C`\-\-$source\-option\*(C'\fR option must specify a key/value pair separated by an
442 \&\f(CW\*(C`=\*(C'\fR. If an option can take multiple values, just specify it multiple times,
443 as with the \f(CW\*(C`extensions=\*(C'\fR examples above. If the option should be a hash
444 reference, specify the value as a second pair separated by a \f(CW\*(C`=\*(C'\fR, as in the
445 \&\f(CW\*(C`pset=\*(C'\fR examples above (escape \f(CW\*(C`=\*(C'\fR with a backslash).
446 .PP
447 All \f(CW\*(C`\-\-sources\*(C'\fR are combined into a hash, and passed to "new" in TAP::Harness's
448 \&\f(CW\*(C`sources\*(C'\fR parameter.
449 .PP
450 See TAP::Parser::IteratorFactory for more details on how configuration is
451 passed to \fISourceHandlers\fR.
452 .SH PLUGINS
453 .IX Header "PLUGINS"
454 Plugins can be loaded using the \f(CW\*(C`\-P\fR\f(CIplugin\fR\f(CW\*(C'\fR syntax, eg:
455 .PP
456 .Vb 1
457 \& prove \-PMyPlugin
458 .Ve
459 .PP
460 This will search for a module named \f(CW\*(C`App::Prove::Plugin::MyPlugin\*(C'\fR, or failing
461 that, \f(CW\*(C`MyPlugin\*(C'\fR. If the plugin can't be found, \f(CW\*(C`prove\*(C'\fR will complain & exit.
462 .PP
463 You can pass arguments to your plugin by appending \f(CW\*(C`=arg1,arg2,etc\*(C'\fR to the
464 plugin name:
465 .PP
466 .Vb 1
467 \& prove \-PMyPlugin=fou,du,fafa
468 .Ve
469 .PP
470 Please check individual plugin documentation for more details.
471 .SS "Available Plugins"
472 .IX Subsection "Available Plugins"
473 For an up-to-date list of plugins available, please check CPAN:
474 .PP
475 <https://metacpan.org/search?q=App%3A%3AProve+Plugin>
476 .SS "Writing Plugins"
477 .IX Subsection "Writing Plugins"
478 Please see "PLUGINS" in App::Prove.