1#!/usr/bin/perl -w 2 3BEGIN { pop @INC if $INC[-1] eq '.' } 4use strict; 5use warnings; 6use App::Prove; 7 8my $app = App::Prove->new; 9$app->process_args(@ARGV); 10exit( $app->run ? 0 : 1 ); 11 12__END__ 13 14=head1 NAME 15 16prove - Run tests through a TAP harness. 17 18=head1 USAGE 19 20 prove [options] [files or directories] 21 22=head1 OPTIONS 23 24Boolean options: 25 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 29 your tests 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 34 (default) 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. 53 -w Enable warnings. 54 -h, --help Display this help 55 -?, Display this help 56 -V, --version Display the version 57 -H, --man Longer manpage for prove 58 --norc Don't process default .proverc 59 60Options that take arguments: 61 62 -I Library paths to include. 63 -P Load plugin (searches App::Prove::Plugin::*.) 64 -M Load a module. 65 -e, --exec Interpreter to run the tests ('' for compiled 66 tests.) 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 71 SOURCE HANDLERS. 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 --statefile=file Use `file` instead of `.prove` for 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 83If F<~/.proverc> or F<./.proverc> exist they will be read and any 84options they contain processed before the command line options. Options 85in F<.proverc> are specified in the same way as command line options: 86 87 # .proverc 88 --state=hot,fast,save 89 -j9 90 91Additional option files may be specified with the C<--rc> option. 92Default option file processing is disabled by the C<--norc> option. 93 94Under Windows and VMS the option file is named F<_proverc> rather than 95F<.proverc> and is sought only in the current directory. 96 97=head2 Reading from C<STDIN> 98 99If you have a list of tests (or URLs, or anything else you want to test) in a 100file, you can add them to your tests by using a '-': 101 102 prove - < my_list_of_things_to_test.txt 103 104See the C<README> in the C<examples> directory of this distribution. 105 106=head2 Default Test Directory 107 108If no files or directories are supplied, C<prove> looks for all files 109matching the pattern C<t/*.t>. 110 111=head2 Colored Test Output 112 113Colored test output using L<TAP::Formatter::Color> is the default, but 114if output is not to a terminal, color is disabled. You can override this by 115adding the C<--color> switch. 116 117Color support requires L<Term::ANSIColor> and, on windows platforms, also 118L<Win32::Console::ANSI>. If the necessary module(s) are not installed 119colored output will not be available. 120 121=head2 Exit Code 122 123If the tests fail C<prove> will exit with non-zero status. 124 125=head2 Arguments to Tests 126 127It is possible to supply arguments to tests. To do so separate them from 128prove's own arguments with the arisdottle, '::'. For example 129 130 prove -v t/mytest.t :: --url http://example.com 131 132would run F<t/mytest.t> with the options '--url http://example.com'. 133When running multiple tests they will each receive the same arguments. 134 135=head2 C<--exec> 136 137Normally you can just pass a list of Perl tests and the harness will know how 138to execute them. However, if your tests are not written in Perl or if you 139want all tests invoked exactly the same way, use the C<-e>, or C<--exec> 140switch: 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 148If you need to make sure your diagnostics are displayed in the correct 149order relative to test results you can use the C<--merge> option to 150merge the test scripts' STDERR into their STDOUT. 151 152This guarantees that STDOUT (where the test results appear) and STDERR 153(where the diagnostics appear) will stay in sync. The harness will 154display any diagnostics your tests emit on STDERR. 155 156Caveat: this is a bit of a kludge. In particular note that if anything 157that appears on STDERR looks like a test result the test harness will 158get confused. Use this option only if you understand the consequences 159and can live with the risk. 160 161=head2 C<--trap> 162 163The C<--trap> option will attempt to trap SIGINT (Ctrl-C) during a test 164run and display the test summary even if the run is interrupted 165 166=head2 C<--state> 167 168You can ask C<prove> to remember the state of previous test runs and 169select and/or order the tests to be run based on that saved state. 170 171The C<--state> switch requires an argument which must be a comma 172separated list of one or more of the following options. 173 174=over 175 176=item C<last> 177 178Run the same tests as the last time the state was saved. This makes it 179possible, 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 189Run 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 197If you also specify the C<save> option newly passing tests will be 198excluded from subsequent runs. 199 200 # Repeat until no more failures 201 $ prove -b --state=failed,save 202 203=item C<passed> 204 205Run only the passed tests from last time. Useful to make sure that no 206new problems have been introduced. 207 208=item C<all> 209 210Run all tests in normal order. Multple options may be specified, so to 211run all tests with the failures from last time first: 212 213 $ prove -b --state=failed,all,save 214 215=item C<hot> 216 217Run the tests that most recently failed first. The last failure time of 218each test is stored. The C<hot> option causes tests to be run in most-recent- 219failure order. 220 221 $ prove -b --state=hot,save 222 223Tests that have never failed will not be selected. To run all tests with 224the most recently failed first use 225 226 $ prove -b --state=hot,all,save 227 228This combination of options may also be specified thus 229 230 $ prove -b --state=adrian 231 232=item C<todo> 233 234Run any tests with todos. 235 236=item C<slow> 237 238Run the tests in slowest to fastest order. This is useful in conjunction 239with the C<-j> parallel testing switch to ensure that your slowest tests 240start running first. 241 242 $ prove -b --state=slow -j9 243 244=item C<fast> 245 246Run test tests in fastest to slowest order. 247 248=item C<new> 249 250Run the tests in newest to oldest order based on the modification times 251of the test scripts. 252 253=item C<old> 254 255Run the tests in oldest to newest order. 256 257=item C<fresh> 258 259Run those test scripts that have been modified since the last test run. 260 261=item C<save> 262 263Save 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 268The C<--state> switch may be used more than once. 269 270 $ prove -b --state=hot --state=all,save 271 272=head2 --rules 273 274The C<--rules> option is used to control which tests are run sequentially and 275which are run in parallel, if the C<--jobs> option is specified. The option may 276be specified multiple times, and the order matters. 277 278The 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 280be selected to run as a test, you can "set and forget" some rules preferences in 281your .proverc file. Then you'll be able to take maximum advantage of the 282performance benefits of parallel testing, while some exceptions are still run 283in 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 311We implement our own glob-style pattern matching for --rules. Here are the 312supported 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 322If you need more advanced management of what runs in parallel vs in sequence, see 323the associated 'rules' documentation in L<TAP::Harness> and L<TAP::Parser::Scheduler>. 324If what's possible directly through C<prove> is not sufficient, you can write your own 325harness to access these features directly. 326 327=head2 @INC 328 329prove introduces a separation between "options passed to the perl which 330runs prove" and "options passed to the perl which runs tests"; this 331distinction is by design. Thus the perl which is running a test starts 332with the default C<@INC>. Additional library directories can be added 333via the C<PERL5LIB> environment variable, via -Ifoo in C<PERL5OPT> or 334via the C<-Ilib> option to F<prove>. 335 336=head2 Taint Mode 337 338Normally when a Perl program is run in taint mode the contents of the 339C<PERL5LIB> environment variable do not appear in C<@INC>. 340 341Because C<PERL5LIB> is often used during testing to add build 342directories to C<@INC> prove passes the names of any directories found 343in C<PERL5LIB> as -I switches. The net effect of this is that 344C<PERL5LIB> is honoured even when prove is run in taint mode. 345 346 347=head1 FORMATTERS 348 349You can load a custom L<TAP::Parser::Formatter>: 350 351 prove --formatter MyFormatter 352 353=head1 SOURCE HANDLERS 354 355You can load custom L<TAP::Parser::SourceHandler>s, to change the way the 356parser interprets particular I<sources> of TAP. 357 358 prove --source MyHandler --source YetAnother t 359 360If 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 367Each C<--$source-option> option must specify a key/value pair separated by an 368C<=>. If an option can take multiple values, just specify it multiple times, 369as with the C<extensions=> examples above. If the option should be a hash 370reference, specify the value as a second pair separated by a C<=>, as in the 371C<pset=> examples above (escape C<=> with a backslash). 372 373All C<--sources> are combined into a hash, and passed to L<TAP::Harness/new>'s 374C<sources> parameter. 375 376See L<TAP::Parser::IteratorFactory> for more details on how configuration is 377passed to I<SourceHandlers>. 378 379=head1 PLUGINS 380 381Plugins can be loaded using the C<< -PI<plugin> >> syntax, eg: 382 383 prove -PMyPlugin 384 385This will search for a module named C<App::Prove::Plugin::MyPlugin>, or failing 386that, C<MyPlugin>. If the plugin can't be found, C<prove> will complain & exit. 387 388You can pass arguments to your plugin by appending C<=arg1,arg2,etc> to the 389plugin name: 390 391 prove -PMyPlugin=fou,du,fafa 392 393Please check individual plugin documentation for more details. 394 395=head2 Available Plugins 396 397For an up-to-date list of plugins available, please check CPAN: 398 399L<http://search.cpan.org/search?query=App%3A%3AProve+Plugin> 400 401=head2 Writing Plugins 402 403Please see L<App::Prove/PLUGINS>. 404 405=cut 406 407# vim:ts=4:sw=4:et:sta 408