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