# -*- Mode: cperl; cperl-indent-level: 4 -*-
-# $Id: Harness.pm,v 1.54 2003/08/15 01:05:00 andy Exp $
+# $Id: Harness.pm,v 1.76 2003/11/25 04:41:03 andy Exp $
package Test::Harness;
use Config;
use strict;
-use vars qw($VERSION $Verbose $Switches $Have_Devel_Corestack $Curtest
- $Columns $verbose $switches $ML $Strap
- @ISA @EXPORT @EXPORT_OK $Last_ML_Print
- );
+use vars qw(
+ $VERSION
+ @ISA @EXPORT @EXPORT_OK
+ $Verbose $Switches $Debug
+ $verbose $switches $debug
+ $Have_Devel_Corestack
+ $Curtest
+ $Columns
+ $ML $Last_ML_Print
+ $Strap
+);
+
+=head1 NAME
+
+Test::Harness - Run Perl standard test scripts with statistics
+
+=head1 VERSION
+
+Version 2.38
+
+ $Header: /home/cvs/test-harness/lib/Test/Harness.pm,v 1.76 2003/11/25 04:41:03 andy Exp $
+
+=cut
+
+$VERSION = '2.38';
# Backwards compatibility for exportable variable names.
*verbose = *Verbose;
*switches = *Switches;
+*debug = *Debug;
$Have_Devel_Corestack = 0;
-$VERSION = '2.30';
-
$ENV{HARNESS_ACTIVE} = 1;
END {
@EXPORT_OK = qw($verbose $switches);
$Verbose = $ENV{HARNESS_VERBOSE} || 0;
+$Debug = $ENV{HARNESS_DEBUG} || 0;
$Switches = "-w";
$Columns = $ENV{HARNESS_COLUMNS} || $ENV{COLUMNS} || 80;
$Columns--; # Some shells have trouble with a full line of text.
-
-=head1 NAME
-
-Test::Harness - run perl standard test scripts with statistics
-
=head1 SYNOPSIS
use Test::Harness;
=item B<Todo tests>
-If the standard output line contains the substring C< # TODO> after
+If the standard output line contains the substring C< # TODO > after
C<not ok> or C<not ok NUMBER>, it is counted as a todo test. The text
afterwards is the thing that has to be done before this test will
succeed.
not ok 13 # TODO harness the power of the atom
+Note that the TODO must have a space after it.
+
=begin _deprecated
Alternatively, you can specify a list of what tests are todo as part
=back
-
=head2 Taint mode
-Test::Harness will honor the C<-T> in the #! line on your test files. So
-if you begin a test with:
+Test::Harness will honor the C<-T> or C<-t> in the #! line on your
+test files. So if you begin a test with:
#!perl -T
the test will be run with taint mode on.
-
=head2 Configuration variables.
These variables can be used to configure the behavior of
=over 4
-=item B<$Test::Harness::verbose>
+=item B<$Test::Harness::Verbose>
-The global variable $Test::Harness::verbose is exportable and can be
-used to let runtests() display the standard output of the script
-without altering the behavior otherwise.
+The global variable C<$Test::Harness::Verbose> is exportable and can be
+used to let C<runtests()> display the standard output of the script
+without altering the behavior otherwise. The F<prove> utility's C<-v>
+flag will set this.
=item B<$Test::Harness::switches>
-The global variable $Test::Harness::switches is exportable and can be
+The global variable C<$Test::Harness::switches> is exportable and can be
used to set perl command line options used for running the test
-script(s). The default value is C<-w>.
+script(s). The default value is C<-w>. It overrides C<HARNESS_SWITCHES>.
=back
=head2 Failure
-It will happen, your tests will fail. After you mop up your ego, you
+It will happen: your tests will fail. After you mop up your ego, you
can begin examining the summary report:
t/base..............ok
=item B<Wstat>
-The wait status of the test I<umm, I need a better explanation here>.
+The wait status of the test.
=item B<Total>
my($total, $failed) = _run_all_tests(@test_files);
-Runs all the given @test_files (as runtests()) but does it quietly (no
-report). $total is a hash ref summary of all the tests run. Its keys
-and values are this:
+Runs all the given C<@test_files> (as C<runtests()>) but does it
+quietly (no report). $total is a hash ref summary of all the tests
+run. Its keys and values are this:
bonus Number of individual todo tests unexpectedly passed
max Number of individual tests ran
tests Number of test files originally given
skipped Number of test files skipped
-If $total->{bad} == 0 and $total->{max} > 0, you've got a successful
-test.
+If C<< $total->{bad} == 0 >> and C<< $total->{max} > 0 >>, you've
+got a successful test.
$failed is a hash ref of all the test scripts which failed. Each key
is the name of a test script, each value is another hash representing
percent Percentage of tests which failed
canon List of tests which failed (as string).
-Needless to say, $failed should be empty if everything passed.
+C<$failed> should be empty if everything passed.
B<NOTE> Currently this function is still noisy. I'm working on it.
my $width = _leader_width(@tests);
foreach my $tfile (@tests) {
+ if ( $Test::Harness::Debug ) {
+ print "# Running: ", $Strap->_command_line($tfile), "\n";
+ }
+
$Last_ML_Print = 0; # so each test prints at least once
my($leader, $ml) = _mk_leader($tfile, $width);
local $ML = $ml;
+
print $leader;
$tot{files}++;
$Strap->{_seen_header} = 0;
my %results = $Strap->analyze_file($tfile) or
- do { warn "$Strap->{error}\n"; next };
+ do { warn $Strap->{error}, "\n"; next };
# state of the current test.
my @failed = grep { !$results{details}[$_-1]{ok} }
my($leader, $ml) = _mk_leader($test_file, $width);
-Generates the 't/foo........' $leader for the given $test_file as well
+Generates the 't/foo........' $leader for the given C<$test_file> as well
as a similar version which will overwrite the current line (by use of
-\r and such). $ml may be empty if Test::Harness doesn't think you're
+\r and such). C<$ml> may be empty if Test::Harness doesn't think you're
on TTY.
-The $width is the width of the "yada/blah.." string.
+The C<$width> is the width of the "yada/blah.." string.
=cut
C<&runtests> is exported by Test::Harness by default.
-C<$verbose> and C<$switches> are exported upon request.
-
+C<$verbose>, C<$switches> and C<$debug> are exported upon request.
=head1 DIAGNOSTICS
B<NOTE> This currently only works when sitting in the perl source
directory!
+=item C<HARNESS_DEBUG>
+
+If true, Test::Harness will print debugging information about itself as
+it runs the tests. This is different from C<HARNESS_VERBOSE>, which prints
+the output from the test being run. Setting C<$Test::Harness::Debug> will
+override this, or you can use the C<-d> switch in the F<prove> utility.
+
=item C<HARNESS_FILELEAK_IN_DIR>
When set to the name of a directory, harness will check after each
=item C<HARNESS_OK_SLOW>
-If true, the C<ok> messages are printed out only every second.
-This reduces output and therefore may for example help testing
-over slow connections.
+If true, the C<ok> messages are printed out only every second. This
+reduces output and may help increase testing speed over slow
+connections, or with very large numbers of tests.
+
+=item C<HARNESS_PERL>
+
+Usually your tests will be run by C<$^X>, the currently-executing Perl.
+However, you may want to have it run by a different executable, such as
+a threading perl, or a different version.
+
+If you're using the F<prove> utility, you can use the C<--perl> switch.
=item C<HARNESS_PERL_SWITCHES>
=item C<HARNESS_VERBOSE>
If true, Test::Harness will output the verbose results of running
-its tests. Setting $Test::Harness::verbose will override this.
+its tests. Setting C<$Test::Harness::verbose> will override this,
+or you can use the C<-v> switch in the F<prove> utility.
=back
HARNESS_COMPILE_TEST currently assumes it's run from the Perl source
directory.
+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 AUTHORS
+
+Original code by Michael G Schwern, maintained by Andy Lester.
+
+=head1 COPYRIGHT
+
+Copyright 2003 by Michael G Schwern C<< <schwern@pobox.com> >>,
+ 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
projects / p5sagit/p5-mst-13.2.git / blobdiff