3 BEGIN { pop @INC if $INC[-1] eq '.' }
8 my $app = App::Prove->new;
9 $app->process_args(@ARGV);
10 exit( $app->run ? 0 : 1 );
16 prove - Run tests through a TAP harness.
20 prove [options] [files or directories]
26 -v, --verbose Print all test lines.
27 -l, --lib Add 'lib' to the path for your tests (-Ilib).
28 -b, --blib Add 'blib/lib' and 'blib/arch' to the path for
30 -s, --shuffle Run the tests in random order.
31 -c, --color Colored test output (default).
32 --nocolor Do not color test output.
33 --count Show the X/Y test count when not verbose
35 --nocount Disable the X/Y test count.
36 -D --dry Dry run. Show test that would have run.
37 -f, --failures Show failed tests.
38 -o, --comments Show comments.
39 --ignore-exit Ignore exit status from test scripts.
40 -m, --merge Merge test scripts' STDERR with their STDOUT.
41 -r, --recurse Recursively descend into directories.
42 --reverse Run the tests in reverse order.
43 -q, --quiet Suppress some test output while running tests.
44 -Q, --QUIET Only print summary results.
45 -p, --parse Show full list of TAP parse errors, if any.
46 --directives Only show results with TODO or SKIP directives.
47 --timer Print elapsed time after each test.
48 --trap Trap Ctrl-C and print summary on interrupt.
49 --normalize Normalize TAP output in verbose output
50 -T Enable tainting checks.
51 -t Enable tainting warnings.
52 -W Enable fatal warnings.
54 -h, --help Display this help
56 -V, --version Display the version
57 -H, --man Longer manpage for prove
58 --norc Don't process default .proverc
60 Options that take arguments:
62 -I Library paths to include.
63 -P Load plugin (searches App::Prove::Plugin::*.)
65 -e, --exec Interpreter to run the tests ('' for compiled
67 --ext Set the extension for tests (default '.t')
68 --harness Define test harness to use. See TAP::Harness.
69 --formatter Result formatter to use. See FORMATTERS.
70 --source Load and/or configure a SourceHandler. See
72 -a, --archive out.tgz Store the resulting TAP in an archive file.
73 -j, --jobs N Run N test jobs in parallel (try 9.)
74 --state=opts Control prove's persistent state.
75 --rc=rcfile Process options from rcfile
76 --rules Rules for parallel vs sequential processing.
82 If F<~/.proverc> or F<./.proverc> exist they will be read and any
83 options they contain processed before the command line options. Options
84 in F<.proverc> are specified in the same way as command line options:
90 Additional option files may be specified with the C<--rc> option.
91 Default option file processing is disabled by the C<--norc> option.
93 Under Windows and VMS the option file is named F<_proverc> rather than
94 F<.proverc> and is sought only in the current directory.
96 =head2 Reading from C<STDIN>
98 If you have a list of tests (or URLs, or anything else you want to test) in a
99 file, you can add them to your tests by using a '-':
101 prove - < my_list_of_things_to_test.txt
103 See the C<README> in the C<examples> directory of this distribution.
105 =head2 Default Test Directory
107 If no files or directories are supplied, C<prove> looks for all files
108 matching the pattern C<t/*.t>.
110 =head2 Colored Test Output
112 Colored test output using L<TAP::Formatter::Color> is the default, but
113 if output is not to a terminal, color is disabled. You can override this by
114 adding the C<--color> switch.
116 Color support requires L<Term::ANSIColor> on Unix-like platforms and
117 L<Win32::Console> on windows. If the necessary module is not installed
118 colored output will not be available.
122 If the tests fail C<prove> will exit with non-zero status.
124 =head2 Arguments to Tests
126 It is possible to supply arguments to tests. To do so separate them from
127 prove's own arguments with the arisdottle, '::'. For example
129 prove -v t/mytest.t :: --url http://example.com
131 would run F<t/mytest.t> with the options '--url http://example.com'.
132 When running multiple tests they will each receive the same arguments.
136 Normally you can just pass a list of Perl tests and the harness will know how
137 to execute them. However, if your tests are not written in Perl or if you
138 want all tests invoked exactly the same way, use the C<-e>, or C<--exec>
141 prove --exec '/usr/bin/ruby -w' t/
142 prove --exec '/usr/bin/perl -Tw -mstrict -Ilib' t/
143 prove --exec '/path/to/my/customer/exec'
147 If you need to make sure your diagnostics are displayed in the correct
148 order relative to test results you can use the C<--merge> option to
149 merge the test scripts' STDERR into their STDOUT.
151 This guarantees that STDOUT (where the test results appear) and STDERR
152 (where the diagnostics appear) will stay in sync. The harness will
153 display any diagnostics your tests emit on STDERR.
155 Caveat: this is a bit of a kludge. In particular note that if anything
156 that appears on STDERR looks like a test result the test harness will
157 get confused. Use this option only if you understand the consequences
158 and can live with the risk.
162 The C<--trap> option will attempt to trap SIGINT (Ctrl-C) during a test
163 run and display the test summary even if the run is interrupted
167 You can ask C<prove> to remember the state of previous test runs and
168 select and/or order the tests to be run based on that saved state.
170 The C<--state> switch requires an argument which must be a comma
171 separated list of one or more of the following options.
177 Run the same tests as the last time the state was saved. This makes it
178 possible, for example, to recreate the ordering of a shuffled test.
180 # Run all tests in random order
181 $ prove -b --state=save --shuffle
183 # Run them again in the same order
184 $ prove -b --state=last
188 Run only the tests that failed on the last run.
191 $ prove -b --state=save
194 $ prove -b --state=failed
196 If you also specify the C<save> option newly passing tests will be
197 excluded from subsequent runs.
199 # Repeat until no more failures
200 $ prove -b --state=failed,save
204 Run only the passed tests from last time. Useful to make sure that no
205 new problems have been introduced.
209 Run all tests in normal order. Multple options may be specified, so to
210 run all tests with the failures from last time first:
212 $ prove -b --state=failed,all,save
216 Run the tests that most recently failed first. The last failure time of
217 each test is stored. The C<hot> option causes tests to be run in most-recent-
220 $ prove -b --state=hot,save
222 Tests that have never failed will not be selected. To run all tests with
223 the most recently failed first use
225 $ prove -b --state=hot,all,save
227 This combination of options may also be specified thus
229 $ prove -b --state=adrian
233 Run any tests with todos.
237 Run the tests in slowest to fastest order. This is useful in conjunction
238 with the C<-j> parallel testing switch to ensure that your slowest tests
241 $ prove -b --state=slow -j9
245 Run test tests in fastest to slowest order.
249 Run the tests in newest to oldest order based on the modification times
254 Run the tests in oldest to newest order.
258 Run those test scripts that have been modified since the last test run.
262 Save the state on exit. The state is stored in a file called F<.prove>
263 (F<_prove> on Windows and VMS) in the current directory.
267 The C<--state> switch may be used more than once.
269 $ prove -b --state=hot --state=all,save
273 The C<--rules> option is used to control which tests are run sequentially and
274 which are run in parallel, if the C<--jobs> option is specified. The option may
275 be specified multiple times, and the order matters.
277 The most practical use is likely to specify that some tests are not
278 "parallel-ready". Since mentioning a file with --rules doesn't cause it to
279 be selected to run as a test, you can "set and forget" some rules preferences in
280 your .proverc file. Then you'll be able to take maximum advantage of the
281 performance benefits of parallel testing, while some exceptions are still run
284 =head3 --rules examples
286 # All tests are allowed to run in parallel, except those starting with "p"
287 --rules='seq=t/p*.t' --rules='par=**'
289 # All tests must run in sequence except those starting with "p", which should be run parallel
292 =head3 --rules resolution
296 =item * By default, all tests are eligible to be run in parallel. Specifying any of your own rules removes this one.
298 =item * "First match wins". The first rule that matches a test will be the one that applies.
300 =item * Any test which does not match a rule will be run in sequence at the end of the run.
302 =item * The existence of a rule does not imply selecting a test. You must still specify the tests to run.
304 =item * 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 C<jobs> in your Harness object.
308 =head3 --rules Glob-style pattern matching
310 We implement our own glob-style pattern matching for --rules. Here are the
313 ** is any number of characters, including /, within a pathname
314 * is zero or more characters within a filename/directory name
315 ? is exactly one character within a filename/directory name
316 {foo,bar,baz} is any of foo, bar or baz.
317 \ is an escape character
319 =head3 More advanced specifications for parallel vs sequence run rules
321 If you need more advanced management of what runs in parallel vs in sequence, see
322 the associated 'rules' documentation in L<TAP::Harness> and L<TAP::Parser::Scheduler>.
323 If what's possible directly through C<prove> is not sufficient, you can write your own
324 harness to access these features directly.
328 prove introduces a separation between "options passed to the perl which
329 runs prove" and "options passed to the perl which runs tests"; this
330 distinction is by design. Thus the perl which is running a test starts
331 with the default C<@INC>. Additional library directories can be added
332 via the C<PERL5LIB> environment variable, via -Ifoo in C<PERL5OPT> or
333 via the C<-Ilib> option to F<prove>.
337 Normally when a Perl program is run in taint mode the contents of the
338 C<PERL5LIB> environment variable do not appear in C<@INC>.
340 Because C<PERL5LIB> is often used during testing to add build
341 directories to C<@INC> prove passes the names of any directories found
342 in C<PERL5LIB> as -I switches. The net effect of this is that
343 C<PERL5LIB> is honoured even when prove is run in taint mode.
348 You can load a custom L<TAP::Parser::Formatter>:
350 prove --formatter MyFormatter
352 =head1 SOURCE HANDLERS
354 You can load custom L<TAP::Parser::SourceHandler>s, to change the way the
355 parser interprets particular I<sources> of TAP.
357 prove --source MyHandler --source YetAnother t
359 If you want to provide config to the source you can use:
361 prove --source MyCustom \
362 --source Perl --perl-option 'foo=bar baz' --perl-option avg=0.278 \
363 --source File --file-option extensions=.txt --file-option extensions=.tmp t
364 --source pgTAP --pgtap-option pset=format=html --pgtap-option pset=border=2
366 Each C<--$source-option> option must specify a key/value pair separated by an
367 C<=>. If an option can take multiple values, just specify it multiple times,
368 as with the C<extensions=> examples above. If the option should be a hash
369 reference, specify the value as a second pair separated by a C<=>, as in the
370 C<pset=> examples above (escape C<=> with a backslash).
372 All C<--sources> are combined into a hash, and passed to L<TAP::Harness/new>'s
373 C<sources> parameter.
375 See L<TAP::Parser::IteratorFactory> for more details on how configuration is
376 passed to I<SourceHandlers>.
380 Plugins can be loaded using the C<< -PI<plugin> >> syntax, eg:
384 This will search for a module named C<App::Prove::Plugin::MyPlugin>, or failing
385 that, C<MyPlugin>. If the plugin can't be found, C<prove> will complain & exit.
387 You can pass arguments to your plugin by appending C<=arg1,arg2,etc> to the
390 prove -PMyPlugin=fou,du,fafa
392 Please check individual plugin documentation for more details.
394 =head2 Available Plugins
396 For an up-to-date list of plugins available, please check CPAN:
398 L<http://search.cpan.org/search?query=App%3A%3AProve+Plugin>
400 =head2 Writing Plugins
402 Please see L<App::Prove/PLUGINS>.
406 # vim:ts=4:sw=4:et:sta