Edit File: Test::Harness.3pm
.\" Automatically generated by Pod::Man 2.27 (Pod::Simple 3.28) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is turned on, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .nr rF 0 .if \n(.g .if rF .nr rF 1 .if (\n(rF:(\n(.g==0)) \{ . if \nF \{ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{ . nr % 0 . nr F 2 . \} . \} .\} .rr rF .\" ======================================================================== .\" .IX Title "Test::Harness 3" .TH Test::Harness 3 "2018-03-19" "perl v5.16.3" "User Contributed Perl Documentation" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAME" Test::Harness \- Run Perl standard test scripts with statistics .SH "VERSION" .IX Header "VERSION" Version 3.42 .SH "SYNOPSIS" .IX Header "SYNOPSIS" .Vb 1 \& use Test::Harness; \& \& runtests(@test_files); .Ve .SH "DESCRIPTION" .IX Header "DESCRIPTION" Although, for historical reasons, the Test::Harness distribution takes its name from this module it now exists only to provide TAP::Harness with an interface that is somewhat backwards compatible with Test::Harness 2.xx. If you're writing new code consider using TAP::Harness directly instead. .PP Emulation is provided for \f(CW\*(C`runtests\*(C'\fR and \f(CW\*(C`execute_tests\*(C'\fR but the pluggable 'Straps' interface that previous versions of Test::Harness supported is not reproduced here. Straps is now available as a stand alone module: Test::Harness::Straps. .PP See TAP::Parser, TAP::Harness for the main documentation for this distribution. .SH "FUNCTIONS" .IX Header "FUNCTIONS" The following functions are available. .ie n .SS "runtests( @test_files )" .el .SS "runtests( \f(CW@test_files\fP )" .IX Subsection "runtests( @test_files )" This runs all the given \fI\f(CI@test_files\fI\fR and divines whether they passed or failed based on their output to \s-1STDOUT \s0(details above). It prints out each individual test which failed along with a summary report and a how long it all took. .PP It returns true if everything was ok. Otherwise it will \f(CW\*(C`die()\*(C'\fR with one of the messages in the \s-1DIAGNOSTICS\s0 section. .SS "execute_tests( tests => \e@test_files, out => \e*FH )" .IX Subsection "execute_tests( tests => @test_files, out => *FH )" Runs all the given \f(CW@test_files\fR (just like \f(CW\*(C`runtests()\*(C'\fR) but doesn't generate the final report. During testing, progress information will be written to the currently selected output filehandle (usually \f(CW\*(C`STDOUT\*(C'\fR), or to the filehandle given by the \&\f(CW\*(C`out\*(C'\fR parameter. The \fIout\fR is optional. .PP Returns a list of two values, \f(CW$total\fR and \f(CW$failed\fR, describing the results. \f(CW$total\fR is a hash ref summary of all the tests run. Its keys and values are this: .PP .Vb 5 \& bonus Number of individual todo tests unexpectedly passed \& max Number of individual tests ran \& ok Number of individual tests passed \& sub_skipped Number of individual tests skipped \& todo Number of individual todo tests \& \& files Number of test files ran \& good Number of test files passed \& bad Number of test files failed \& tests Number of test files originally given \& skipped Number of test files skipped .Ve .PP If \f(CW\*(C`$total\->{bad} == 0\*(C'\fR and \f(CW\*(C`$total\->{max} > 0\*(C'\fR, you've got a successful test. .PP \&\f(CW$failed\fR is a hash ref of all the test scripts that failed. Each key is the name of a test script, each value is another hash representing how that script failed. Its keys are these: .PP .Vb 6 \& name Name of the test which failed \& estat Script\*(Aqs exit value \& wstat Script\*(Aqs wait status \& max Number of individual tests \& failed Number which failed \& canon List of tests which failed (as string). .Ve .PP \&\f(CW$failed\fR should be empty if everything passed. .SH "EXPORT" .IX Header "EXPORT" \&\f(CW&runtests\fR is exported by \f(CW\*(C`Test::Harness\*(C'\fR by default. .PP \&\f(CW&execute_tests\fR, \f(CW$verbose\fR, \f(CW$switches\fR and \f(CW$debug\fR are exported upon request. .SH "ENVIRONMENT VARIABLES THAT TAP::HARNESS::COMPATIBLE SETS" .IX Header "ENVIRONMENT VARIABLES THAT TAP::HARNESS::COMPATIBLE SETS" \&\f(CW\*(C`Test::Harness\*(C'\fR sets these before executing the individual tests. .ie n .IP """HARNESS_ACTIVE""" 4 .el .IP "\f(CWHARNESS_ACTIVE\fR" 4 .IX Item "HARNESS_ACTIVE" This is set to a true value. It allows the tests to determine if they are being executed through the harness or by any other means. .ie n .IP """HARNESS_VERSION""" 4 .el .IP "\f(CWHARNESS_VERSION\fR" 4 .IX Item "HARNESS_VERSION" This is the version of \f(CW\*(C`Test::Harness\*(C'\fR. .SH "ENVIRONMENT VARIABLES THAT AFFECT TEST::HARNESS" .IX Header "ENVIRONMENT VARIABLES THAT AFFECT TEST::HARNESS" .ie n .IP """HARNESS_PERL_SWITCHES""" 4 .el .IP "\f(CWHARNESS_PERL_SWITCHES\fR" 4 .IX Item "HARNESS_PERL_SWITCHES" Setting this adds perl command line switches to each test file run. .Sp For example, \f(CW\*(C`HARNESS_PERL_SWITCHES=\-T\*(C'\fR will turn on taint mode. \&\f(CW\*(C`HARNESS_PERL_SWITCHES=\-MDevel::Cover\*(C'\fR will run \f(CW\*(C`Devel::Cover\*(C'\fR for each test. .Sp \&\f(CW\*(C`\-w\*(C'\fR is always set. You can turn this off in the test with \f(CW\*(C`BEGIN { $^W = 0 }\*(C'\fR. .ie n .IP """HARNESS_TIMER""" 4 .el .IP "\f(CWHARNESS_TIMER\fR" 4 .IX Item "HARNESS_TIMER" Setting this to true will make the harness display the number of milliseconds each test took. You can also use \fIprove\fR's \f(CW\*(C`\-\-timer\*(C'\fR switch. .ie n .IP """HARNESS_VERBOSE""" 4 .el .IP "\f(CWHARNESS_VERBOSE\fR" 4 .IX Item "HARNESS_VERBOSE" If true, \f(CW\*(C`Test::Harness\*(C'\fR will output the verbose results of running its tests. Setting \f(CW$Test::Harness::verbose\fR will override this, or you can use the \f(CW\*(C`\-v\*(C'\fR switch in the \fIprove\fR utility. .ie n .IP """HARNESS_OPTIONS""" 4 .el .IP "\f(CWHARNESS_OPTIONS\fR" 4 .IX Item "HARNESS_OPTIONS" Provide additional options to the harness. Currently supported options are: .RS 4 .ie n .IP """j<n>""" 4 .el .IP "\f(CWj<n>\fR" 4 .IX Item "j<n>" Run <n> (default 9) parallel jobs. .ie n .IP """c""" 4 .el .IP "\f(CWc\fR" 4 .IX Item "c" Try to color output. See \*(L"new\*(R" in TAP::Formatter::Base. .ie n .IP """a<file.tgz>""" 4 .el .IP "\f(CWa<file.tgz>\fR" 4 .IX Item "a<file.tgz>" Will use TAP::Harness::Archive as the harness class, and save the \s-1TAP\s0 to \&\f(CW\*(C`file.tgz\*(C'\fR .ie n .IP """fPackage\-With\-Dashes""" 4 .el .IP "\f(CWfPackage\-With\-Dashes\fR" 4 .IX Item "fPackage-With-Dashes" Set the formatter_class of the harness being run. Since the \f(CW\*(C`HARNESS_OPTIONS\*(C'\fR is seperated by \f(CW\*(C`:\*(C'\fR, we use \f(CW\*(C`\-\*(C'\fR instead. .RE .RS 4 .Sp Multiple options may be separated by colons: .Sp .Vb 1 \& HARNESS_OPTIONS=j9:c make test .Ve .RE .ie n .IP """HARNESS_SUBCLASS""" 4 .el .IP "\f(CWHARNESS_SUBCLASS\fR" 4 .IX Item "HARNESS_SUBCLASS" Specifies a TAP::Harness subclass to be used in place of TAP::Harness. .ie n .IP """HARNESS_SUMMARY_COLOR_SUCCESS""" 4 .el .IP "\f(CWHARNESS_SUMMARY_COLOR_SUCCESS\fR" 4 .IX Item "HARNESS_SUMMARY_COLOR_SUCCESS" Determines the Term::ANSIColor for the summary in case it is successful. This color defaults to \f(CW\*(Aqgreen\*(Aq\fR. .ie n .IP """HARNESS_SUMMARY_COLOR_FAIL""" 4 .el .IP "\f(CWHARNESS_SUMMARY_COLOR_FAIL\fR" 4 .IX Item "HARNESS_SUMMARY_COLOR_FAIL" Determines the Term::ANSIColor for the failure in case it is successful. This color defaults to \f(CW\*(Aqred\*(Aq\fR. .SH "Taint Mode" .IX Header "Taint Mode" Normally when a Perl program is run in taint mode the contents of the \&\f(CW\*(C`PERL5LIB\*(C'\fR environment variable do not appear in \f(CW@INC\fR. .PP Because \f(CW\*(C`PERL5LIB\*(C'\fR is often used during testing to add build directories to \f(CW@INC\fR \f(CW\*(C`Test::Harness\*(C'\fR passes the names of any directories found in \f(CW\*(C`PERL5LIB\*(C'\fR as \-I switches. The net effect of this is that \f(CW\*(C`PERL5LIB\*(C'\fR is honoured even in taint mode. .SH "SEE ALSO" .IX Header "SEE ALSO" TAP::Harness .SH "BUGS" .IX Header "BUGS" Please report any bugs or feature requests to \&\f(CW\*(C`bug\-test\-harness at rt.cpan.org\*(C'\fR, or through the web interface at <http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Test\-Harness>. I will be notified, and then you'll automatically be notified of progress on your bug as I make changes. .SH "AUTHORS" .IX Header "AUTHORS" Andy Armstrong \f(CW\*(C`<andy@hexten.net>\*(C'\fR .PP Test::Harness 2.64 (maintained by Andy Lester and on which this module is based) has this attribution: .PP .Vb 5 \& Either Tim Bunce or Andreas Koenig, we don\*(Aqt know. What we know for \& sure is, that it was inspired by Larry Wall\*(Aqs F<TEST> script that came \& with perl distributions for ages. Numerous anonymous contributors \& exist. Andreas Koenig held the torch for many years, and then \& Michael G Schwern. .Ve .SH "LICENCE AND COPYRIGHT" .IX Header "LICENCE AND COPYRIGHT" Copyright (c) 2007\-2011, Andy Armstrong \f(CW\*(C`<andy@hexten.net>\*(C'\fR. All rights reserved. .PP This module is free software; you can redistribute it and/or modify it under the same terms as Perl itself. See perlartistic.