[p5sagit/p5-mst-13.2.git] / lib / Test / Harness / bin / prove

#!/usr/bin/perl -w

use strict;

use Test::Harness;
use Getopt::Long;
use Pod::Usage 1.12;
use File::Spec;

use vars qw( $VERSION );
$VERSION = "1.04";

my @ext = ();
my $shuffle = 0;
my $dry = 0;
my $blib = 0;
my $lib = 0;
my $recurse = 0;
my @includes = ();
my @switches = ();

# Allow cuddling the paths with the -I
@ARGV = map { /^(-I)(.+)/ ? ($1,$2) : $_ } @ARGV;

# Stick any default switches at the beginning, so they can be overridden
# by the command line switches.
unshift @ARGV, split( " ", $ENV{PROVE_SWITCHES} ) if defined $ENV{PROVE_SWITCHES};

Getopt::Long::Configure( "no_ignore_case" );
Getopt::Long::Configure( "bundling" );
GetOptions(
    'b|blib'        => \$blib,
    'd|debug'       => \$Test::Harness::debug,
    'D|dry'         => \$dry,
    'h|help|?'      => sub {pod2usage({-verbose => 1}); exit},
    'H|man'         => sub {pod2usage({-verbose => 2}); exit},
    'I=s@'          => \@includes,
    'l|lib'         => \$lib,
    'r|recurse'     => \$recurse,
    's|shuffle'     => \$shuffle,
    't'             => sub { unshift @switches, "-t" }, # Always want -t up front
    'T'             => sub { unshift @switches, "-T" }, # Always want -T up front
    'timer'         => \$Test::Harness::Timer,
    'v|verbose'     => \$Test::Harness::verbose,
    'V|version'     => sub { print_version(); exit; },
    'ext=s@'        => \@ext,
) or exit 1;

$ENV{TEST_VERBOSE} = 1 if $Test::Harness::verbose;

# Build up extensions regex
@ext = map { split /,/ } @ext;
s/^\.// foreach @ext;
@ext = ("t") unless @ext;
my $ext_regex = join( "|", map { quotemeta } @ext );
$ext_regex = qr/\.($ext_regex)$/;

# Handle blib includes
if ( $blib ) {
    my @blibdirs = blibdirs();
    if ( @blibdirs ) {
        unshift @includes, @blibdirs;
    } else {
        warn "No blib directories found.\n";
    }
}

# Handle lib includes
if ( $lib ) {
    unshift @includes, "lib";
}

# Build up TH switches
push( @switches, map { /\s/ && !/^".*"$/ ? qq["-I$_"] : "-I$_" } @includes );
$Test::Harness::Switches = join( " ", @switches );
print "# \$Test::Harness::Switches: $Test::Harness::Switches\n" if $Test::Harness::debug;

my @tests;
@ARGV = File::Spec->curdir unless @ARGV;
push( @tests, -d $_ ? all_in( $_ ) : $_ ) for map { glob } @ARGV;

if ( @tests ) {
    shuffle(@tests) if $shuffle;
    if ( $dry ) {
        print join( "\n", @tests, "" );
    } else {
        print "# ", scalar @tests, " tests to run\n" if $Test::Harness::debug;
        runtests(@tests);
    }
}

sub all_in {
    my $start = shift;

    my @hits = ();

    local *DH;
    if ( opendir( DH, $start ) ) {
        my @files = sort readdir DH;
        closedir DH;
        for my $file ( @files ) {
            next if $file eq File::Spec->updir || $file eq File::Spec->curdir;
            next if $file eq ".svn";
            next if $file eq "CVS";

            my $currfile = File::Spec->catfile( $start, $file );
            if ( -d $currfile ) {
                push( @hits, all_in( $currfile ) ) if $recurse;
            } else {
                push( @hits, $currfile ) if $currfile =~ $ext_regex;
            }
        }
    } else {
        warn "$start: $!\n";
    }

    return @hits;
}

sub shuffle {
    # Fisher-Yates shuffle
    my $i = @_;
    while ($i) {
        my $j = rand $i--;
        @_[$i, $j] = @_[$j, $i];
    }
}

sub print_version {
    printf( "prove v%s, using Test::Harness v%s and Perl v%vd\n",
        $VERSION, $Test::Harness::VERSION, $^V );
}

# Stolen directly from blib.pm
sub blibdirs {
    my $dir = File::Spec->curdir;
    if ($^O eq 'VMS') {
        ($dir = VMS::Filespec::unixify($dir)) =~ s-/\z--;
    }
    my $archdir = "arch";
    if ( $^O eq "MacOS" ) {
        # Double up the MP::A so that it's not used only once.
        $archdir = $MacPerl::Architecture = $MacPerl::Architecture;
    }

    my $i = 5;
    while ($i--) {
        my $blib      = File::Spec->catdir( $dir, "blib" );
        my $blib_lib  = File::Spec->catdir( $blib, "lib" );
        my $blib_arch = File::Spec->catdir( $blib, $archdir );

        if ( -d $blib && -d $blib_arch && -d $blib_lib ) {
            return ($blib_arch,$blib_lib);
        }
        $dir = File::Spec->catdir($dir, File::Spec->updir);
    }
    warn "$0: Cannot find blib\n";
    return;
}

__END__

=head1 NAME

prove -- A command-line tool for running tests against Test::Harness

=head1 SYNOPSIS

prove [options] [files/directories]

Options:

    -b, --blib      Adds blib/lib to the path for your tests, a la "use blib".
    -d, --debug     Includes extra debugging information.
    -D, --dry       Dry run: Show the tests to run, but don't run them.
        --ext=x     Extensions (defaults to .t)
    -h, --help      Display this help
    -H, --man       Longer manpage for prove
    -I              Add libraries to @INC, as Perl's -I
    -l, --lib       Add lib to the path for your tests.
    -r, --recurse   Recursively descend into directories.
    -s, --shuffle   Run the tests in a random order.
    -T              Enable tainting checks
    -t              Enable tainting warnings
        --timer     Print elapsed time after each test file
    -v, --verbose   Display standard output of test scripts while running them.
    -V, --version   Display version info

Single-character options may be stacked.  Default options may be set by
specifying the PROVE_SWITCHES environment variable.

=head1 OVERVIEW

F<prove> is a command-line interface to the test-running functionality
of C<Test::Harness>.  With no arguments, it will run all tests in the
current directory.

Shell metacharacters may be used with command lines options and will be exanded 
via C<glob>.

=head1 PROVE VS. "MAKE TEST"

F<prove> has a number of advantages over C<make test> when doing development.

=over 4

=item * F<prove> is designed as a development tool

Perl users typically run the test harness through a makefile via
C<make test>.  That's fine for module distributions, but it's
suboptimal for a test/code/debug development cycle.

=item * F<prove> is granular 

F<prove> lets your run against only the files you want to check.
Running C<prove t/live/ t/master.t> checks every F<*.t> in F<t/live>,
plus F<t/master.t>.

=item * F<prove> has an easy verbose mode

F<prove> has a C<-v> option to see the raw output from the tests.
To do this with C<make test>, you must set C<HARNESS_VERBOSE=1> in
the environment.

=item * F<prove> can run under taint mode

F<prove>'s C<-T> runs your tests under C<perl -T>, and C<-t> runs them
under C<perl -t>.

=item * F<prove> can shuffle tests

You can use F<prove>'s C<--shuffle> option to try to excite problems
that don't show up when tests are run in the same order every time.

=item * F<prove> doesn't rely on a make tool

Not everyone wants to write a makefile, or use L<ExtUtils::MakeMaker>
to do so.  F<prove> has no external dependencies.

=item * Not everything is a module

More and more users are using Perl's testing tools outside the
context of a module distribution, and may not even use a makefile
at all.

=back

=head1 COMMAND LINE OPTIONS

=head2 -b, --blib

Adds blib/lib to the path for your tests, a la "use blib".

=head2 -d, --debug

Include debug information about how F<prove> is being run.  This
option doesn't show the output from the test scripts.  That's handled
by -v,--verbose.

=head2 -D, --dry

Dry run: Show the tests to run, but don't run them.

=head2 --ext=extension

Specify extensions of the test files to run.  By default, these are .t,
but you may have other non-.t test files, most likely .sh shell scripts.
The --ext is repeatable.

=head2 -I

Add libraries to @INC, as Perl's -I.

=head2 -l, --lib

Add C<lib> to @INC.  Equivalent to C<-Ilib>.

=head2 -r, --recurse

Descends into subdirectories of any directories specified, looking for tests.

=head2 -s, --shuffle

Sometimes tests are accidentally dependent on tests that have been
run before.  This switch will shuffle the tests to be run prior to
running them, thus ensuring that hidden dependencies in the test
order are likely to be revealed.  The author hopes the run the
algorithm on the preceding sentence to see if he can produce something
slightly less awkward.

=head2 -t

Runs test programs under perl's -t taint warning mode.

=head2 -T

Runs test programs under perl's -T taint mode.

=head2 --timer

Print elapsed time after each test file

=head2 -v, --verbose

Display standard output of test scripts while running them.  Also sets
TEST_VERBOSE in case your tests rely on them.

=head2 -V, --version

Display version info.

=head1 BUGS

Please use the CPAN bug ticketing system at L<http://rt.cpan.org/>.
You can also mail bugs, fixes and enhancements to 
C<< <bug-test-harness@rt.cpan.org> >>.

=head1 TODO

=over 4

=item *

Shuffled tests must be recreatable

=back

=head1 AUTHORS

Andy Lester C<< <andy@petdance.com> >>

=head1 COPYRIGHT

Copyright 2005 by Andy Lester C<< <andy@petdance.com> >>.

This program is free software; you can redistribute it and/or 
modify it under the same terms as Perl itself.

See L<http://www.perl.com/perl/misc/Artistic.html>.

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