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