The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.

Name

Test.Harness - Run TAP standard JavaScript test scripts with statistics

Synopsis

  Test.Harness.runTests('foo.js', bar.js');

Description

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.

STOP AGAIN! Test.Harness is an abstract base class. See Test.Harness.Browser for a concrete subclass offering a browser-based harness.

Test.Harness runs tests and expects to get the results from the TestResults attribute of the Test.Builder object. These results conform to a format called TAP, the Test Anything Protocol. It is defined in http://search.cpan.org/dist/Test-Harness/lib/Test/Harness/TAP.pod.

Failure

When tests fail, analyze the summary report:

  base.html..............ok
  nonumbers.js...........ok
  ok.js..................ok
  test-harness.js........ok
  waterloo.html..........dubious
  DIED. FAILED tests 1, 3, 5, 7, 9, 11, 13, 15, 17, 19
          Failed 10/20 tests, 50.00% okay
  Failed Test   Total Fail  Failed  List of Failed
  -------------------------------------------------------------
  waterloo.html    20   10  50.00%  1 3 5 7 9 11 13 15 17 19
  Failed 1/5 test scripts, 80.00% okay. 10/44 subtests failed, 77.27% okay.

Everything passed but waterloo.html. It failed 10 of 20 tests.

The columns in the summary report mean:

Failed Test

The test file which failed.

Total

Total number of tests expected to run.

Fail

Number that failed, either from "not ok" or because they never ran.

Failed

Percentage of the total tests that failed.

List of Failed

A list of the tests that failed. Successive failures may be abbreviated (ie. 15-20 to indicate that tests 15, 16, 17, 18, 19 and 20 failed).

Class Methods

  Test.Harness.runTests('testone.js', 'testtwo.js');

Constructs a new Test.Harness object and calls its runTests() instance method, passing all arguments along.

Constructors

  var harness = new Test.Harness();

Constructs a new Test.Harness object.

Instance Methods

runTests
  harness.runTests('testone.js', 'testtwo.js');

This method runs all the given test files and divines whether they passed or failed based on the contents of the TestRusults attribute of their global Test.Builder.Test object. It prints out each individual test that failed along with a summary report and a how long it all took. When all tests have been run, a diagnostic message will be output.

encoding
  var encoding = harness.encoding();
  harness = harness.encoding(encoding);

Gets or sets the encoding to use for the test scripts. Returns the harness object when setting the encoding. The encoding is null by default, and therefore unset.

Diagnostics

All tests successful.\nFiles=%d, Tests=%d, %s

If all tests are successful some statistics about the performance are output.

FAILED tests %s\n\tFailed %d/%d tests, %.2f%% okay.

For any single script that has failing subtests statistics like the above are printed.

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.

See Also

Test.Simple and Test.More, modules with which to write tests.

Authors

David Wheeler <david@kineticode.com>, based on the original Test::Harness included with Perl.

Copyright

Copyright 2005 by David Wheeler <david@kineticode.com>

This program is free software; you can redistribute it and/or modify it under the terms of the Perl Artistic License or the GNU GPL.

See http://www.perl.com/perl/misc/Artistic.html and http://www.gnu.org/copyleft/gpl.html.