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