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