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. |
41d86c6b |
30 | -D --dry Dry run. Show test that would have run. |
f7c69158 |
31 | --ext Set the extension for tests (default '.t') |
b965d173 |
32 | -f, --failures Only show failed tests. |
f7c69158 |
33 | --fork Fork to run harness in multiple processes. |
34 | --ignore-exit Ignore exit status from test scripts. |
b965d173 |
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 |
e4fc8a1e |
51 | |
b965d173 |
52 | Options that take arguments: |
e4fc8a1e |
53 | |
b965d173 |
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 |
e4fc8a1e |
64 | |
b965d173 |
65 | =head1 NOTES |
e4fc8a1e |
66 | |
b965d173 |
67 | =head2 .proverc |
e4fc8a1e |
68 | |
b965d173 |
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: |
e4fc8a1e |
72 | |
b965d173 |
73 | # .proverc |
74 | --state=hot,fast,save |
75 | -j9 --fork |
e4fc8a1e |
76 | |
b965d173 |
77 | Additional option files may be specified with the C<--rc> option. |
78 | Default option file processing is disabled by the C<--norc> option. |
e4fc8a1e |
79 | |
b965d173 |
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. |
e4fc8a1e |
82 | |
b965d173 |
83 | =head2 Reading from C<STDIN> |
e4fc8a1e |
84 | |
b965d173 |
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 '-': |
e4fc8a1e |
87 | |
b965d173 |
88 | prove - < my_list_of_things_to_test.txt |
e4fc8a1e |
89 | |
b965d173 |
90 | See the C<README> in the C<examples> directory of this distribution. |
e4fc8a1e |
91 | |
b965d173 |
92 | =head2 Default Test Directory |
e4fc8a1e |
93 | |
b965d173 |
94 | If no files or directories are supplied, C<prove> looks for all files |
95 | matching the pattern C<t/*.t>. |
e4fc8a1e |
96 | |
b965d173 |
97 | =head2 Colored Test Output |
e4fc8a1e |
98 | |
b965d173 |
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. |
e4fc8a1e |
102 | |
b965d173 |
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. |
e4fc8a1e |
106 | |
b965d173 |
107 | =head2 Arguments to Tests |
e4fc8a1e |
108 | |
b965d173 |
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 |
e4fc8a1e |
111 | |
b965d173 |
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. |
e4fc8a1e |
116 | |
b965d173 |
117 | =head2 C<--exec> |
e4fc8a1e |
118 | |
b965d173 |
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: |
e4fc8a1e |
123 | |
b965d173 |
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' |
e4fc8a1e |
127 | |
b965d173 |
128 | =head2 C<--merge> |
e4fc8a1e |
129 | |
b965d173 |
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. |
e4fc8a1e |
133 | |
b965d173 |
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. |
e4fc8a1e |
137 | |
b965d173 |
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. |
e4fc8a1e |
142 | |
b965d173 |
143 | =head2 C<--state> |
e4fc8a1e |
144 | |
b965d173 |
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. |
e4fc8a1e |
148 | |
b965d173 |
149 | The C<--state> switch requires an argument which must be a comma |
150 | separated list of one or more of the following options. |
60e33a80 |
151 | |
b965d173 |
152 | =over |
60e33a80 |
153 | |
b965d173 |
154 | =item C<last> |
e4fc8a1e |
155 | |
b965d173 |
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. |
20f9f807 |
158 | |
b965d173 |
159 | # Run all tests in random order |
160 | $ prove -b --state=save --shuffle |
20f9f807 |
161 | |
b965d173 |
162 | # Run them again in the same order |
163 | $ prove -b --state=last |
e4fc8a1e |
164 | |
b965d173 |
165 | =item C<failed> |
e4fc8a1e |
166 | |
b965d173 |
167 | Run only the tests that failed on the last run. |
e4fc8a1e |
168 | |
b965d173 |
169 | # Run all tests |
69f36734 |
170 | $ prove -b --state=save |
b965d173 |
171 | |
172 | # Run failures |
173 | $ prove -b --state=failed |
e4fc8a1e |
174 | |
b965d173 |
175 | If you also specify the C<save> option newly passing tests will be |
176 | excluded from subsequent runs. |
5b1ebecd |
177 | |
b965d173 |
178 | # Repeat until no more failures |
179 | $ prove -b --state=failed,save |
5b1ebecd |
180 | |
b965d173 |
181 | =item C<passed> |
e4fc8a1e |
182 | |
b965d173 |
183 | Run only the passed tests from last time. Useful to make sure that no |
184 | new problems have been introduced. |
e4fc8a1e |
185 | |
b965d173 |
186 | =item C<all> |
e4fc8a1e |
187 | |
b965d173 |
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: |
e4fc8a1e |
190 | |
b965d173 |
191 | $ prove -b --state=failed,all,save |
43ef773b |
192 | |
b965d173 |
193 | =item C<hot> |
43ef773b |
194 | |
b965d173 |
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. |
e4fc8a1e |
198 | |
b965d173 |
199 | $ prove -b --state=hot,save |
e4fc8a1e |
200 | |
b965d173 |
201 | Tests that have never failed will not be selected. To run all tests with |
202 | the most recently failed first use |
e4fc8a1e |
203 | |
b965d173 |
204 | $ prove -b --state=hot,all,save |
e4fc8a1e |
205 | |
b965d173 |
206 | This combination of options may also be specified thus |
e4fc8a1e |
207 | |
b965d173 |
208 | $ prove -b --state=adrian |
e4fc8a1e |
209 | |
b965d173 |
210 | =item C<todo> |
e4fc8a1e |
211 | |
b965d173 |
212 | Run any tests with todos. |
e4fc8a1e |
213 | |
b965d173 |
214 | =item C<slow> |
e4fc8a1e |
215 | |
b965d173 |
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. |
e4fc8a1e |
219 | |
b965d173 |
220 | $ prove -b --state=slow -j9 |
221 | |
222 | =item C<fast> |
e4fc8a1e |
223 | |
b965d173 |
224 | Run test tests in fastest to slowest order. |
e4fc8a1e |
225 | |
b965d173 |
226 | =item C<new> |
e4fc8a1e |
227 | |
b965d173 |
228 | Run the tests in newest to oldest order. |
e4fc8a1e |
229 | |
b965d173 |
230 | =item C<old> |
e4fc8a1e |
231 | |
b965d173 |
232 | Run the tests in oldest to newest order. |
e4fc8a1e |
233 | |
b965d173 |
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 |
e4fc8a1e |
244 | |
bd3ac2f1 |
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 | |
e4fc8a1e |
256 | =cut |
b965d173 |
257 | |
258 | # vim:ts=4:sw=4:et:sta |