bin/prove

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