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