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