bin/prove

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