local-lib5/man/man1/prove.1p

   1 .\" Automatically generated by Pod::Man v1.37, Pod::Parser v1.3
   2 .\"
   3 .\" Standard preamble:
   4 .\" ========================================================================
   5 .de Sh \" Subsection heading
   6 .br
   7 .if t .Sp
   8 .ne 5
   9 .PP
  10 \fB\\$1\fR
  11 .PP
  12 ..
  13 .de Sp \" Vertical space (when we can't use .PP)
  14 .if t .sp .5v
  15 .if n .sp
  16 ..
  17 .de Vb \" Begin verbatim text
  18 .ft CW
  19 .nf
  20 .ne \\$1
  21 ..
  22 .de Ve \" End verbatim text
  23 .ft R
  24 .fi
  25 ..
  26 .\" Set up some character translations and predefined strings.  \*(-- will
  27 .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
  28 .\" double quote, and \*(R" will give a right double quote.  | will give a
  29 .\" real vertical bar.  \*(C+ will give a nicer C++.  Capital omega is used to
  30 .\" do unbreakable dashes and therefore won't be available.  \*(C` and \*(C'
  31 .\" expand to `' in nroff, nothing in troff, for use with C<>.
  32 .tr \(*W-|\(bv\*(Tr
  33 .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
  34 .ie n \{\
  35 .    ds -- \(*W-
  36 .    ds PI pi
  37 .    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
  38 .    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
  39 .    ds L" ""
  40 .    ds R" ""
  41 .    ds C` ""
  42 .    ds C' ""
  43 'br\}
  44 .el\{\
  45 .    ds -- \|\(em\|
  46 .    ds PI \(*p
  47 .    ds L" ``
  48 .    ds R" ''
  49 'br\}
  50 .\"
  51 .\" If the F register is turned on, we'll generate index entries on stderr for
  52 .\" titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and index
  53 .\" entries marked with X<> in POD.  Of course, you'll have to process the
  54 .\" output yourself in some meaningful fashion.
  55 .if \nF \{\
  56 .    de IX
  57 .    tm Index:\\$1\t\\n%\t"\\$2"
  58 ..
  59 .    nr % 0
  60 .    rr F
  61 .\}
  62 .\"
  63 .\" For nroff, turn off justification.  Always turn off hyphenation; it makes
  64 .\" way too many mistakes in technical documents.
  65 .hy 0
  66 .if n .na
  67 .\"
  68 .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
  69 .\" Fear.  Run.  Save yourself.  No user-serviceable parts.
  70 .    \" fudge factors for nroff and troff
  71 .if n \{\
  72 .    ds #H 0
  73 .    ds #V .8m
  74 .    ds #F .3m
  75 .    ds #[ \f1
  76 .    ds #] \fP
  77 .\}
  78 .if t \{\
  79 .    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
  80 .    ds #V .6m
  81 .    ds #F 0
  82 .    ds #[ \&
  83 .    ds #] \&
  84 .\}
  85 .    \" simple accents for nroff and troff
  86 .if n \{\
  87 .    ds ' \&
  88 .    ds ` \&
  89 .    ds ^ \&
  90 .    ds , \&
  91 .    ds ~ ~
  92 .    ds /
  93 .\}
  94 .if t \{\
  95 .    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
  96 .    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
  97 .    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
  98 .    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
  99 .    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
 100 .    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
 101 .\}
 102 .    \" troff and (daisy-wheel) nroff accents
 103 .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
 104 .ds 8 \h'\*(#H'\(*b\h'-\*(#H'
 105 .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
 106 .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
 107 .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
 108 .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
 109 .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
 110 .ds ae a\h'-(\w'a'u*4/10)'e
 111 .ds Ae A\h'-(\w'A'u*4/10)'E
 112 .    \" corrections for vroff
 113 .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
 114 .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
 115 .    \" for low resolution devices (crt and lpr)
 116 .if \n(.H>23 .if \n(.V>19 \
 117 \{\
 118 .    ds : e
 119 .    ds 8 ss
 120 .    ds o a
 121 .    ds d- d\h'-1'\(ga
 122 .    ds D- D\h'-1'\(hy
 123 .    ds th \o'bp'
 124 .    ds Th \o'LP'
 125 .    ds ae ae
 126 .    ds Ae AE
 127 .\}
 128 .rm #[ #] #H #V #F C
 129 .\" ========================================================================
 130 .\"
 131 .IX Title "PROVE 1"
 132 .TH PROVE 1 "2009-05-05" "perl v5.8.7" "User Contributed Perl Documentation"
 133 .SH "NAME"
 134 prove \- Run tests through a TAP harness.
 135 .SH "USAGE"
 136 .IX Header "USAGE"
 137 .Vb 1
 138 \& prove [options] [files or directories]
 139 .Ve
 140 .SH "OPTIONS"
 141 .IX Header "OPTIONS"
 142 Boolean options:
 143 .PP
 144 .Vb 31
 145 \& \-v,  \-\-verbose     Print all test lines.
 146 \& \-l,  \-\-lib         Add 'lib' to the path for your tests (\-Ilib).
 147 \& \-b,  \-\-blib        Add 'blib/lib' and 'blib/arch' to the path for your tests
 148 \& \-s,  \-\-shuffle     Run the tests in random order.
 149 \& \-c,  \-\-color       Colored test output (default).
 150 \&      \-\-nocolor     Do not color test output.
 151 \&      \-\-count       Show the X/Y test count when not verbose (default)
 152 \&      \-\-nocount     Disable the X/Y test count.
 153 \& \-D   \-\-dry         Dry run. Show test that would have run.
 154 \&      \-\-ext         Set the extension for tests (default '.t')
 155 \& \-f,  \-\-failures    Show failed tests.
 156 \& \-o,  \-\-comments    Show comments.
 157 \&      \-\-fork        Fork to run harness in multiple processes.
 158 \&      \-\-ignore\-exit Ignore exit status from test scripts.
 159 \& \-m,  \-\-merge       Merge test scripts' STDERR with their STDOUT.
 160 \& \-r,  \-\-recurse     Recursively descend into directories.
 161 \&      \-\-reverse     Run the tests in reverse order.
 162 \& \-q,  \-\-quiet       Suppress some test output while running tests.
 163 \& \-Q,  \-\-QUIET       Only print summary results.
 164 \& \-p,  \-\-parse       Show full list of TAP parse errors, if any.
 165 \&      \-\-directives  Only show results with TODO or SKIP directives.
 166 \&      \-\-timer       Print elapsed time after each test.
 167 \&      \-\-normalize   Normalize TAP output in verbose output
 168 \& \-T                 Enable tainting checks.
 169 \& \-t                 Enable tainting warnings.
 170 \& \-W                 Enable fatal warnings.
 171 \& \-w                 Enable warnings.
 172 \& \-h,  \-\-help        Display this help
 173 \& \-?,                Display this help
 174 \& \-H,  \-\-man         Longer manpage for prove
 175 \&      \-\-norc        Don't process default .proverc
 176 .Ve
 177 .PP
 178 Options that take arguments:
 179 .PP
 180 .Vb 10
 181 \& \-I                 Library paths to include.
 182 \& \-P                 Load plugin (searches App::Prove::Plugin::*.)
 183 \& \-M                 Load a module.
 184 \& \-e,  \-\-exec        Interpreter to run the tests ('' for compiled tests.)
 185 \&      \-\-harness     Define test harness to use.  See TAP::Harness.
 186 \&      \-\-formatter   Result formatter to use. See TAP::Harness.
 187 \& \-a,  \-\-archive     Store the resulting TAP in an archive file.
 188 \& \-j,  \-\-jobs N      Run N test jobs in parallel (try 9.)
 189 \&      \-\-state=opts  Control prove's persistent state.
 190 \&      \-\-rc=rcfile   Process options from rcfile
 191 .Ve
 192 .SH "NOTES"
 193 .IX Header "NOTES"
 194 .Sh ".proverc"
 195 .IX Subsection ".proverc"
 196 If \fI~/.proverc\fR or \fI./.proverc\fR exist they will be read and any
 197 options they contain processed before the command line options. Options
 198 in \fI.proverc\fR are specified in the same way as command line options:
 199 .PP
 200 .Vb 3
 201 \&    # .proverc
 202 \&    \-\-state=hot,fast,save
 203 \&    \-j9 \-\-fork
 204 .Ve
 205 .PP
 206 Additional option files may be specified with the \f(CW\*(C`\-\-rc\*(C'\fR option.
 207 Default option file processing is disabled by the \f(CW\*(C`\-\-norc\*(C'\fR option.
 208 .PP
 209 Under Windows and \s-1VMS\s0 the option file is named \fI_proverc\fR rather than
 210 \&\fI.proverc\fR and is sought only in the current directory.
 211 .ie n .Sh "Reading from ""STDIN"""
 212 .el .Sh "Reading from \f(CWSTDIN\fP"
 213 .IX Subsection "Reading from STDIN"
 214 If you have a list of tests (or URLs, or anything else you want to test) in a
 215 file, you can add them to your tests by using a '\-':
 216 .PP
 217 .Vb 1
 218 \& prove \- < my_list_of_things_to_test.txt
 219 .Ve
 220 .PP
 221 See the \f(CW\*(C`README\*(C'\fR in the \f(CW\*(C`examples\*(C'\fR directory of this distribution.
 222 .Sh "Default Test Directory"
 223 .IX Subsection "Default Test Directory"
 224 If no files or directories are supplied, \f(CW\*(C`prove\*(C'\fR looks for all files
 225 matching the pattern \f(CW\*(C`t/*.t\*(C'\fR.
 226 .Sh "Colored Test Output"
 227 .IX Subsection "Colored Test Output"
 228 Colored test output is the default, but if output is not to a
 229 terminal, color is disabled. You can override this by adding the
 230 \&\f(CW\*(C`\-\-color\*(C'\fR switch.
 231 .PP
 232 Color support requires Term::ANSIColor on Unix-like platforms and
 233 Win32::Console windows. If the necessary module is not installed
 234 colored output will not be available.
 235 .Sh "Exit Code"
 236 .IX Subsection "Exit Code"
 237 If the tests fail \f(CW\*(C`prove\*(C'\fR will exit with non-zero status.
 238 .Sh "Arguments to Tests"
 239 .IX Subsection "Arguments to Tests"
 240 It is possible to supply arguments to tests. To do so separate them from
 241 prove's own arguments with the arisdottle, '::'. For example
 242 .PP
 243 .Vb 1
 244 \& prove \-v t/mytest.t :: \-\-url http://example.com
 245 .Ve
 246 .PP
 247 would run \fIt/mytest.t\fR with the options '\-\-url http://example.com'.
 248 When running multiple tests they will each receive the same arguments.
 249 .ie n .Sh """\-\-exec"""
 250 .el .Sh "\f(CW\-\-exec\fP"
 251 .IX Subsection "--exec"
 252 Normally you can just pass a list of Perl tests and the harness will know how
 253 to execute them.  However, if your tests are not written in Perl or if you
 254 want all tests invoked exactly the same way, use the \f(CW\*(C`\-e\*(C'\fR, or \f(CW\*(C`\-\-exec\*(C'\fR
 255 switch:
 256 .PP
 257 .Vb 3
 258 \& prove \-\-exec '/usr/bin/ruby \-w' t/
 259 \& prove \-\-exec '/usr/bin/perl \-Tw \-mstrict \-Ilib' t/
 260 \& prove \-\-exec '/path/to/my/customer/exec'
 261 .Ve
 262 .ie n .Sh """\-\-merge"""
 263 .el .Sh "\f(CW\-\-merge\fP"
 264 .IX Subsection "--merge"
 265 If you need to make sure your diagnostics are displayed in the correct
 266 order relative to test results you can use the \f(CW\*(C`\-\-merge\*(C'\fR option to
 267 merge the test scripts' \s-1STDERR\s0 into their \s-1STDOUT\s0.
 268 .PP
 269 This guarantees that \s-1STDOUT\s0 (where the test results appear) and \s-1STDOUT\s0
 270 (where the diagnostics appear) will stay in sync. The harness will
 271 display any diagnostics your tests emit on \s-1STDERR\s0.
 272 .PP
 273 Caveat: this is a bit of a kludge. In particular note that if anything
 274 that appears on \s-1STDERR\s0 looks like a test result the test harness will
 275 get confused. Use this option only if you understand the consequences
 276 and can live with the risk.
 277 .ie n .Sh """\-\-state"""
 278 .el .Sh "\f(CW\-\-state\fP"
 279 .IX Subsection "--state"
 280 You can ask \f(CW\*(C`prove\*(C'\fR to remember the state of previous test runs and
 281 select and/or order the tests to be run based on that saved state.
 282 .PP
 283 The \f(CW\*(C`\-\-state\*(C'\fR switch requires an argument which must be a comma
 284 separated list of one or more of the following options.
 285 .ie n .IP """last""" 4
 286 .el .IP "\f(CWlast\fR" 4
 287 .IX Item "last"
 288 Run the same tests as the last time the state was saved. This makes it
 289 possible, for example, to recreate the ordering of a shuffled test.
 290 .Sp
 291 .Vb 2
 292 \&    # Run all tests in random order
 293 \&    $ prove \-b \-\-state=save \-\-shuffle
 294 .Ve
 295 .Sp
 296 .Vb 2
 297 \&    # Run them again in the same order
 298 \&    $ prove \-b \-\-state=last
 299 .Ve
 300 .ie n .IP """failed""" 4
 301 .el .IP "\f(CWfailed\fR" 4
 302 .IX Item "failed"
 303 Run only the tests that failed on the last run.
 304 .Sp
 305 .Vb 2
 306 \&    # Run all tests
 307 \&    $ prove \-b \-\-state=save
 308 .Ve
 309 .Sp
 310 .Vb 2
 311 \&    # Run failures
 312 \&    $ prove \-b \-\-state=failed
 313 .Ve
 314 .Sp
 315 If you also specify the \f(CW\*(C`save\*(C'\fR option newly passing tests will be
 316 excluded from subsequent runs.
 317 .Sp
 318 .Vb 2
 319 \&    # Repeat until no more failures
 320 \&    $ prove \-b \-\-state=failed,save
 321 .Ve
 322 .ie n .IP """passed""" 4
 323 .el .IP "\f(CWpassed\fR" 4
 324 .IX Item "passed"
 325 Run only the passed tests from last time. Useful to make sure that no
 326 new problems have been introduced.
 327 .ie n .IP """all""" 4
 328 .el .IP "\f(CWall\fR" 4
 329 .IX Item "all"
 330 Run all tests in normal order. Multple options may be specified, so to
 331 run all tests with the failures from last time first:
 332 .Sp
 333 .Vb 1
 334 \&    $ prove \-b \-\-state=failed,all,save
 335 .Ve
 336 .ie n .IP """hot""" 4
 337 .el .IP "\f(CWhot\fR" 4
 338 .IX Item "hot"
 339 Run the tests that most recently failed first. The last failure time of
 340 each test is stored. The \f(CW\*(C`hot\*(C'\fR option causes tests to be run in most\-recent\-
 341 failure order.
 342 .Sp
 343 .Vb 1
 344 \&    $ prove \-b \-\-state=hot,save
 345 .Ve
 346 .Sp
 347 Tests that have never failed will not be selected. To run all tests with
 348 the most recently failed first use
 349 .Sp
 350 .Vb 1
 351 \&    $ prove \-b \-\-state=hot,all,save
 352 .Ve
 353 .Sp
 354 This combination of options may also be specified thus
 355 .Sp
 356 .Vb 1
 357 \&    $ prove \-b \-\-state=adrian
 358 .Ve
 359 .ie n .IP """todo""" 4
 360 .el .IP "\f(CWtodo\fR" 4
 361 .IX Item "todo"
 362 Run any tests with todos.
 363 .ie n .IP """slow""" 4
 364 .el .IP "\f(CWslow\fR" 4
 365 .IX Item "slow"
 366 Run the tests in slowest to fastest order. This is useful in conjunction
 367 with the \f(CW\*(C`\-j\*(C'\fR parallel testing switch to ensure that your slowest tests
 368 start running first.
 369 .Sp
 370 .Vb 1
 371 \&    $ prove \-b \-\-state=slow \-j9
 372 .Ve
 373 .ie n .IP """fast""" 4
 374 .el .IP "\f(CWfast\fR" 4
 375 .IX Item "fast"
 376 Run test tests in fastest to slowest order.
 377 .ie n .IP """new""" 4
 378 .el .IP "\f(CWnew\fR" 4
 379 .IX Item "new"
 380 Run the tests in newest to oldest order based on the modification times
 381 of the test scripts.
 382 .ie n .IP """old""" 4
 383 .el .IP "\f(CWold\fR" 4
 384 .IX Item "old"
 385 Run the tests in oldest to newest order.
 386 .ie n .IP """fresh""" 4
 387 .el .IP "\f(CWfresh\fR" 4
 388 .IX Item "fresh"
 389 Run those test scripts that have been modified since the last test run.
 390 .ie n .IP """save""" 4
 391 .el .IP "\f(CWsave\fR" 4
 392 .IX Item "save"
 393 Save the state on exit. The state is stored in a file called \fI.prove\fR
 394 (\fI_prove\fR on Windows and \s-1VMS\s0) in the current directory.
 395 .PP
 396 The \f(CW\*(C`\-\-state\*(C'\fR switch may be used more than once.
 397 .PP
 398 .Vb 1
 399 \&    $ prove \-b \-\-state=hot \-\-state=all,save
 400 .Ve
 401 .Sh "@INC"
 402 .IX Subsection "@INC"
 403 prove introduces a separation between \*(L"options passed to the perl which
 404 runs prove\*(R" and \*(L"options passed to the perl which runs tests\*(R"; this
 405 distinction is by design. Thus the perl which is running a test starts
 406 with the default \f(CW@INC\fR. Additional library directories can be added
 407 via the \f(CW\*(C`PERL5LIB\*(C'\fR environment variable, via \-Ifoo in \f(CW\*(C`PERL5OPT\*(C'\fR or
 408 via the \f(CW\*(C`\-Ilib\*(C'\fR option to \fIprove\fR.
 409 .Sh "Taint Mode"
 410 .IX Subsection "Taint Mode"
 411 Normally when a Perl program is run in taint mode the contents of the
 412 \&\f(CW\*(C`PERL5LIB\*(C'\fR environment variable do not appear in \f(CW@INC\fR.
 413 .PP
 414 Because \f(CW\*(C`PERL5LIB\*(C'\fR is often used during testing to add build directories
 415 to \f(CW@INC\fR prove (actually TAP::Parser::Source::Perl) passes the
 416 names of any directories found in \f(CW\*(C`PERL5LIB\*(C'\fR as \-I switches. The net
 417 effect of this is that \f(CW\*(C`PERL5LIB\*(C'\fR is honoured even when prove is run in
 418 taint mode.
 419 .SH "PLUGINS"
 420 .IX Header "PLUGINS"
 421 Plugins can be loaded using the \f(CW\*(C`\-P\f(CIplugin\f(CW\*(C'\fR syntax, eg:
 422 .PP
 423 .Vb 1
 424 \&  prove \-PMyPlugin
 425 .Ve
 426 .PP
 427 This will search for a module named \f(CW\*(C`App::Prove::Plugin::MyPlugin\*(C'\fR, or failing
 428 that, \f(CW\*(C`MyPlugin\*(C'\fR.  If the plugin can't be found, \f(CW\*(C`prove\*(C'\fR will complain & exit.
 429 .PP
 430 You can pass arguments to your plugin by appending \f(CW\*(C`=arg1,arg2,etc\*(C'\fR to the
 431 plugin name:
 432 .PP
 433 .Vb 1
 434 \&  prove \-PMyPlugin=fou,du,fafa
 435 .Ve
 436 .PP
 437 Please check individual plugin documentation for more details.
 438 .Sh "Available Plugins"
 439 .IX Subsection "Available Plugins"
 440 For an up-to-date list of plugins available, please check \s-1CPAN:\s0
 441 .PP
 442 <http://search.cpan.org/search?query=App%3A%3AProve+Plugin>
 443 .Sh "Writing Plugins"
 444 .IX Subsection "Writing Plugins"
 445 Please see \*(L"\s-1PLUGINS\s0\*(R" in App::Prove.