Commit | Line | Data |
e4fc8a1e |
1 | #!/usr/bin/perl -w |
2 | |
3 | use strict; |
4 | |
5 | use Test::Harness; |
20f9f807 |
6 | use Test::Harness::Util qw( all_in blibdirs shuffle ); |
7 | |
e4fc8a1e |
8 | use Getopt::Long; |
9 | use Pod::Usage 1.12; |
10 | use File::Spec; |
11 | |
12 | use vars qw( $VERSION ); |
5b1ebecd |
13 | $VERSION = '2.64'; |
e4fc8a1e |
14 | |
e4fc8a1e |
15 | my $shuffle = 0; |
16 | my $dry = 0; |
17 | my $blib = 0; |
60e33a80 |
18 | my $lib = 0; |
e4fc8a1e |
19 | my $recurse = 0; |
20 | my @includes = (); |
21 | my @switches = (); |
22 | |
23 | # Allow cuddling the paths with the -I |
24 | @ARGV = map { /^(-I)(.+)/ ? ($1,$2) : $_ } @ARGV; |
25 | |
26 | # Stick any default switches at the beginning, so they can be overridden |
27 | # by the command line switches. |
5b1ebecd |
28 | unshift @ARGV, split( ' ', $ENV{PROVE_SWITCHES} ) if defined $ENV{PROVE_SWITCHES}; |
e4fc8a1e |
29 | |
5b1ebecd |
30 | Getopt::Long::Configure( 'no_ignore_case' ); |
31 | Getopt::Long::Configure( 'bundling' ); |
e4fc8a1e |
32 | GetOptions( |
33 | 'b|blib' => \$blib, |
42d29bac |
34 | 'd|debug' => \$Test::Harness::debug, |
e4fc8a1e |
35 | 'D|dry' => \$dry, |
73ea3450 |
36 | 'h|help|?' => sub {pod2usage({-verbose => 1}); exit}, |
37 | 'H|man' => sub {pod2usage({-verbose => 2}); exit}, |
e4fc8a1e |
38 | 'I=s@' => \@includes, |
42d29bac |
39 | 'l|lib' => \$lib, |
5b1ebecd |
40 | 'perl=s' => \$ENV{HARNESS_PERL}, |
e4fc8a1e |
41 | 'r|recurse' => \$recurse, |
42 | 's|shuffle' => \$shuffle, |
5b1ebecd |
43 | 't' => sub { unshift @switches, '-t' }, # Always want -t up front |
44 | 'T' => sub { unshift @switches, '-T' }, # Always want -T up front |
20f9f807 |
45 | 'w' => sub { push @switches, '-w' }, |
46 | 'W' => sub { push @switches, '-W' }, |
5b1ebecd |
47 | 'strap=s' => \$ENV{HARNESS_STRAP_CLASS}, |
43ef773b |
48 | 'timer' => \$Test::Harness::Timer, |
e4fc8a1e |
49 | 'v|verbose' => \$Test::Harness::verbose, |
50 | 'V|version' => sub { print_version(); exit; }, |
e4fc8a1e |
51 | ) or exit 1; |
52 | |
42d29bac |
53 | $ENV{TEST_VERBOSE} = 1 if $Test::Harness::verbose; |
54 | |
e4fc8a1e |
55 | # Handle blib includes |
56 | if ( $blib ) { |
57 | my @blibdirs = blibdirs(); |
58 | if ( @blibdirs ) { |
42d29bac |
59 | unshift @includes, @blibdirs; |
20f9f807 |
60 | } |
61 | else { |
42d29bac |
62 | warn "No blib directories found.\n"; |
e4fc8a1e |
63 | } |
64 | } |
65 | |
60e33a80 |
66 | # Handle lib includes |
67 | if ( $lib ) { |
5b1ebecd |
68 | unshift @includes, 'lib'; |
60e33a80 |
69 | } |
70 | |
e4fc8a1e |
71 | # Build up TH switches |
72 | push( @switches, map { /\s/ && !/^".*"$/ ? qq["-I$_"] : "-I$_" } @includes ); |
5b1ebecd |
73 | $Test::Harness::Switches = join( ' ', @switches ); |
e4fc8a1e |
74 | print "# \$Test::Harness::Switches: $Test::Harness::Switches\n" if $Test::Harness::debug; |
75 | |
e4fc8a1e |
76 | @ARGV = File::Spec->curdir unless @ARGV; |
20f9f807 |
77 | my @argv_globbed; |
78 | my @tests; |
ea5423ed |
79 | if ( $] >= 5.006001 ) { |
20f9f807 |
80 | require File::Glob; |
81 | @argv_globbed = map { File::Glob::bsd_glob($_) } @ARGV; |
82 | } |
83 | else { |
84 | @argv_globbed = map { glob } @ARGV; |
85 | } |
86 | |
87 | for ( @argv_globbed ) { |
88 | push( @tests, -d $_ ? all_in( { recurse => $recurse, start => $_ } ) : $_ ) |
89 | } |
e4fc8a1e |
90 | |
91 | if ( @tests ) { |
92 | shuffle(@tests) if $shuffle; |
93 | if ( $dry ) { |
5b1ebecd |
94 | print join( "\n", @tests, '' ); |
20f9f807 |
95 | } |
96 | else { |
42d29bac |
97 | print "# ", scalar @tests, " tests to run\n" if $Test::Harness::debug; |
e4fc8a1e |
98 | runtests(@tests); |
99 | } |
100 | } |
101 | |
e4fc8a1e |
102 | sub print_version { |
103 | printf( "prove v%s, using Test::Harness v%s and Perl v%vd\n", |
42d29bac |
104 | $VERSION, $Test::Harness::VERSION, $^V ); |
e4fc8a1e |
105 | } |
106 | |
e4fc8a1e |
107 | __END__ |
108 | |
109 | =head1 NAME |
110 | |
111 | prove -- A command-line tool for running tests against Test::Harness |
112 | |
113 | =head1 SYNOPSIS |
114 | |
115 | prove [options] [files/directories] |
116 | |
20f9f807 |
117 | =head1 OPTIONS |
e4fc8a1e |
118 | |
20f9f807 |
119 | -b, --blib Adds blib/lib to the path for your tests, a la "use blib" |
120 | -d, --debug Includes extra debugging information |
121 | -D, --dry Dry run: Show the tests to run, but don't run them |
e4fc8a1e |
122 | -h, --help Display this help |
123 | -H, --man Longer manpage for prove |
124 | -I Add libraries to @INC, as Perl's -I |
20f9f807 |
125 | -l, --lib Add lib to the path for your tests |
126 | --perl Sets the name of the Perl executable to use |
127 | -r, --recurse Recursively descend into directories |
128 | -s, --shuffle Run the tests in a random order |
5b1ebecd |
129 | --strap Define strap class to use |
42d29bac |
130 | -T Enable tainting checks |
131 | -t Enable tainting warnings |
43ef773b |
132 | --timer Print elapsed time after each test file |
20f9f807 |
133 | -v, --verbose Display standard output of test scripts while running them |
e4fc8a1e |
134 | -V, --version Display version info |
135 | |
136 | Single-character options may be stacked. Default options may be set by |
137 | specifying the PROVE_SWITCHES environment variable. |
138 | |
139 | =head1 OVERVIEW |
140 | |
141 | F<prove> is a command-line interface to the test-running functionality |
142 | of C<Test::Harness>. With no arguments, it will run all tests in the |
143 | current directory. |
144 | |
145 | Shell metacharacters may be used with command lines options and will be exanded |
20f9f807 |
146 | via C<File::Glob::bsd_glob>. |
e4fc8a1e |
147 | |
148 | =head1 PROVE VS. "MAKE TEST" |
149 | |
150 | F<prove> has a number of advantages over C<make test> when doing development. |
151 | |
152 | =over 4 |
153 | |
154 | =item * F<prove> is designed as a development tool |
155 | |
156 | Perl users typically run the test harness through a makefile via |
157 | C<make test>. That's fine for module distributions, but it's |
158 | suboptimal for a test/code/debug development cycle. |
159 | |
160 | =item * F<prove> is granular |
161 | |
162 | F<prove> lets your run against only the files you want to check. |
163 | Running C<prove t/live/ t/master.t> checks every F<*.t> in F<t/live>, |
164 | plus F<t/master.t>. |
165 | |
166 | =item * F<prove> has an easy verbose mode |
167 | |
168 | F<prove> has a C<-v> option to see the raw output from the tests. |
169 | To do this with C<make test>, you must set C<HARNESS_VERBOSE=1> in |
170 | the environment. |
171 | |
172 | =item * F<prove> can run under taint mode |
173 | |
174 | F<prove>'s C<-T> runs your tests under C<perl -T>, and C<-t> runs them |
175 | under C<perl -t>. |
176 | |
177 | =item * F<prove> can shuffle tests |
178 | |
179 | You can use F<prove>'s C<--shuffle> option to try to excite problems |
180 | that don't show up when tests are run in the same order every time. |
181 | |
182 | =item * F<prove> doesn't rely on a make tool |
183 | |
184 | Not everyone wants to write a makefile, or use L<ExtUtils::MakeMaker> |
185 | to do so. F<prove> has no external dependencies. |
186 | |
187 | =item * Not everything is a module |
188 | |
189 | More and more users are using Perl's testing tools outside the |
190 | context of a module distribution, and may not even use a makefile |
191 | at all. |
192 | |
193 | =back |
194 | |
195 | =head1 COMMAND LINE OPTIONS |
196 | |
197 | =head2 -b, --blib |
198 | |
199 | Adds blib/lib to the path for your tests, a la "use blib". |
200 | |
201 | =head2 -d, --debug |
202 | |
203 | Include debug information about how F<prove> is being run. This |
204 | option doesn't show the output from the test scripts. That's handled |
205 | by -v,--verbose. |
206 | |
207 | =head2 -D, --dry |
208 | |
209 | Dry run: Show the tests to run, but don't run them. |
210 | |
e4fc8a1e |
211 | =head2 -I |
212 | |
60e33a80 |
213 | Add libraries to @INC, as Perl's -I. |
214 | |
215 | =head2 -l, --lib |
216 | |
217 | Add C<lib> to @INC. Equivalent to C<-Ilib>. |
e4fc8a1e |
218 | |
20f9f807 |
219 | =head2 --perl |
220 | |
221 | Sets the C<HARNESS_PERL> environment variable, which controls what |
222 | Perl executable will run the tests. |
223 | |
e4fc8a1e |
224 | =head2 -r, --recurse |
225 | |
226 | Descends into subdirectories of any directories specified, looking for tests. |
227 | |
228 | =head2 -s, --shuffle |
229 | |
230 | Sometimes tests are accidentally dependent on tests that have been |
231 | run before. This switch will shuffle the tests to be run prior to |
232 | running them, thus ensuring that hidden dependencies in the test |
233 | order are likely to be revealed. The author hopes the run the |
234 | algorithm on the preceding sentence to see if he can produce something |
235 | slightly less awkward. |
236 | |
5b1ebecd |
237 | =head2 --strap |
238 | |
239 | Sets the HARNESS_STRAP_CLASS variable to set which Test::Harness::Straps |
240 | variable to use in running the tests. |
241 | |
e4fc8a1e |
242 | =head2 -t |
243 | |
244 | Runs test programs under perl's -t taint warning mode. |
245 | |
246 | =head2 -T |
247 | |
248 | Runs test programs under perl's -T taint mode. |
249 | |
43ef773b |
250 | =head2 --timer |
251 | |
252 | Print elapsed time after each test file |
253 | |
e4fc8a1e |
254 | =head2 -v, --verbose |
255 | |
42d29bac |
256 | Display standard output of test scripts while running them. Also sets |
257 | TEST_VERBOSE in case your tests rely on them. |
e4fc8a1e |
258 | |
259 | =head2 -V, --version |
260 | |
261 | Display version info. |
262 | |
263 | =head1 BUGS |
264 | |
265 | Please use the CPAN bug ticketing system at L<http://rt.cpan.org/>. |
266 | You can also mail bugs, fixes and enhancements to |
267 | C<< <bug-test-harness@rt.cpan.org> >>. |
268 | |
269 | =head1 TODO |
270 | |
271 | =over 4 |
272 | |
273 | =item * |
274 | |
275 | Shuffled tests must be recreatable |
276 | |
e4fc8a1e |
277 | =back |
278 | |
279 | =head1 AUTHORS |
280 | |
20f9f807 |
281 | Andy Lester C<< <andy at petdance.com> >> |
e4fc8a1e |
282 | |
283 | =head1 COPYRIGHT |
284 | |
5b1ebecd |
285 | Copyright 2004-2006 by Andy Lester C<< <andy at petdance.com> >>. |
e4fc8a1e |
286 | |
287 | This program is free software; you can redistribute it and/or |
288 | modify it under the same terms as Perl itself. |
289 | |
290 | See L<http://www.perl.com/perl/misc/Artistic.html>. |
291 | |
292 | =cut |