Commit | Line | Data |
e4fc8a1e |
1 | #!/usr/bin/perl -w |
2 | |
3 | use strict; |
b965d173 |
4 | use App::Prove; |
e4fc8a1e |
5 | |
b965d173 |
6 | my $app = App::Prove->new; |
7 | $app->process_args(@ARGV); |
f7c69158 |
8 | exit( $app->run ? 0 : 1 ); |
e4fc8a1e |
9 | |
e4fc8a1e |
10 | __END__ |
11 | |
12 | =head1 NAME |
13 | |
b965d173 |
14 | prove - Run tests through a TAP harness. |
e4fc8a1e |
15 | |
b965d173 |
16 | =head1 USAGE |
e4fc8a1e |
17 | |
b965d173 |
18 | prove [options] [files or directories] |
e4fc8a1e |
19 | |
20f9f807 |
20 | =head1 OPTIONS |
e4fc8a1e |
21 | |
b965d173 |
22 | Boolean options: |
e4fc8a1e |
23 | |
b965d173 |
24 | -v, --verbose Print all test lines. |
25 | -l, --lib Add 'lib' to the path for your tests (-Ilib). |
f7c69158 |
26 | -b, --blib Add 'blib/lib' and 'blib/arch' to the path for your tests |
b965d173 |
27 | -s, --shuffle Run the tests in random order. |
28 | -c, --color Colored test output (default). |
29 | --nocolor Do not color test output. |
27fc0087 |
30 | --count Show the X/Y test count when not verbose (default) |
31 | --nocount Disable the X/Y test count. |
41d86c6b |
32 | -D --dry Dry run. Show test that would have run. |
f7c69158 |
33 | --ext Set the extension for tests (default '.t') |
a39e16d8 |
34 | -f, --failures Show failed tests. |
35 | -o, --comments Show comments. |
f7c69158 |
36 | --fork Fork to run harness in multiple processes. |
37 | --ignore-exit Ignore exit status from test scripts. |
b965d173 |
38 | -m, --merge Merge test scripts' STDERR with their STDOUT. |
39 | -r, --recurse Recursively descend into directories. |
40 | --reverse Run the tests in reverse order. |
41 | -q, --quiet Suppress some test output while running tests. |
42 | -Q, --QUIET Only print summary results. |
43 | -p, --parse Show full list of TAP parse errors, if any. |
44 | --directives Only show results with TODO or SKIP directives. |
45 | --timer Print elapsed time after each test. |
a39e16d8 |
46 | --normalize Normalize TAP output in verbose output |
b965d173 |
47 | -T Enable tainting checks. |
48 | -t Enable tainting warnings. |
49 | -W Enable fatal warnings. |
50 | -w Enable warnings. |
51 | -h, --help Display this help |
52 | -?, Display this help |
53 | -H, --man Longer manpage for prove |
54 | --norc Don't process default .proverc |
e4fc8a1e |
55 | |
b965d173 |
56 | Options that take arguments: |
e4fc8a1e |
57 | |
b965d173 |
58 | -I Library paths to include. |
59 | -P Load plugin (searches App::Prove::Plugin::*.) |
60 | -M Load a module. |
61 | -e, --exec Interpreter to run the tests ('' for compiled tests.) |
62 | --harness Define test harness to use. See TAP::Harness. |
63 | --formatter Result formatter to use. See TAP::Harness. |
64 | -a, --archive Store the resulting TAP in an archive file. |
65 | -j, --jobs N Run N test jobs in parallel (try 9.) |
66 | --state=opts Control prove's persistent state. |
67 | --rc=rcfile Process options from rcfile |
e4fc8a1e |
68 | |
b965d173 |
69 | =head1 NOTES |
e4fc8a1e |
70 | |
b965d173 |
71 | =head2 .proverc |
e4fc8a1e |
72 | |
b965d173 |
73 | If F<~/.proverc> or F<./.proverc> exist they will be read and any |
74 | options they contain processed before the command line options. Options |
75 | in F<.proverc> are specified in the same way as command line options: |
e4fc8a1e |
76 | |
b965d173 |
77 | # .proverc |
78 | --state=hot,fast,save |
79 | -j9 --fork |
e4fc8a1e |
80 | |
b965d173 |
81 | Additional option files may be specified with the C<--rc> option. |
82 | Default option file processing is disabled by the C<--norc> option. |
e4fc8a1e |
83 | |
b965d173 |
84 | Under Windows and VMS the option file is named F<_proverc> rather than |
85 | F<.proverc> and is sought only in the current directory. |
e4fc8a1e |
86 | |
b965d173 |
87 | =head2 Reading from C<STDIN> |
e4fc8a1e |
88 | |
b965d173 |
89 | If you have a list of tests (or URLs, or anything else you want to test) in a |
90 | file, you can add them to your tests by using a '-': |
e4fc8a1e |
91 | |
b965d173 |
92 | prove - < my_list_of_things_to_test.txt |
e4fc8a1e |
93 | |
b965d173 |
94 | See the C<README> in the C<examples> directory of this distribution. |
e4fc8a1e |
95 | |
b965d173 |
96 | =head2 Default Test Directory |
e4fc8a1e |
97 | |
b965d173 |
98 | If no files or directories are supplied, C<prove> looks for all files |
99 | matching the pattern C<t/*.t>. |
e4fc8a1e |
100 | |
b965d173 |
101 | =head2 Colored Test Output |
e4fc8a1e |
102 | |
b965d173 |
103 | Colored test output is the default, but if output is not to a |
104 | terminal, color is disabled. You can override this by adding the |
105 | C<--color> switch. |
e4fc8a1e |
106 | |
b965d173 |
107 | Color support requires L<Term::ANSIColor> on Unix-like platforms and |
108 | L<Win32::Console> windows. If the necessary module is not installed |
109 | colored output will not be available. |
e4fc8a1e |
110 | |
a39e16d8 |
111 | =head2 Exit Code |
112 | |
113 | If the tests fail C<prove> will exit with non-zero status. |
114 | |
b965d173 |
115 | =head2 Arguments to Tests |
e4fc8a1e |
116 | |
b965d173 |
117 | It is possible to supply arguments to tests. To do so separate them from |
118 | prove's own arguments with the arisdottle, '::'. For example |
e4fc8a1e |
119 | |
b965d173 |
120 | prove -v t/mytest.t :: --url http://example.com |
121 | |
122 | would run F<t/mytest.t> with the options '--url http://example.com'. |
123 | When running multiple tests they will each receive the same arguments. |
e4fc8a1e |
124 | |
b965d173 |
125 | =head2 C<--exec> |
e4fc8a1e |
126 | |
b965d173 |
127 | Normally you can just pass a list of Perl tests and the harness will know how |
128 | to execute them. However, if your tests are not written in Perl or if you |
129 | want all tests invoked exactly the same way, use the C<-e>, or C<--exec> |
130 | switch: |
e4fc8a1e |
131 | |
b965d173 |
132 | prove --exec '/usr/bin/ruby -w' t/ |
133 | prove --exec '/usr/bin/perl -Tw -mstrict -Ilib' t/ |
134 | prove --exec '/path/to/my/customer/exec' |
e4fc8a1e |
135 | |
b965d173 |
136 | =head2 C<--merge> |
e4fc8a1e |
137 | |
b965d173 |
138 | If you need to make sure your diagnostics are displayed in the correct |
139 | order relative to test results you can use the C<--merge> option to |
140 | merge the test scripts' STDERR into their STDOUT. |
e4fc8a1e |
141 | |
b965d173 |
142 | This guarantees that STDOUT (where the test results appear) and STDOUT |
143 | (where the diagnostics appear) will stay in sync. The harness will |
144 | display any diagnostics your tests emit on STDERR. |
e4fc8a1e |
145 | |
b965d173 |
146 | Caveat: this is a bit of a kludge. In particular note that if anything |
147 | that appears on STDERR looks like a test result the test harness will |
148 | get confused. Use this option only if you understand the consequences |
149 | and can live with the risk. |
e4fc8a1e |
150 | |
b965d173 |
151 | =head2 C<--state> |
e4fc8a1e |
152 | |
b965d173 |
153 | You can ask C<prove> to remember the state of previous test runs and |
27fc0087 |
154 | select and/or order the tests to be run based on that saved state. |
e4fc8a1e |
155 | |
b965d173 |
156 | The C<--state> switch requires an argument which must be a comma |
157 | separated list of one or more of the following options. |
60e33a80 |
158 | |
b965d173 |
159 | =over |
60e33a80 |
160 | |
b965d173 |
161 | =item C<last> |
e4fc8a1e |
162 | |
b965d173 |
163 | Run the same tests as the last time the state was saved. This makes it |
164 | possible, for example, to recreate the ordering of a shuffled test. |
20f9f807 |
165 | |
b965d173 |
166 | # Run all tests in random order |
167 | $ prove -b --state=save --shuffle |
20f9f807 |
168 | |
b965d173 |
169 | # Run them again in the same order |
170 | $ prove -b --state=last |
e4fc8a1e |
171 | |
b965d173 |
172 | =item C<failed> |
e4fc8a1e |
173 | |
b965d173 |
174 | Run only the tests that failed on the last run. |
e4fc8a1e |
175 | |
b965d173 |
176 | # Run all tests |
69f36734 |
177 | $ prove -b --state=save |
b965d173 |
178 | |
179 | # Run failures |
180 | $ prove -b --state=failed |
e4fc8a1e |
181 | |
b965d173 |
182 | If you also specify the C<save> option newly passing tests will be |
183 | excluded from subsequent runs. |
5b1ebecd |
184 | |
b965d173 |
185 | # Repeat until no more failures |
186 | $ prove -b --state=failed,save |
5b1ebecd |
187 | |
b965d173 |
188 | =item C<passed> |
e4fc8a1e |
189 | |
b965d173 |
190 | Run only the passed tests from last time. Useful to make sure that no |
191 | new problems have been introduced. |
e4fc8a1e |
192 | |
b965d173 |
193 | =item C<all> |
e4fc8a1e |
194 | |
b965d173 |
195 | Run all tests in normal order. Multple options may be specified, so to |
196 | run all tests with the failures from last time first: |
e4fc8a1e |
197 | |
b965d173 |
198 | $ prove -b --state=failed,all,save |
43ef773b |
199 | |
b965d173 |
200 | =item C<hot> |
43ef773b |
201 | |
b965d173 |
202 | Run the tests that most recently failed first. The last failure time of |
203 | each test is stored. The C<hot> option causes tests to be run in most-recent- |
204 | failure order. |
e4fc8a1e |
205 | |
b965d173 |
206 | $ prove -b --state=hot,save |
e4fc8a1e |
207 | |
b965d173 |
208 | Tests that have never failed will not be selected. To run all tests with |
209 | the most recently failed first use |
e4fc8a1e |
210 | |
b965d173 |
211 | $ prove -b --state=hot,all,save |
e4fc8a1e |
212 | |
b965d173 |
213 | This combination of options may also be specified thus |
e4fc8a1e |
214 | |
b965d173 |
215 | $ prove -b --state=adrian |
e4fc8a1e |
216 | |
b965d173 |
217 | =item C<todo> |
e4fc8a1e |
218 | |
b965d173 |
219 | Run any tests with todos. |
e4fc8a1e |
220 | |
b965d173 |
221 | =item C<slow> |
e4fc8a1e |
222 | |
b965d173 |
223 | Run the tests in slowest to fastest order. This is useful in conjunction |
224 | with the C<-j> parallel testing switch to ensure that your slowest tests |
225 | start running first. |
e4fc8a1e |
226 | |
b965d173 |
227 | $ prove -b --state=slow -j9 |
228 | |
229 | =item C<fast> |
e4fc8a1e |
230 | |
b965d173 |
231 | Run test tests in fastest to slowest order. |
e4fc8a1e |
232 | |
b965d173 |
233 | =item C<new> |
e4fc8a1e |
234 | |
27fc0087 |
235 | Run the tests in newest to oldest order based on the modification times |
236 | of the test scripts. |
e4fc8a1e |
237 | |
b965d173 |
238 | =item C<old> |
e4fc8a1e |
239 | |
b965d173 |
240 | Run the tests in oldest to newest order. |
e4fc8a1e |
241 | |
27fc0087 |
242 | =item C<fresh> |
243 | |
244 | Run those test scripts that have been modified since the last test run. |
245 | |
b965d173 |
246 | =item C<save> |
247 | |
248 | Save the state on exit. The state is stored in a file called F<.prove> |
249 | (F<_prove> on Windows and VMS) in the current directory. |
250 | |
251 | =back |
252 | |
253 | The C<--state> switch may be used more than once. |
254 | |
255 | $ prove -b --state=hot --state=all,save |
e4fc8a1e |
256 | |
a39e16d8 |
257 | =head2 @INC |
258 | |
259 | prove introduces a separation between "options passed to the perl which |
260 | runs prove" and "options passed to the perl which runs tests"; this |
261 | distinction is by design. Thus the perl which is running a test starts |
262 | with the default C<@INC>. Additional library directories can be added |
263 | via the C<PERL5LIB> environment variable, via -Ifoo in C<PERL5OPT> or |
264 | via the C<-Ilib> option to F<prove>. |
265 | |
bd3ac2f1 |
266 | =head2 Taint Mode |
267 | |
268 | Normally when a Perl program is run in taint mode the contents of the |
269 | C<PERL5LIB> environment variable do not appear in C<@INC>. |
270 | |
271 | Because C<PERL5LIB> is often used during testing to add build directories |
272 | to C<@INC> prove (actually L<TAP::Parser::Source::Perl>) passes the |
273 | names of any directories found in C<PERL5LIB> as -I switches. The net |
274 | effect of this is that C<PERL5LIB> is honoured even when prove is run in |
275 | taint mode. |
276 | |
bdaf8c65 |
277 | =head1 PLUGINS |
278 | |
279 | Plugins can be loaded using the C<< -PI<plugin> >> syntax, eg: |
280 | |
281 | prove -PMyPlugin |
282 | |
283 | This will search for a module named C<App::Prove::Plugin::MyPlugin>, or failing |
284 | that, C<MyPlugin>. If the plugin can't be found, C<prove> will complain & exit. |
285 | |
286 | You can pass arguments to your plugin by appending C<=arg1,arg2,etc> to the |
287 | plugin name: |
288 | |
289 | prove -PMyPlugin=fou,du,fafa |
290 | |
291 | Please check individual plugin documentation for more details. |
292 | |
293 | =head2 Available Plugins |
294 | |
295 | For an up-to-date list of plugins available, please check CPAN: |
296 | |
297 | L<http://search.cpan.org/search?query=App%3A%3AProve+Plugin> |
298 | |
299 | =head2 Writing Plugins |
300 | |
301 | Please see L<App::Prove/PLUGINS>. |
302 | |
e4fc8a1e |
303 | =cut |
b965d173 |
304 | |
305 | # vim:ts=4:sw=4:et:sta |