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