Index for Section 3

Alphabetical listing for T

Bottom of page

Test::Harness(3)
NAME
  Test::Harness - run perl standard test scripts with statistics

SYNOPSIS
  use Test::Harness;

  runtests(@tests);

DESCRIPTION
  (By using the the Test manpage module, you can write test scripts without
  knowing the exact output this module expects.	 However, if you need to know
  the specifics, read on!)

  Perl test scripts print to standard output ""ok N"" for each single test,
  where "N" is an increasing sequence of integers. The first line output by a
  standard test script is ""1..M"" with "M" being the number of tests that
  should be run within the test script. Test::Harness::runtests(@tests) runs
  all the testscripts named as arguments and checks standard output for the
  expected ""ok N"" strings.

  After all tests have been performed, runtests() prints some performance
  statistics that are computed by the Benchmark module.

  The test script output

  Any output from the testscript to standard error is ignored and bypassed,
  thus will be seen by the user. Lines written to standard output containing
  "/^(not\s+)?ok\b/" are interpreted as feedback for runtests().  All other
  lines are discarded.

  It is tolerated if the test numbers after "ok" are omitted. In this case
  Test::Harness maintains temporarily its own counter until the script
  supplies test numbers again. So the following test script

      print <<END;
      1..6
      not ok
      ok
      not ok
      ok
      ok
      END

  will generate

      FAILED tests 1, 3, 6
      Failed 3/6 tests, 50.00% okay

  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 $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".

  If the standard output line contains substring " # Skip" (with variations
  in spacing and case) after "ok" or "ok NUMBER", it is counted as a skipped
  test.	 If the whole testscript succeeds, the count of skipped tests is
  included in the generated output.

  "Test::Harness" reports the text after " # Skip(whatever)" as a reason for
  skipping.  Similarly, one can include a similar explanation in a "1..0"
  line emitted if the test is skipped completely:

    1..0 # Skipped: no leverage found

EXPORT
  "&runtests" is exported by Test::Harness per default.

DIAGNOSTICS
  "All tests successful.\nFiles=%d,  Tests=%d, %s"
      If all tests are successful some statistics about the performance are
      printed.

  "FAILED tests %s\n\tFailed %d/%d tests, %.2f%% okay."
      For any single script that has failing subtests statistics like the
      above are printed.

  "Test returned status %d (wstat %d)"
      Scripts that return a non-zero exit status, both "$? >> 8" and "$?" are
      printed in a message similar to the above.

  "Failed 1 test, %.2f%% okay. %s"
  "Failed %d/%d tests, %.2f%% okay. %s"
      If not all tests were successful, the script dies with one of the above
      messages.

ENVIRONMENT
  Setting "HARNESS_IGNORE_EXITCODE" makes harness ignore the exit status of
  child processes.

  Setting "HARNESS_NOTTY" 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).

  Setting "HARNESS_COMPILE_TEST" to a true value will make harness attempt to
  compile the test using "perlcc" before running it.

  If "HARNESS_FILELEAK_IN_DIR" is 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 predicatable results.

  The value of "HARNESS_PERL_SWITCHES" 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 "HARNESS_COLUMNS" is set, then 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.

  Harness sets "HARNESS_ACTIVE" before executing the individual tests.	This
  allows the tests to determine if they are being executed through the
  harness or by any other means.

SEE ALSO
  the Test manpage for writing test scripts and also the Benchmark manpage
  for the underlying timing routines.

AUTHORS
  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. Current
  maintainer is Andreas Koenig.

BUGS
  Test::Harness uses $^X to determine the perl binary to run the tests with.
  Test scripts running via the shebang ("#!") line may not be portable
  because $^X is not consistent for shebang scripts across platforms. This is
  no problem when Test::Harness is run with an absolute path to the perl
  binary or when $^X can be found in the path.

Index for Section 3

Alphabetical listing for T

Top of page