bin/prove

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