STOP! If all you want to do is write a test script, consider
using Test::Simple. Test::Harness is the module that reads the
output from Test::Simple, Test::More and other modules based on
Test::Builder. You don't need to know about Test::Harness to use
those modules.
Test::Harness runs tests and expects output from the test in a
certain format. That format is called TAP, the Test Anything
Protocol. It is defined in the Test::Harness::TAP manpage.
Test::Harness::runtests(@tests) runs all the testscripts named
as arguments and checks standard output for the expected strings
in TAP format.
The prove utility is a thin wrapper around Test::Harness.
The package 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 prove utility's -v
flag will set this.
The package variable $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 -w. It overrides HARNESS_SWITCHES.
This runs all the given @test_files and divines whether they passed
or failed based on their output to STDOUT (details above). It prints
out each individual test which failed along with a summary report and
a how long it all took.
It returns true if everything was ok. Otherwise it will die() with
one of the messages in the DIAGNOSTICS section.
This value will be used for the width of the terminal. If it is not
set then it will default to COLUMNS. If this is not set, it will
default to 80. Note that users of Bourne-sh based shells will need to
export COLUMNS for this module to use that variable.
If true, Test::Harness will print debugging information about itself as
it runs the tests. This is different from HARNESS_VERBOSE, which prints
the output from the test being run. Setting $Test::Harness::Debug will
override this, or you can use the -d switch in the prove utility.
When set to the name of a directory, harness will check after each
test whether new files appeared in that directory, and report them as
LEAKED FILES: scr.tmp 0 my.db
If relative, directory name is with respect to the current directory at
the moment runtests() was called. Putting absolute path into
HARNESS_FILELEAK_IN_DIR may give more predictable results.
When set to a true value, forces it to behave as though STDOUT were
not a console. You may need to set this if you don't want harness to
output more frequent progress messages using carriage returns. Some
consoles may not handle carriage returns properly (which results in a
somewhat messy output).
Usually your tests will be run by $^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 prove utility, you can use the --perl switch.
Its value will be prepended to the switches used to invoke perl on
each test. For example, setting HARNESS_PERL_SWITCHES to -W will
run all tests with all warnings enabled.
If true, Test::Harness will output the verbose results of running
its tests. Setting $Test::Harness::verbose will override this,
or you can use the -v switch in the prove utility.
perldoc2tree.cgi: /usr/lib/perl5/5.8.8/Test/Harness.pm: cannot resolve L in paragraph 234.
perldoc2tree.cgi: /usr/lib/perl5/5.8.8/Test/Harness.pm: cannot resolve L in paragraph 234.
The included prove utility for running test scripts from the command line,
Test and the Test::Simple manpage for writing test scripts, Benchmark for
the underlying timing routines, and the Devel::Cover manpage for test coverage
analysis.
Provide a way of running tests quietly (ie. no printing) for automated
validation of tests. This will probably take the form of a version
of runtests() which rather than printing its output returns raw data
on the state of the tests. (Partially done in Test::Harness::Straps)
Document the format.
Fix HARNESS_COMPILE_TEST without breaking its core usage.
Figure a way to report test names in the failure summary.
Rework the test summary so long test names are not truncated as badly.
(Partially done with new skip test styles)
Either Tim Bunce or Andreas Koenig, we don't know. What we know for
sure is, that it was inspired by Larry Wall's 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.
Current maintainer is Andy Lester <andy at petdance.com>.
