codekingpro/portable-devtools

1#!/usr/bin/perl2    eval 'exec /usr/bin/perl -S $0 ${1+"$@"}'3	if 0; # ^ Run only under a shell4#!/usr/bin/perl -w5 6BEGIN { pop @INC if $INC[-1] eq '.' }7use strict;8use warnings;9use App::Prove;10 11my $app = App::Prove->new;12$app->process_args(@ARGV);13exit( $app->run ? 0 : 1 );14 15__END__16 17=head1 NAME18 19prove - Run tests through a TAP harness.20 21=head1 USAGE22 23 prove [options] [files or directories]24 25=head1 OPTIONS26 27Boolean options:28 29 -v,  --verbose         Print all test lines.  Also sets TEST_VERBOSE30 -l,  --lib             Add 'lib' to the path for your tests (-Ilib).31 -b,  --blib            Add 'blib/lib' and 'blib/arch' to the path for32                        your tests33 -s,  --shuffle         Run the tests in random order.34 -c,  --color           Colored test output (default).35      --nocolor         Do not color test output.36      --count           Show the X/Y test count when not verbose37                        (default)38      --nocount         Disable the X/Y test count.39 -D   --dry             Dry run. Show test that would have run.40 -f,  --failures        Show failed tests.41 -o,  --comments        Show comments.42      --ignore-exit     Ignore exit status from test scripts.43 -m,  --merge           Merge test scripts' STDERR with their STDOUT.44 -r,  --recurse         Recursively descend into directories.45      --reverse         Run the tests in reverse order.46 -q,  --quiet           Suppress some test output while running tests.47 -Q,  --QUIET           Only print summary results.48 -p,  --parse           Show full list of TAP parse errors, if any.49      --directives      Only show results with TODO or SKIP directives.50      --timer           Print elapsed time after each test.51      --trap            Trap Ctrl-C and print summary on interrupt.52      --normalize       Normalize TAP output in verbose output53 -T                     Enable tainting checks.54 -t                     Enable tainting warnings.55 -W                     Enable fatal warnings.56 -w                     Enable warnings.57 -h,  --help            Display this help58 -?,                    Display this help59 -V,  --version         Display the version60 -H,  --man             Longer manpage for prove61      --norc            Don't process default .proverc62 63Options that take arguments:64 65 -I                     Library paths to include.66 -P                     Load plugin (searches App::Prove::Plugin::*.)67 -M                     Load a module.68 -e,  --exec            Interpreter to run the tests ('' for compiled69                        tests.)70      --ext             Set the extension for tests (default '.t')71      --harness         Define test harness to use.  See TAP::Harness.72      --formatter       Result formatter to use. See FORMATTERS.73      --source          Load and/or configure a SourceHandler. See74                        SOURCE HANDLERS.75 -a,  --archive out.tgz Store the resulting TAP in an archive file.76 -j,  --jobs N          Run N test jobs in parallel (try 9.)77      --state=opts      Control prove's persistent state.78      --statefile=file  Use `file` instead of `.prove` for state79      --rc=rcfile       Process options from rcfile80      --rules           Rules for parallel vs sequential processing.81 82=head1 NOTES83 84=head2 .proverc85 86If F<~/.proverc> or F<./.proverc> exist they will be read and any87options they contain processed before the command line options. Options88in F<.proverc> are specified in the same way as command line options:89 90    # .proverc91    --state=hot,fast,save92    -j993 94Additional option files may be specified with the C<--rc> option.95Default option file processing is disabled by the C<--norc> option.96 97Under Windows and VMS the option file is named F<_proverc> rather than98F<.proverc> and is sought only in the current directory.99 100=head2 Reading from C<STDIN>101 102If you have a list of tests (or URLs, or anything else you want to test) in a103file, you can add them to your tests by using a '-':104 105 prove - < my_list_of_things_to_test.txt106 107See the C<README> in the C<examples> directory of this distribution.108 109=head2 Default Test Directory110 111If no files or directories are supplied, C<prove> looks for all files112matching the pattern C<t/*.t>.113 114=head2 Colored Test Output115 116Colored test output using L<TAP::Formatter::Color> is the default, but117if output is not to a terminal, color is disabled. You can override this by118adding the C<--color> switch.119 120Color support requires L<Term::ANSIColor> and, on windows platforms, also121L<Win32::Console::ANSI>. If the necessary module(s) are not installed122colored output will not be available.123 124=head2 Exit Code125 126If the tests fail C<prove> will exit with non-zero status.127 128=head2 Arguments to Tests129 130It is possible to supply arguments to tests. To do so separate them from131prove's own arguments with the arisdottle, '::'. For example132 133 prove -v t/mytest.t :: --url http://example.com134 135would run F<t/mytest.t> with the options '--url http://example.com'.136When running multiple tests they will each receive the same arguments.137 138=head2 C<--exec>139 140Normally you can just pass a list of Perl tests and the harness will know how141to execute them.  However, if your tests are not written in Perl or if you142want all tests invoked exactly the same way, use the C<-e>, or C<--exec>143switch:144 145 prove --exec '/usr/bin/ruby -w' t/146 prove --exec '/usr/bin/perl -Tw -mstrict -Ilib' t/147 prove --exec '/path/to/my/customer/exec'148 149=head2 C<--merge>150 151If you need to make sure your diagnostics are displayed in the correct152order relative to test results you can use the C<--merge> option to153merge the test scripts' STDERR into their STDOUT.154 155This guarantees that STDOUT (where the test results appear) and STDERR156(where the diagnostics appear) will stay in sync. The harness will157display any diagnostics your tests emit on STDERR.158 159Caveat: this is a bit of a kludge. In particular note that if anything160that appears on STDERR looks like a test result the test harness will161get confused. Use this option only if you understand the consequences162and can live with the risk.163 164=head2 C<--trap>165 166The C<--trap> option will attempt to trap SIGINT (Ctrl-C) during a test167run and display the test summary even if the run is interrupted168 169=head2 C<--state>170 171You can ask C<prove> to remember the state of previous test runs and172select and/or order the tests to be run based on that saved state.173 174The C<--state> switch requires an argument which must be a comma175separated list of one or more of the following options.176 177=over178 179=item C<last>180 181Run the same tests as the last time the state was saved. This makes it182possible, for example, to recreate the ordering of a shuffled test.183 184    # Run all tests in random order185    $ prove -b --state=save --shuffle186 187    # Run them again in the same order188    $ prove -b --state=last189 190=item C<failed>191 192Run only the tests that failed on the last run.193 194    # Run all tests195    $ prove -b --state=save196 197    # Run failures198    $ prove -b --state=failed199 200If you also specify the C<save> option newly passing tests will be201excluded from subsequent runs.202 203    # Repeat until no more failures204    $ prove -b --state=failed,save205 206=item C<passed>207 208Run only the passed tests from last time. Useful to make sure that no209new problems have been introduced.210 211=item C<all>212 213Run all tests in normal order. Multiple options may be specified, so to214run all tests with the failures from last time first:215 216    $ prove -b --state=failed,all,save217 218=item C<hot>219 220Run the tests that most recently failed first. The last failure time of221each test is stored. The C<hot> option causes tests to be run in most-recent-222failure order.223 224    $ prove -b --state=hot,save225 226Tests that have never failed will not be selected. To run all tests with227the most recently failed first use228 229    $ prove -b --state=hot,all,save230 231This combination of options may also be specified thus232 233    $ prove -b --state=adrian234 235=item C<todo>236 237Run any tests with todos.238 239=item C<slow>240 241Run the tests in slowest to fastest order. This is useful in conjunction242with the C<-j> parallel testing switch to ensure that your slowest tests243start running first.244 245    $ prove -b --state=slow -j9246 247=item C<fast>248 249Run test tests in fastest to slowest order.250 251=item C<new>252 253Run the tests in newest to oldest order based on the modification times254of the test scripts.255 256=item C<old>257 258Run the tests in oldest to newest order.259 260=item C<fresh>261 262Run those test scripts that have been modified since the last test run.263 264=item C<save>265 266Save the state on exit. The state is stored in a file called F<.prove>267(F<_prove> on Windows and VMS) in the current directory.268 269=back270 271The C<--state> switch may be used more than once.272 273    $ prove -b --state=hot --state=all,save274 275=head2 --rules276 277The C<--rules> option is used to control which tests are run sequentially and278which are run in parallel, if the C<--jobs> option is specified. The option may279be specified multiple times, and the order matters.280 281The most practical use is likely to specify that some tests are not282"parallel-ready".  Since mentioning a file with --rules doesn't cause it to283be selected to run as a test, you can "set and forget" some rules preferences in284your .proverc file. Then you'll be able to take maximum advantage of the285performance benefits of parallel testing, while some exceptions are still run286in parallel.287 288=head3 --rules examples289 290    # All tests are allowed to run in parallel, except those starting with "p"291    --rules='seq=t/p*.t' --rules='par=**'292 293    # All tests must run in sequence except those starting with "p", which should be run parallel294    --rules='par=t/p*.t'295 296=head3 --rules resolution297 298=over 4299 300=item * By default, all tests are eligible to be run in parallel. Specifying any of your own rules removes this one.301 302=item * "First match wins". The first rule that matches a test will be the one that applies.303 304=item * Any test which does not match a rule will be run in sequence at the end of the run.305 306=item * The existence of a rule does not imply selecting a test. You must still specify the tests to run.307 308=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.309 310=back311 312=head3 --rules Glob-style pattern matching313 314We implement our own glob-style pattern matching for --rules. Here are the315supported patterns:316 317    ** is any number of characters, including /, within a pathname318    * is zero or more characters within a filename/directory name319    ? is exactly one character within a filename/directory name320    {foo,bar,baz} is any of foo, bar or baz.321    \ is an escape character322 323=head3 More advanced specifications for parallel vs sequence run rules324 325If you need more advanced management of what runs in parallel vs in sequence, see326the associated 'rules' documentation in L<TAP::Harness> and L<TAP::Parser::Scheduler>.327If what's possible directly through C<prove> is not sufficient, you can write your own328harness to access these features directly.329 330=head2 @INC331 332prove introduces a separation between "options passed to the perl which333runs prove" and "options passed to the perl which runs tests"; this334distinction is by design. Thus the perl which is running a test starts335with the default C<@INC>. Additional library directories can be added336via the C<PERL5LIB> environment variable, via -Ifoo in C<PERL5OPT> or337via the C<-Ilib> option to F<prove>.338 339=head2 Taint Mode340 341Normally when a Perl program is run in taint mode the contents of the342C<PERL5LIB> environment variable do not appear in C<@INC>.343 344Because C<PERL5LIB> is often used during testing to add build345directories to C<@INC> prove passes the names of any directories found346in C<PERL5LIB> as -I switches. The net effect of this is that347C<PERL5LIB> is honoured even when prove is run in taint mode.348 349 350=head1 FORMATTERS351 352You can load a custom L<TAP::Parser::Formatter>:353 354  prove --formatter MyFormatter355 356=head1 SOURCE HANDLERS357 358You can load custom L<TAP::Parser::SourceHandler>s, to change the way the359parser interprets particular I<sources> of TAP.360 361  prove --source MyHandler --source YetAnother t362 363If you want to provide config to the source you can use:364 365  prove --source MyCustom \366        --source Perl --perl-option 'foo=bar baz' --perl-option avg=0.278 \367        --source File --file-option extensions=.txt --file-option extensions=.tmp t368        --source pgTAP --pgtap-option pset=format=html --pgtap-option pset=border=2369 370Each C<--$source-option> option must specify a key/value pair separated by an371C<=>. If an option can take multiple values, just specify it multiple times,372as with the C<extensions=> examples above. If the option should be a hash373reference, specify the value as a second pair separated by a C<=>, as in the374C<pset=> examples above (escape C<=> with a backslash).375 376All C<--sources> are combined into a hash, and passed to L<TAP::Harness/new>'s377C<sources> parameter.378 379See L<TAP::Parser::IteratorFactory> for more details on how configuration is380passed to I<SourceHandlers>.381 382=head1 PLUGINS383 384Plugins can be loaded using the C<< -PI<plugin> >> syntax, eg:385 386  prove -PMyPlugin387 388This will search for a module named C<App::Prove::Plugin::MyPlugin>, or failing389that, C<MyPlugin>.  If the plugin can't be found, C<prove> will complain & exit.390 391You can pass arguments to your plugin by appending C<=arg1,arg2,etc> to the392plugin name:393 394  prove -PMyPlugin=fou,du,fafa395 396Please check individual plugin documentation for more details.397 398=head2 Available Plugins399 400For an up-to-date list of plugins available, please check CPAN:401 402L<https://metacpan.org/search?q=App%3A%3AProve+Plugin>403 404=head2 Writing Plugins405 406Please see L<App::Prove/PLUGINS>.407 408=cut409 410# vim:ts=4:sw=4:et:sta411