1PROVE(1)              User Contributed Perl Documentation             PROVE(1)
2
3
4

NAME

6       prove - Run tests through a TAP harness.
7

USAGE

9        prove [options] [files or directories]
10

OPTIONS

12       Boolean options:
13
14        -v,  --verbose         Print all test lines.
15        -l,  --lib             Add 'lib' to the path for your tests (-Ilib).
16        -b,  --blib            Add 'blib/lib' and 'blib/arch' to the path for
17                               your tests
18        -s,  --shuffle         Run the tests in random order.
19        -c,  --color           Colored test output (default).
20             --nocolor         Do not color test output.
21             --count           Show the X/Y test count when not verbose
22                               (default)
23             --nocount         Disable the X/Y test count.
24        -D   --dry             Dry run. Show test that would have run.
25        -f,  --failures        Show failed tests.
26        -o,  --comments        Show comments.
27             --ignore-exit     Ignore exit status from test scripts.
28        -m,  --merge           Merge test scripts' STDERR with their STDOUT.
29        -r,  --recurse         Recursively descend into directories.
30             --reverse         Run the tests in reverse order.
31        -q,  --quiet           Suppress some test output while running tests.
32        -Q,  --QUIET           Only print summary results.
33        -p,  --parse           Show full list of TAP parse errors, if any.
34             --directives      Only show results with TODO or SKIP directives.
35             --timer           Print elapsed time after each test.
36             --trap            Trap Ctrl-C and print summary on interrupt.
37             --normalize       Normalize TAP output in verbose output
38        -T                     Enable tainting checks.
39        -t                     Enable tainting warnings.
40        -W                     Enable fatal warnings.
41        -w                     Enable warnings.
42        -h,  --help            Display this help
43        -?,                    Display this help
44        -V,  --version         Display the version
45        -H,  --man             Longer manpage for prove
46             --norc            Don't process default .proverc
47
48       Options that take arguments:
49
50        -I                     Library paths to include.
51        -P                     Load plugin (searches App::Prove::Plugin::*.)
52        -M                     Load a module.
53        -e,  --exec            Interpreter to run the tests ('' for compiled
54                               tests.)
55             --ext             Set the extension for tests (default '.t')
56             --harness         Define test harness to use.  See TAP::Harness.
57             --formatter       Result formatter to use. See FORMATTERS.
58             --source          Load and/or configure a SourceHandler. See
59                               SOURCE HANDLERS.
60        -a,  --archive out.tgz Store the resulting TAP in an archive file.
61        -j,  --jobs N          Run N test jobs in parallel (try 9.)
62             --state=opts      Control prove's persistent state.
63             --statefile=file  Use `file` instead of `.prove` for state
64             --rc=rcfile       Process options from rcfile
65             --rules           Rules for parallel vs sequential processing.
66

NOTES

68   .proverc
69       If ~/.proverc or ./.proverc exist they will be read and any options
70       they contain processed before the command line options. Options in
71       .proverc are specified in the same way as command line options:
72
73           # .proverc
74           --state=hot,fast,save
75           -j9
76
77       Additional option files may be specified with the "--rc" option.
78       Default option file processing is disabled by the "--norc" option.
79
80       Under Windows and VMS the option file is named _proverc rather than
81       .proverc and is sought only in the current directory.
82
83   Reading from "STDIN"
84       If you have a list of tests (or URLs, or anything else you want to
85       test) in a file, you can add them to your tests by using a '-':
86
87        prove - < my_list_of_things_to_test.txt
88
89       See the "README" in the "examples" directory of this distribution.
90
91   Default Test Directory
92       If no files or directories are supplied, "prove" looks for all files
93       matching the pattern "t/*.t".
94
95   Colored Test Output
96       Colored test output using TAP::Formatter::Color is the default, but if
97       output is not to a terminal, color is disabled. You can override this
98       by adding the "--color" switch.
99
100       Color support requires Term::ANSIColor and, on windows platforms, also
101       Win32::Console::ANSI. If the necessary module(s) are not installed
102       colored output will not be available.
103
104   Exit Code
105       If the tests fail "prove" will exit with non-zero status.
106
107   Arguments to Tests
108       It is possible to supply arguments to tests. To do so separate them
109       from prove's own arguments with the arisdottle, '::'. For example
110
111        prove -v t/mytest.t :: --url http://example.com
112
113       would run t/mytest.t with the options '--url http://example.com'.  When
114       running multiple tests they will each receive the same arguments.
115
116   "--exec"
117       Normally you can just pass a list of Perl tests and the harness will
118       know how to execute them.  However, if your tests are not written in
119       Perl or if you want all tests invoked exactly the same way, use the
120       "-e", or "--exec" switch:
121
122        prove --exec '/usr/bin/ruby -w' t/
123        prove --exec '/usr/bin/perl -Tw -mstrict -Ilib' t/
124        prove --exec '/path/to/my/customer/exec'
125
126   "--merge"
127       If you need to make sure your diagnostics are displayed in the correct
128       order relative to test results you can use the "--merge" option to
129       merge the test scripts' STDERR into their STDOUT.
130
131       This guarantees that STDOUT (where the test results appear) and STDERR
132       (where the diagnostics appear) will stay in sync. The harness will
133       display any diagnostics your tests emit on STDERR.
134
135       Caveat: this is a bit of a kludge. In particular note that if anything
136       that appears on STDERR looks like a test result the test harness will
137       get confused. Use this option only if you understand the consequences
138       and can live with the risk.
139
140   "--trap"
141       The "--trap" option will attempt to trap SIGINT (Ctrl-C) during a test
142       run and display the test summary even if the run is interrupted
143
144   "--state"
145       You can ask "prove" to remember the state of previous test runs and
146       select and/or order the tests to be run based on that saved state.
147
148       The "--state" switch requires an argument which must be a comma
149       separated list of one or more of the following options.
150
151       "last"
152           Run the same tests as the last time the state was saved. This makes
153           it possible, for example, to recreate the ordering of a shuffled
154           test.
155
156               # Run all tests in random order
157               $ prove -b --state=save --shuffle
158
159               # Run them again in the same order
160               $ prove -b --state=last
161
162       "failed"
163           Run only the tests that failed on the last run.
164
165               # Run all tests
166               $ prove -b --state=save
167
168               # Run failures
169               $ prove -b --state=failed
170
171           If you also specify the "save" option newly passing tests will be
172           excluded from subsequent runs.
173
174               # Repeat until no more failures
175               $ prove -b --state=failed,save
176
177       "passed"
178           Run only the passed tests from last time. Useful to make sure that
179           no new problems have been introduced.
180
181       "all"
182           Run all tests in normal order. Multple options may be specified, so
183           to run all tests with the failures from last time first:
184
185               $ prove -b --state=failed,all,save
186
187       "hot"
188           Run the tests that most recently failed first. The last failure
189           time of each test is stored. The "hot" option causes tests to be
190           run in most-recent- failure order.
191
192               $ prove -b --state=hot,save
193
194           Tests that have never failed will not be selected. To run all tests
195           with the most recently failed first use
196
197               $ prove -b --state=hot,all,save
198
199           This combination of options may also be specified thus
200
201               $ prove -b --state=adrian
202
203       "todo"
204           Run any tests with todos.
205
206       "slow"
207           Run the tests in slowest to fastest order. This is useful in
208           conjunction with the "-j" parallel testing switch to ensure that
209           your slowest tests start running first.
210
211               $ prove -b --state=slow -j9
212
213       "fast"
214           Run test tests in fastest to slowest order.
215
216       "new"
217           Run the tests in newest to oldest order based on the modification
218           times of the test scripts.
219
220       "old"
221           Run the tests in oldest to newest order.
222
223       "fresh"
224           Run those test scripts that have been modified since the last test
225           run.
226
227       "save"
228           Save the state on exit. The state is stored in a file called .prove
229           (_prove on Windows and VMS) in the current directory.
230
231       The "--state" switch may be used more than once.
232
233           $ prove -b --state=hot --state=all,save
234
235   --rules
236       The "--rules" option is used to control which tests are run
237       sequentially and which are run in parallel, if the "--jobs" option is
238       specified. The option may be specified multiple times, and the order
239       matters.
240
241       The most practical use is likely to specify that some tests are not
242       "parallel-ready".  Since mentioning a file with --rules doesn't cause
243       it to be selected to run as a test, you can "set and forget" some rules
244       preferences in your .proverc file. Then you'll be able to take maximum
245       advantage of the performance benefits of parallel testing, while some
246       exceptions are still run in parallel.
247
248       --rules examples
249
250           # All tests are allowed to run in parallel, except those starting with "p"
251           --rules='seq=t/p*.t' --rules='par=**'
252
253           # All tests must run in sequence except those starting with "p", which should be run parallel
254           --rules='par=t/p*.t'
255
256       --rules resolution
257
258       •   By default, all tests are eligible to be run in parallel.
259           Specifying any of your own rules removes this one.
260
261       •   "First match wins". The first rule that matches a test will be the
262           one that applies.
263
264       •   Any test which does not match a rule will be run in sequence at the
265           end of the run.
266
267       •   The existence of a rule does not imply selecting a test. You must
268           still specify the tests to run.
269
270       •   Specifying a rule to allow tests to run in parallel does not make
271           them run in parallel. You still need specify the number of parallel
272           "jobs" in your Harness object.
273
274       --rules Glob-style pattern matching
275
276       We implement our own glob-style pattern matching for --rules. Here are
277       the supported patterns:
278
279           ** is any number of characters, including /, within a pathname
280           * is zero or more characters within a filename/directory name
281           ? is exactly one character within a filename/directory name
282           {foo,bar,baz} is any of foo, bar or baz.
283           \ is an escape character
284
285       More advanced specifications for parallel vs sequence run rules
286
287       If you need more advanced management of what runs in parallel vs in
288       sequence, see the associated 'rules' documentation in TAP::Harness and
289       TAP::Parser::Scheduler.  If what's possible directly through "prove" is
290       not sufficient, you can write your own harness to access these features
291       directly.
292
293   @INC
294       prove introduces a separation between "options passed to the perl which
295       runs prove" and "options passed to the perl which runs tests"; this
296       distinction is by design. Thus the perl which is running a test starts
297       with the default @INC. Additional library directories can be added via
298       the "PERL5LIB" environment variable, via -Ifoo in "PERL5OPT" or via the
299       "-Ilib" option to prove.
300
301   Taint Mode
302       Normally when a Perl program is run in taint mode the contents of the
303       "PERL5LIB" environment variable do not appear in @INC.
304
305       Because "PERL5LIB" is often used during testing to add build
306       directories to @INC prove passes the names of any directories found in
307       "PERL5LIB" as -I switches. The net effect of this is that "PERL5LIB" is
308       honoured even when prove is run in taint mode.
309

FORMATTERS

311       You can load a custom TAP::Parser::Formatter:
312
313         prove --formatter MyFormatter
314

SOURCE HANDLERS

316       You can load custom TAP::Parser::SourceHandlers, to change the way the
317       parser interprets particular sources of TAP.
318
319         prove --source MyHandler --source YetAnother t
320
321       If you want to provide config to the source you can use:
322
323         prove --source MyCustom \
324               --source Perl --perl-option 'foo=bar baz' --perl-option avg=0.278 \
325               --source File --file-option extensions=.txt --file-option extensions=.tmp t
326               --source pgTAP --pgtap-option pset=format=html --pgtap-option pset=border=2
327
328       Each "--$source-option" option must specify a key/value pair separated
329       by an "=". If an option can take multiple values, just specify it
330       multiple times, as with the "extensions=" examples above. If the option
331       should be a hash reference, specify the value as a second pair
332       separated by a "=", as in the "pset=" examples above (escape "=" with a
333       backslash).
334
335       All "--sources" are combined into a hash, and passed to "new" in
336       TAP::Harness's "sources" parameter.
337
338       See TAP::Parser::IteratorFactory for more details on how configuration
339       is passed to SourceHandlers.
340

PLUGINS

342       Plugins can be loaded using the "-Pplugin" syntax, eg:
343
344         prove -PMyPlugin
345
346       This will search for a module named "App::Prove::Plugin::MyPlugin", or
347       failing that, "MyPlugin".  If the plugin can't be found, "prove" will
348       complain & exit.
349
350       You can pass arguments to your plugin by appending "=arg1,arg2,etc" to
351       the plugin name:
352
353         prove -PMyPlugin=fou,du,fafa
354
355       Please check individual plugin documentation for more details.
356
357   Available Plugins
358       For an up-to-date list of plugins available, please check CPAN:
359
360       <http://search.cpan.org/search?query=App%3A%3AProve+Plugin>
361
362   Writing Plugins
363       Please see "PLUGINS" in App::Prove.
364
365
366
367perl v5.34.0                      2021-07-23                          PROVE(1)
Impressum