lib/Test/Harness/bin/prove

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