File Coverage

/Users/johanl/perl5/perlbrew/perls/perl-5.18.1/bin/prove
Criterion Covered Total %
statement 13 13 100.0
branch 1 2 50.0
condition n/a
subroutine 3 3 100.0
pod n/a
total 17 18 94.4


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