Commit | Line | Data |
3fea05b9 |
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. |