/ 
JS-Test-Simple-0.29
River stage one • 1 direct dependent • 3 total dependents
/ Test.Harness.Browser

Name

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

Synopsis

<html>
<head>
  <script type="text/javascript" src="JSAN.js"></script>
</head>
<body>
  <script type="text/javascript">
    new JSAN("../lib").use("Test.Harness.Browser");
    new Test.Harness.Browser('JSAN.js').runTests(
        'async.js',
        'bad_plan.html',
        'buffer.js',
        'builder.html'
    );
  </script>
</body>
</html>

or non-JSAN approach (JavaScript test files will not work without JSAN)

<html>
<head>
  <script type="text/javascript" src="Test/Harness.js"></script>
  <script type="text/javascript" src="Test/Harness/Browser.js"></script>
</head>
<body>
  <script type="text/javascript">
    Test.Harness.Browser.runTests(
        'async.html',
        'bad_plan.html',
        'buffer.html',
        'builder.html'
    );
  </script>
</body>
</html>

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.

Test.Harness.Browser runs JavaScript tests in a browser and expects to get the results from the TestResults attribute of the Test.Builder object constructed by each test script. 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. See Test.Harness for details on the output.

Class Methods

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

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

Constructors

var harness = new Test.Harness.Browser('script.js', 'another.js');

Constructs a new Test.Harness.Browser object. If your tests will be pure JavaScript files (that is, ending in .js, pass in a list of dependency scripts to be loaded before each script. A particularly handy one to load is JSAN.js (http://www.openjsan.org/go?l=JSAN). This library will allow you to dymamically load whatever other libraries you need from each test script, like so:

var jsan = new JSAN('../lib');
jsan.use('Test.More');
jsan.use('HTTP.Query');
plan({tests: 1});
var q = new HTTP.Query;
isaOK(q, HTTP.Query);

In fact, this is the approach that Test.Simple's own tests take. Check 'em out!

Instance Methods

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

This method runs all the given test files and divines whether they passed or failed based on the contents of the TestResults 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. See Test.Harness for details on the output.

For .js files, be sure to pass to the Test.Harness.Browser constructor a list of required scripts to be loaded before the test is loaded and executed.

GET Options

An HTML file that uses Test.Harness.Browser will automatically process the GET its arguments, and these can be used to affect the behavior of the harness.

verbose
index.html?verbose=1

Set the verbose option to a true value to have all of the output of all of the tests in the harness output to the browser window. By default, only failing tests display their output.

file
index.html?file=foo.html;file=bar.html

Set the file option to override the list of files passed to runTest(). This option may be specified multiple times, and each file specified will be passed to runTest().

Bugs

Safari (and maybe KHTML?) has a number of bugs that affect how Test.Harness.Browser works. The most obvious is that it cannot run tests on a local disk. The harness only works in Safari if the tests are served by a Web server. The WebKit team is aware of the issue; expect it to be fixed in a future version.

Other Safari bugs I reported while writing this module:

iFrame Doesn't seem to Respect a local "file://" src

http://bugs.webkit.org/show_bug.cgi?id=3593

Function.toString() Doesn't Stringify Constructors as Attributes

Some tests are skipped in tests/create.html, tests/harness.html, and tests/more.html to work around this bug.

http://bugs.webkit.org/show_bug.cgi?id=3537

WebKit JavaScript Does not Properly Support Circular References

One test is skipped in tests/circular_data.html to work around this bug.

http://bugs.webkit.org/show_bug.cgi?id=3539

iFrames Appear to be Cached

http://bugs.webkit.org/show_bug.cgi?id=3580

iFrames set to display:none are Missing from frames array

So the iframe used to run tests isn't hidden in Safari. Instead, it is set to "height: 0; widht: 0".

http://bugs.webkit.org/show_bug.cgi?id=3581

Add Support for the watch() method of Object

This would just be nice to have, so that we wouldn't have to set timeouts to check for test completion.

http://bugs.webkit.org/show_bug.cgi?id=3659

See Also

Test.Harness, the base class for this class.

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

Authors

David Wheeler <david@kineticode.com>.

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.