Debian Codegraph @

upstream/mageia-cauldron/man1/prove.1

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