From a5dbcf56c2c901024a062c4e2ece6688b091881e Mon Sep 17 00:00:00 2001
From: James Graham <james@hoppipolla.co.uk>
Date: Tue, 6 May 2014 12:20:11 +0100
Subject: [PATCH] Move docs to their own files and format as markdown.

---
 docs/api.md        | 407 +++++++++++++++++++++++++++++++++++++++++++
 docs/idlharness.md | 118 +++++++++++++
 idlharness.js      | 126 +-------------
 testharness.js     | 417 +--------------------------------------------
 4 files changed, 527 insertions(+), 541 deletions(-)
 create mode 100644 docs/api.md
 create mode 100644 docs/idlharness.md

diff --git a/docs/api.md b/docs/api.md
new file mode 100644
index 0000000..660b08b
--- /dev/null
+++ b/docs/api.md
@@ -0,0 +1,407 @@
+## Introduction ##
+
+testharness.js provides a framework for writing testcases. It is intended to
+provide a convenient API for making common assertions, and to work both
+for testing synchronous and asynchronous DOM features in a way that
+promotes clear, robust, tests.
+
+## Basic Usage ##
+
+To use this file, import the script and the testharnessreport script into
+the test document:
+
+    <script src="/resources/testharness.js"></script>
+    <script src="/resources/testharnessreport.js"></script>
+
+Within each file one may define one or more tests. Each test is atomic
+in the sense that a single test has a single result (`PASS`/`FAIL`/`TIMEOUT`).
+Within each test one may have a number of asserts. The test fails at the
+first failing assert, and the remainder of the test is (typically) not run.
+
+If the file containing the tests is a HTML file, a table containing the test
+results will be added to the document after all tests have run. By default this
+will be added to a div element with id=log if it exists, or a new div element
+appended to document.body if it does not.
+
+NOTE: By default tests must be created before the load event fires. For ways
+to create tests after the load event, see "Determining when all tests
+are complete", below
+
+## Synchronous Tests ##
+
+To create a synchronous test use the test() function:
+
+    test(test_function, name, properties)
+
+`test_function` is a function that contains the code to test. For example a
+trivial passing test would be:
+
+    test(function() {assert_true(true)}, "assert_true with true")
+
+The function passed in is run in the test() call.
+
+`properties` is a javascript object for passing extra options to the
+test. Currently it is only used to provide test-specific
+metadata, as described in the [metadata](#metadata) section below.
+
+## Asynchronous Tests ##
+
+Testing asynchronous features is somewhat more complex since the result of
+a test may depend on one or more events or other callbacks. The API provided
+for testing these features is indended to be rather low-level but hopefully
+applicable to many situations.
+
+To create a test, one starts by getting a Test object using async_test:
+
+    async_test(name, properties)
+
+e.g.
+    var t = async_test("Simple async test")
+
+Assertions can be added to the test by calling the step method of the test
+object with a function containing the test assertions:
+
+    t.step(function() {assert_true(true)});
+
+When all the steps are complete, the done() method must be called:
+
+    t.done();
+
+As a convenience, async_test can also takes a function as first argument.
+This function is called with the test object as both its `this` object and
+first argument. The above example can be rewritten as:
+
+    async_test(function(t) {
+        object.some_event = function() {
+            t.step(function (){assert_true(true); t.done();});
+        };
+    }, "Simple async test");
+
+which avoids cluttering the global scope with references to async
+tests instances.
+
+The properties argument is identical to that for `test()`.
+
+In many cases it is convenient to run a step in response to an event or a
+callback. A convenient method of doing this is through the step_func method
+which returns a function that, when called runs a test step. For example
+
+    object.some_event = t.step_func(function(e) {assert_true(e.a)});
+
+For asynchronous callbacks that should never execute, `unreached_func` can
+be used. For example:
+
+    object.some_event = t.unreached_func("some_event should not fire");
+
+## Single Page Tests ##
+
+Sometimes, particularly when dealing with asynchronous behaviour,
+having exactly one test per page is desirable, and the overhead of
+wrapping everything in functions for isolation becomes
+burdensome. For these cases `testharness.js` support "single page
+tests".
+
+In order for a test to be interpreted as a single page test, the
+it must simply not call `test()` or `async_test()` anywhere on the page, and
+must call the `done()` function to indicate that the test is complete. All
+the `assert_*` functions are avaliable as normal, but are called without
+the normal step function wrapper. For example:
+
+    <!doctype html>
+    <title>Example single-page test</title>
+    <script src="/resources/testharness.js"></script>
+    <script src="/resources/testharnessreport.js"></script>
+    <body>
+      <script>
+        assert_equals(document.body, document.getElementsByTagName("body")[0])
+        done()
+     </script>
+
+The test title for sinple page tests is always taken from `document.title`.
+
+## Making assertions ##
+
+Functions for making assertions start `assert_`. The full list of
+asserts avaliable is documented in the [asserts](#asserts) section
+below.. The general signature is
+
+    assert_something(actual, expected, description)
+
+although not all assertions precisely match this pattern e.g. `assert_true`
+only takes `actual` and `description` as arguments.
+
+The description parameter is used to present more useful error messages when
+a test fails
+
+NOTE: All asserts must be located in a `test()` or a step of an
+`async_test()`, unless the test is a single page test. Asserts outside
+these places won't be detected correctly by the harness and may cause
+unexpected exceptions that will lead to an error in the harness.
+
+## Cleanup ##
+
+Occasionally tests may create state that will persist beyond the test itself.
+In order to ensure that tests are independent, such state should be cleaned
+up once the test has a result. This can be achieved by adding cleanup
+callbacks to the test. Such callbacks are registered using the `add_cleanup`
+function on the test object. All registered callbacks will be run as soon as
+the test result is known. For example
+
+    test(function() {
+             window.some_global = "example";
+             this.add_cleanup(function() {delete window.some_global});
+             assert_true(false);
+         });
+
+## Harness Timeout ##
+
+The overall harness admits two timeout values `"normal"` (the
+default) and `"long"`, used for tests which have an unusually long
+runtime. After the timeout is reached, the harness will stop
+waiting for further async tests to complete. By default the
+timeouts are set to 10s and 60s, respectively, but may be changed
+when the test is run on hardware with different performance
+characteristics to a common desktop computer.  In order to opt-in
+to the longer test timeout, the test must specify a meta element:
+
+    <meta name="timeout" content="long">
+
+Occasionally tests may have a race between the harness timing out and
+a particular test failing; typically when the test waits for some event
+that never occurs. In this case it is possible to use `test.force_timeout()`
+in place of `assert_unreached()`, to immediately fail the test but with a
+status of `TIMEOUT`. This should only be used as a last resort when it is
+not possible to make the test reliable in some other way.
+
+## Setup ##
+
+Sometimes tests require non-trivial setup that may fail. For this purpose
+there is a `setup()` function, that may be called with one or two arguments.
+The two argument version is:
+
+    setup(func, properties)
+
+The one argument versions may omit either argument.
+func is a function to be run synchronously. `setup()` becomes a no-op once
+any tests have returned results. Properties are global properties of the test
+harness. Currently recognised properties are:
+
+
+`explicit_done` - Wait for an explicit call to done() before declaring all
+tests complete (see below; implicitly true for single page tests)
+
+`output_document` - The document to which results should be logged. By default
+this is the current document but could be an ancestor document in some cases
+e.g. a SVG test loaded in an HTML wrapper
+
+`explicit_timeout` - disable file timeout; only stop waiting for results
+when the `timeout()` function is called (typically for use when integrating
+with some existing test framework that has its own timeout mechanism).
+
+`allow_uncaught_exception` - don't treat an uncaught exception as an error;
+needed when e.g. testing the `window.onerror` handler.
+
+`timeout_multiplier` - Multiplier to apply to per-test timeouts.
+
+## Determining when all tests are complete ##
+
+By default the test harness will assume there are no more results to come
+when:
+
+ 1. There are no `Test` objects that have been created but not completed
+ 2. The load event on the document has fired
+
+This behaviour can be overridden by setting the `explicit_done` property to
+true in a call to `setup()`. If `explicit_done` is true, the test harness will
+not assume it is done until the global `done()` function is called. Once `done()`
+is called, the two conditions above apply like normal.
+
+## Generating tests ##
+
+There are scenarios in which is is desirable to create a large number of
+(synchronous) tests that are internally similar but vary in the parameters
+used. To make this easier, the `generate_tests` function allows a single
+function to be called with each set of parameters in a list:
+
+    generate_tests(test_function, parameter_lists, properties)
+
+For example:
+
+    generate_tests(assert_equals, [
+        ["Sum one and one", 1+1, 2],
+        ["Sum one and zero", 1+0, 1]
+        ])
+
+Is equivalent to:
+
+    test(function() {assert_equals(1+1, 2)}, "Sum one and one")
+    test(function() {assert_equals(1+0, 1)}, "Sum one and zero")
+
+Note that the first item in each parameter list corresponds to the name of
+the test.
+
+The properties argument is identical to that for `test()`. This may be a
+single object (used for all generated tests) or an array.
+
+## Callback API ##
+
+The framework provides callbacks corresponding to 3 events:
+
+ * `start` - happens when the first Test is created
+ * `result` - happens when a test result is recieved
+ * `complete` - happens when all results are recieved
+
+The page defining the tests may add callbacks for these events by calling
+the following methods:
+
+  `add_start_callback(callback)` - callback called with no arguments
+
+  `add_result_callback(callback)` - callback called with a test argument
+
+  `add_completion_callback(callback)` - callback called with an array of tests
+                                        and an status object
+
+tests have the following properties:
+
+  * `status` - A status code. This can be compared to the `PASS`, `FAIL`, `TIMEOUT` and
+              `NOTRUN` properties on the test object
+
+  * `message` - A message indicating the reason for failure. In the future this
+               will always be a string
+
+ The status object gives the overall status of the harness. It has the
+ following properties:
+
+ * `status` - Can be compared to the `OK`, `ERROR` and `TIMEOUT` properties
+
+ * `message` - An error message set when the status is `ERROR`
+
+## External API ##
+
+In order to collect the results of multiple pages containing tests, the test
+harness will, when loaded in a nested browsing context, attempt to call
+certain functions in each ancestor and opener browsing context:
+
+ * start - `start_callback`
+ * result - `result_callback`
+ * complete - `completion_callback`
+
+These are given the same arguments as the corresponding internal callbacks
+described above.
+
+## External API through cross-document messaging ##
+
+Where supported, the test harness will also send messages using
+cross-document messaging to each ancestor and opener browsing context. Since
+it uses the wildcard keyword (*), cross-origin communication is enabled and
+script on different origins can collect the results.
+
+This API follows similar conventions as those described above only slightly
+modified to accommodate message event API. Each message is sent by the harness
+is passed a single vanilla object, available as the `data` property of the
+event object. These objects are structures as follows:
+
+ * start - `{ type: "start" }`
+ * result - `{ type: "result", test: Test }`
+ * complete - `{ type: "complete", tests: [Test, ...], status: TestsStatus }`
+
+## List of Assertions ##
+
+### `assert_true(actual, description)`
+asserts that `actual` is strictly true
+
+### `assert_false(actual, description)`
+asserts that `actual` is strictly false
+
+### `assert_equals(actual, expected, description)`
+asserts that `actual` is the same value as `expected`
+
+### `assert_not_equals(actual, expected, description)`
+asserts that `actual` is a different value to `expected`.
+This means that `expected` is a misnomer.
+
+### `assert_in_array(actual, expected, description)`
+asserts that `expected` is an Array, and `actual` is equal to one of the
+members i.e. `expected.indexOf(actual) != -1`
+
+### `assert_array_equals(actual, expected, description)`
+asserts that `actual` and `expected` have the same
+length and the value of each indexed property in `actual` is the strictly equal
+to the corresponding property value in `expected`
+
+### `assert_approx_equals(actual, expected, epsilon, description)`
+asserts that `actual` is a number within +`- `epsilon` of `expected`
+
+### `assert_less_than(actual, expected, description)`
+asserts that `actual` is a number less than `expected`
+
+### `assert_greater_than(actual, expected, description)`
+asserts that `actual` is a number greater than `expected`
+
+### `assert_less_than_equal(actual, expected, description)`
+asserts that `actual` is a number less than or equal to `expected`
+
+### `assert_greater_than_equal(actual, expected, description)`
+asserts that `actual` is a number greater than or equal to `expected`
+
+### `assert_regexp_match(actual, expected, description)`
+asserts that `actual` matches the regexp `expected`
+
+### `assert_class_string(object, class_name, description)`
+asserts that the class string of `object` as returned in
+`Object.prototype.toString` is equal to `class_name`.
+
+### `assert_own_property(object, property_name, description)`
+assert that object has own property `property_name`
+
+### `assert_inherits(object, property_name, description)`
+assert that object does not have an own property named
+`property_name` but that `property_name` is present in the prototype
+chain for object
+
+### `assert_idl_attribute(object, attribute_name, description)`
+assert that an object that is an instance of some interface has the
+attribute attribute_name following the conditions specified by WebIDL
+
+### `assert_readonly(object, property_name, description)`
+assert that property `property_name` on object is readonly
+
+### `assert_throws(code, func, description)`
+`code` - the expected exception. This can take several forms:
+
+  * string - the thrown exception must be a DOMException with the given
+             name, e.g., "TimeoutError" (for compatibility with existing
+             tests, a constant is also supported, e.g., "TIMEOUT_ERR")
+  * object - the thrown exception must have a property called "name" that
+             matches code.name
+  * null -   allow any exception (in general, one of the options above
+             should be used)
+
+`func` - a function that should throw
+
+### `assert_unreached(description)`
+asserts if called. Used to ensure that some codepath is *not* taken e.g.
+an event does not fire.
+
+### `assert_any(assert_func, actual, expected_array, extra_arg_1, ... extra_arg_N)`
+asserts that one `assert_func(actual, expected_array_N, extra_arg1, ..., extra_arg_N)`
+  is true for some `expected_array_N` in `expected_array`. This only works for `assert_func`
+  with signature `assert_func(actual, expected, args_1, ..., args_N)`. Note that tests
+  with multiple allowed pass conditions are bad practice unless the spec specifically
+  allows multiple behaviours. Test authors should not use this method simply to hide
+  UA bugs.
+
+### `assert_exists(object, property_name, description)`
+**deprecated**
+asserts that object has an own property `property_name`
+
+### `assert_not_exists(object, property_name, description)`
+**deprecated**
+assert that object does not have own property `property_name`
+
+## Metadata ##
+
+It is possible to add optional metadata to tests; this can be done in
+one of two ways; either by adding `<meta>` elements to the head of the
+document containing the tests, or by adding the metadata to individual
+`[async_]test` calls, as properties.
diff --git a/docs/idlharness.md b/docs/idlharness.md
new file mode 100644
index 0000000..52f5900
--- /dev/null
+++ b/docs/idlharness.md
@@ -0,0 +1,118 @@
+## Introduction ##
+
+`idlharness.js` automatically generates browser tests for WebIDL interfaces, using
+the testharness.js framework.  To use, first include the following:
+
+    <script src=/resources/testharness.js></script>
+    <script src=/resources/testharnessreport.js></script>
+    <script src=/resources/WebIDLParser.js></script>
+    <script src=/resources/idlharness.js></script>
+
+Then you'll need some type of IDLs.  Here's some script that can be run on a
+spec written in HTML, which will grab all the elements with `class="idl"`,
+concatenate them, and replace the body so you can copy-paste:
+
+    var s = "";
+    [].forEach.call(document.getElementsByClassName("idl"), function(idl) {
+      //https://www.w3.org/Bugs/Public/show_bug.cgi?id=14914
+      if (!idl.classList.contains("extract"))
+      {
+        s += idl.textContent + "\n\n";
+      }
+    });
+    document.body.innerHTML = '<pre></pre>';
+    document.body.firstChild.textContent = s;
+
+Once you have that, put it in your script somehow.  The easiest way is to
+embed it literally in an HTML file with `<script type=text/plain>` or similar,
+so that you don't have to do any escaping.  Another possibility is to put it
+in a separate .idl file that's fetched via XHR or similar.  Sample usage:
+
+    var idl_array = new IdlArray();
+    idl_array.add_untested_idls("interface Node { readonly attribute DOMString nodeName; };");
+    idl_array.add_idls("interface Document : Node { readonly attribute DOMString URL; };");
+    idl_array.add_objects({Document: ["document"]});
+    idl_array.test();
+
+This tests that `window.Document` exists and meets all the requirements of
+WebIDL.  It also tests that window.document (the result of evaluating the
+string "document") has URL and nodeName properties that behave as they
+should, and otherwise meets WebIDL's requirements for an object whose
+primary interface is Document.  It does not test that window.Node exists,
+which is what you want if the Node interface is already tested in some other
+specification's suite and your specification only extends or refers to it.
+Of course, each IDL string can define many different things, and calls to
+add_objects() can register many different objects for different interfaces:
+this is a very simple example.
+
+## Public methods of IdlArray ##
+
+IdlArray objects can be obtained with `new IdlArray()`.  Anything not
+documented in this section should be considered an implementation detail,
+and outside callers should not use it.
+
+### `add_idls(idl_string)`
+  Parses `idl_string` (throwing on parse error) and adds the results to the
+  IdlArray.  All the definitions will be tested when you run test().  If
+  some of the definitions refer to other definitions, those must be present
+  too.  For instance, if `idl_string` says that `Document` inherits from `Node`,
+  the `Node` interface must also have been provided in some call to `add_idls()`
+  or `add_untested_idls()`.
+
+### `add_untested_idls(idl_string)`
+  Like `add_idls()`, but the definitions will not be tested.  If an untested
+  interface is added and then extended with a tested partial interface, the
+  members of the partial interface will still be tested.  Also, all the
+  members will still be tested for objects added with `add_objects()`, because
+  you probably want to test that (for instance) window.document has all the
+  properties from `Node`, not just `Document`, even if the `Node` interface itself
+  is tested in a different test suite.
+
+### `add_objects(dict)`
+  `dict` should be an object whose keys are the names of interfaces or
+  exceptions, and whose values are arrays of strings.  When an interface or
+  exception is tested, every string registered for it with `add_objects()`
+  will be evaluated, and tests will be run on the result to verify that it
+  correctly implements that interface or exception.  This is the only way to
+  test anything about `[NoInterfaceObject]` interfaces, and there are many
+  tests that can't be run on any interface without an object to fiddle with.
+
+  The interface has to be the *primary* interface of all the objects
+  provided.  For example, don't pass `{Node: ["document"]}`, but rather
+  `{Document: ["document"]}`.  Assuming the `Document` interface was declared to
+  inherit from `Node`, this will automatically test that document implements
+  the `Node` interface too.
+
+  Warning: methods will be called on any provided objects, in a manner that
+  WebIDL requires be safe.  For instance, if a method has mandatory
+  arguments, the test suite will try calling it with too few arguments to
+  see if it throws an exception.  If an implementation incorrectly runs the
+  function instead of throwing, this might have side effects, possibly even
+  preventing the test suite from running correctly.
+
+### `prevent_multiple_testing(name)`
+  This is a niche method for use in case you're testing many objects that
+  implement the same interfaces, and don't want to retest the same
+  interfaces every single time.  For instance, HTML defines many interfaces
+  that all inherit from `HTMLElement`, so the HTML test suite has something
+  like
+    `.add_objects({
+      HTMLHtmlElement: ['document.documentElement'],
+      HTMLHeadElement: ['document.head'],
+      HTMLBodyElement: ['document.body'],
+      ...
+    })`
+  and so on for dozens of element types.  This would mean that it would
+  retest that each and every one of those elements implements `HTMLElement`,
+  `Element`, and `Node`, which would be thousands of basically redundant tests.
+  The test suite therefore calls `prevent_multiple_testing("HTMLElement")`.
+  This means that once one object has been tested to implement `HTMLElement`
+  and its ancestors, no other object will be.  Thus in the example code
+  above, the harness would test that `document.documentElement` correctly
+  implements `HTMLHtmlElement`, `HTMLElement`, `Element`, and `Node`; but
+  `document.head` would only be tested for `HTMLHeadElement`, and so on for
+  further objects.
+
+### `test()`
+  Run all tests.  This should be called after you've called all other
+  methods to add IDLs and objects.
diff --git a/idlharness.js b/idlharness.js
index 25e1117..b8d735b 100644
--- a/idlharness.js
+++ b/idlharness.js
@@ -8,131 +8,7 @@ policies and contribution forms [3].
 [3] http://www.w3.org/2004/10/27-testcases
 */
 
-/*
- * This file automatically generates browser tests for WebIDL interfaces, using
- * the testharness.js framework.  To use, first include the following:
- *
- *   <script src=/resources/testharness.js></script>
- *   <script src=/resources/testharnessreport.js></script>
- *   <script src=/resources/WebIDLParser.js></script>
- *   <script src=/resources/idlharness.js></script>
- *
- * Then you'll need some type of IDLs.  Here's some script that can be run on a
- * spec written in HTML, which will grab all the elements with class="idl",
- * concatenate them, and replace the body so you can copy-paste:
- *
-     var s = "";
-     [].forEach.call(document.getElementsByClassName("idl"), function(idl) {
-       //https://www.w3.org/Bugs/Public/show_bug.cgi?id=14914
-       if (!idl.classList.contains("extract"))
-       {
-         s += idl.textContent + "\n\n";
-       }
-     });
-     document.body.innerHTML = '<pre></pre>';
-     document.body.firstChild.textContent = s;
- *
- * (TODO: write this in Python or something so that it can be done from the
- * command line instead.)
- *
- * Once you have that, put it in your script somehow.  The easiest way is to
- * embed it literally in an HTML file with <script type=text/plain> or similar,
- * so that you don't have to do any escaping.  Another possibility is to put it
- * in a separate .idl file that's fetched via XHR or similar.  Sample usage:
- *
- *   var idl_array = new IdlArray();
- *   idl_array.add_untested_idls("interface Node { readonly attribute DOMString nodeName; };");
- *   idl_array.add_idls("interface Document : Node { readonly attribute DOMString URL; };");
- *   idl_array.add_objects({Document: ["document"]});
- *   idl_array.test();
- *
- * This tests that window.Document exists and meets all the requirements of
- * WebIDL.  It also tests that window.document (the result of evaluating the
- * string "document") has URL and nodeName properties that behave as they
- * should, and otherwise meets WebIDL's requirements for an object whose
- * primary interface is Document.  It does not test that window.Node exists,
- * which is what you want if the Node interface is already tested in some other
- * specification's suite and your specification only extends or refers to it.
- * Of course, each IDL string can define many different things, and calls to
- * add_objects() can register many different objects for different interfaces:
- * this is a very simple example.
- *
- * TODO: Write assert_writable, assert_enumerable, assert_configurable and
- * their inverses, and use those instead of just checking
- * getOwnPropertyDescriptor.
- *
- * == Public methods of IdlArray ==
- *
- * IdlArray objects can be obtained with new IdlArray().  Anything not
- * documented in this section should be considered an implementation detail,
- * and outside callers should not use it.
- *
- * add_idls(idl_string):
- *   Parses idl_string (throwing on parse error) and adds the results to the
- *   IdlArray.  All the definitions will be tested when you run test().  If
- *   some of the definitions refer to other definitions, those must be present
- *   too.  For instance, if idl_string says that Document inherits from Node,
- *   the Node interface must also have been provided in some call to add_idls()
- *   or add_untested_idls().
- *
- * add_untested_idls(idl_string):
- *   Like add_idls(), but the definitions will not be tested.  If an untested
- *   interface is added and then extended with a tested partial interface, the
- *   members of the partial interface will still be tested.  Also, all the
- *   members will still be tested for objects added with add_objects(), because
- *   you probably want to test that (for instance) window.document has all the
- *   properties from Node, not just Document, even if the Node interface itself
- *   is tested in a different test suite.
- *
- * add_objects(dict):
- *   dict should be an object whose keys are the names of interfaces or
- *   exceptions, and whose values are arrays of strings.  When an interface or
- *   exception is tested, every string registered for it with add_objects()
- *   will be evaluated, and tests will be run on the result to verify that it
- *   correctly implements that interface or exception.  This is the only way to
- *   test anything about [NoInterfaceObject] interfaces, and there are many
- *   tests that can't be run on any interface without an object to fiddle with.
- *
- *   The interface has to be the *primary* interface of all the objects
- *   provided.  For example, don't pass {Node: ["document"]}, but rather
- *   {Document: ["document"]}.  Assuming the Document interface was declared to
- *   inherit from Node, this will automatically test that document implements
- *   the Node interface too.
- *
- *   Warning: methods will be called on any provided objects, in a manner that
- *   WebIDL requires be safe.  For instance, if a method has mandatory
- *   arguments, the test suite will try calling it with too few arguments to
- *   see if it throws an exception.  If an implementation incorrectly runs the
- *   function instead of throwing, this might have side effects, possibly even
- *   preventing the test suite from running correctly.
- *
- * prevent_multiple_testing(name):
- *   This is a niche method for use in case you're testing many objects that
- *   implement the same interfaces, and don't want to retest the same
- *   interfaces every single time.  For instance, HTML defines many interfaces
- *   that all inherit from HTMLElement, so the HTML test suite has something
- *   like
- *     .add_objects({
- *         HTMLHtmlElement: ['document.documentElement'],
- *         HTMLHeadElement: ['document.head'],
- *         HTMLBodyElement: ['document.body'],
- *         ...
- *     })
- *   and so on for dozens of element types.  This would mean that it would
- *   retest that each and every one of those elements implements HTMLElement,
- *   Element, and Node, which would be thousands of basically redundant tests.
- *   The test suite therefore calls prevent_multiple_testing("HTMLElement").
- *   This means that once one object has been tested to implement HTMLElement
- *   and its ancestors, no other object will be.  Thus in the example code
- *   above, the harness would test that document.documentElement correctly
- *   implements HTMLHtmlElement, HTMLElement, Element, and Node; but
- *   document.head would only be tested for HTMLHeadElement, and so on for
- *   further objects.
- *
- * test():
- *   Run all tests.  This should be called after you've called all other
- *   methods to add IDLs and objects.
- */
+/* For user documentation see docs/idlharness.md */
 
 /**
  * Notes for people who want to edit this file (not just use it as a library):
diff --git a/testharness.js b/testharness.js
index 753fa59..47de02d 100644
--- a/testharness.js
+++ b/testharness.js
@@ -10,422 +10,7 @@ policies and contribution forms [3].
 [3] http://www.w3.org/2004/10/27-testcases
 */
 
-/*
- * == Introduction ==
- *
- * This file provides a framework for writing testcases. It is intended to
- * provide a convenient API for making common assertions, and to work both
- * for testing synchronous and asynchronous DOM features in a way that
- * promotes clear, robust, tests.
- *
- * == Basic Usage ==
- *
- * To use this file, import the script and the testharnessreport script into
- * the test document:
-
-<!doctype html>
-<title></title>
-<script src="/resources/testharness.js"></script>
-<script src="/resources/testharnessreport.js"></script>
-
- * Within each file one may define one or more tests. Each test is atomic
- * in the sense that a single test has a single result (pass/fail/timeout).
- * Within each test one may have a number of asserts. The test fails at the
- * first failing assert, and the remainder of the test is (typically) not run.
- *
- * If the file containing the tests is a HTML file, a table containing the test
- * results will be added to the document after all tests have run. By default this
- * will be added to a div element with id=log if it exists, or a new div element
- * appended to document.body if it does not.
- *
- * NOTE: By default tests must be created before the load event fires. For ways
- *       to create tests after the load event, see "Determining when all tests
- *       are complete", below
- *
- * == Synchronous Tests ==
- *
- * To create a synchronous test use the test() function:
- *
- * test(test_function, name, properties)
- *
- * test_function is a function that contains the code to test. For example a
- * trivial passing test would be:
- *
- * test(function() {assert_true(true)}, "assert_true with true")
- *
- * The function passed in is run in the test() call.
- *
- * properties is an object that overrides default test properties. The
- * recognised properties are:
- *    timeout - the test timeout in ms
- *
- * e.g.
- * test(test_function, "Sample test", {timeout:1000})
- *
- * would run test_function with a timeout of 1s.
- *
- * Additionally, test-specific metadata can be passed in the properties. These
- * are used when the individual test has different metadata from that stored
- * in the <head>.
- * The recognized metadata properties are:
- *
- *    help - The url or an array of urls of the part(s) of the specification(s)
- *           being tested
- *
- *    assert - A human readable description of what the test is attempting
- *             to prove
- *
- *    author - Name and contact information for the author of the test in the
- *             format: "Name <email_addr>" or "Name http://contact/url"
- *
- * == Asynchronous Tests ==
- *
- * Testing asynchronous features is somewhat more complex since the result of
- * a test may depend on one or more events or other callbacks. The API provided
- * for testing these features is indended to be rather low-level but hopefully
- * applicable to many situations.
- *
- * To create a test, one starts by getting a Test object using async_test:
- *
- * async_test(name, properties)
- *
- * e.g.
- * var t = async_test("Simple async test")
- *
- * Assertions can be added to the test by calling the step method of the test
- * object with a function containing the test assertions:
- *
- * t.step(function() {assert_true(true)});
- *
- * When all the steps are complete, the done() method must be called:
- *
- * t.done();
- *
- * As a convenience, async_test can also takes a function as first argument.
- * This function is called with the test object as both its `this` object and
- * first argument. The above example can be rewritten as:
- *
- * async_test(function(t) {
- *     object.some_event = function() {
- *         t.step(function (){assert_true(true); t.done();});
- *     };
- * }, "Simple async test");
- *
- * which avoids cluttering the global scope with references to async
- * tests instances.
- *
- * The properties argument is identical to that for test().
- *
- * In many cases it is convenient to run a step in response to an event or a
- * callback. A convenient method of doing this is through the step_func method
- * which returns a function that, when called runs a test step. For example
- *
- * object.some_event = t.step_func(function(e) {assert_true(e.a)});
- *
- * For asynchronous callbacks that should never execute, unreached_func can
- * be used. For example:
- *
- * object.some_event = t.unreached_func("some_event should not fire");
- *
- * == Single Page Tests ==
- *
- * Sometimes, particularly when dealing with asynchronous behaviour,
- * having exactly one test per page is desirable, and the overhead of
- * wrapping everything in functions for isolation becomes
- * burdensome. For these cases testharness.js support "single page
- * tests".
- *
- * In order for a test to be interpreted as a "single page" test, the
- * it must simply not call test() or async_test() anywhere on the page, and
- * must call the done() function to indicate that the test is complete. All
- * the assert_* functions are avaliable as normal, but are called without
- * the normal step function wrapper. For example:
- *
- * <!doctype html>
- * <title>Example single-page test</title>
- * <script src="/resources/testharness.js"></script>
- * <script src="/resources/testharnessreport.js"></script>
- * <body>
- *   <script>
- *     assert_equals(document.body, document.getElementsByTagName("body")[0])
- *     done()
- *  </script>
- *
- * The test title for sinple page tests is always taken from document.title.
- *
- * == Making assertions ==
- *
- * Functions for making assertions start assert_
- * The best way to get a list is to look in this file for functions names
- * matching that pattern. The general signature is
- *
- * assert_something(actual, expected, description)
- *
- * although not all assertions precisely match this pattern e.g. assert_true
- * only takes actual and description as arguments.
- *
- * The description parameter is used to present more useful error messages when
- * a test fails
- *
- * NOTE: All asserts must be located in a test() or a step of an async_test().
- *       asserts outside these places won't be detected correctly by the harness
- *       and may cause a file to stop testing.
- *
- * == Cleanup ==
- *
- * Occasionally tests may create state that will persist beyond the test itself.
- * In order to ensure that tests are independent, such state should be cleaned
- * up once the test has a result. This can be achieved by adding cleanup
- * callbacks to the test. Such callbacks are registered using the add_cleanup
- * function on the test object. All registered callbacks will be run as soon as
- * the test result is known. For example
- * test(function() {
- *          window.some_global = "example";
- *          this.add_cleanup(function() {delete window.some_global});
- *          assert_true(false);
- *      });
- *
- * == Harness Timeout ==
- *
- * The overall harness admits two timeout values "normal" (the
- * default) and "long", used for tests which have an unusually long
- * runtime. After the timeout is reached, the harness will stop
- * waiting for further async tests to complete. By default the
- * timeouts are set to 10s and 60s, respectively, but may be changed
- * when the test is run on hardware with different performance
- * characteristics to a common desktop computer.  In order to opt-in
- * to the longer test timeout, the test must specify a meta element:
- * <meta name="timeout" content="long">
- *
- * Occasionally tests may have a race between the harness timing out and
- * a particular test failing; typically when the test waits for some event
- * that never occurs. In this case it is possible to use test.force_timeout()
- * in place of assert_unreached(), to immediately fail the test but with a
- * status of "timeout". This should only be used as a last resort when it is
- * not possible to make the test reliable in some other way.
- *
- * == Setup ==
- *
- * Sometimes tests require non-trivial setup that may fail. For this purpose
- * there is a setup() function, that may be called with one or two arguments.
- * The two argument version is:
- *
- * setup(func, properties)
- *
- * The one argument versions may omit either argument.
- * func is a function to be run synchronously. setup() becomes a no-op once
- * any tests have returned results. Properties are global properties of the test
- * harness. Currently recognised properties are:
- *
- *
- * explicit_done - Wait for an explicit call to done() before declaring all
- *                 tests complete (see below; implicitly true for single page
- *                 tests)
- *
- * output_document - The document to which results should be logged. By default
- *                   this is the current document but could be an ancestor
- *                   document in some cases e.g. a SVG test loaded in an HTML
- *                   wrapper
- *
- * explicit_timeout - disable file timeout; only stop waiting for results
- *                    when the timeout() function is called (typically for
- *                    use when integrating with some existing test framework
- *                    that has its own timeout mechanism).
- *
- * allow_uncaught_exception - don't treat an uncaught exception as an error;
- *                            needed when e.g. testing the window.onerror
- *                            handler.
- *
- * timeout_multiplier - Multiplier to apply to per-test timeouts.
- *
- * == Determining when all tests are complete ==
- *
- * By default the test harness will assume there are no more results to come
- * when:
- * 1) There are no Test objects that have been created but not completed
- * 2) The load event on the document has fired
- *
- * This behaviour can be overridden by setting the explicit_done property to
- * true in a call to setup(). If explicit_done is true, the test harness will
- * not assume it is done until the global done() function is called. Once done()
- * is called, the two conditions above apply like normal.
- *
- * == Generating tests ==
- *
- * NOTE: this functionality may be removed
- *
- * There are scenarios in which is is desirable to create a large number of
- * (synchronous) tests that are internally similar but vary in the parameters
- * used. To make this easier, the generate_tests function allows a single
- * function to be called with each set of parameters in a list:
- *
- * generate_tests(test_function, parameter_lists, properties)
- *
- * For example:
- *
- * generate_tests(assert_equals, [
- *     ["Sum one and one", 1+1, 2],
- *     ["Sum one and zero", 1+0, 1]
- *     ])
- *
- * Is equivalent to:
- *
- * test(function() {assert_equals(1+1, 2)}, "Sum one and one")
- * test(function() {assert_equals(1+0, 1)}, "Sum one and zero")
- *
- * Note that the first item in each parameter list corresponds to the name of
- * the test.
- *
- * The properties argument is identical to that for test(). This may be a
- * single object (used for all generated tests) or an array.
- *
- * == Callback API ==
- *
- * The framework provides callbacks corresponding to 3 events:
- *
- * start - happens when the first Test is created
- * result - happens when a test result is recieved
- * complete - happens when all results are recieved
- *
- * The page defining the tests may add callbacks for these events by calling
- * the following methods:
- *
- *   add_start_callback(callback) - callback called with no arguments
- *   add_result_callback(callback) - callback called with a test argument
- *   add_completion_callback(callback) - callback called with an array of tests
- *                                       and an status object
- *
- * tests have the following properties:
- *   status: A status code. This can be compared to the PASS, FAIL, TIMEOUT and
- *           NOTRUN properties on the test object
- *   message: A message indicating the reason for failure. In the future this
- *            will always be a string
- *
- *  The status object gives the overall status of the harness. It has the
- *  following properties:
- *    status: Can be compared to the OK, ERROR and TIMEOUT properties
- *    message: An error message set when the status is ERROR
- *
- * == External API ==
- *
- * In order to collect the results of multiple pages containing tests, the test
- * harness will, when loaded in a nested browsing context, attempt to call
- * certain functions in each ancestor and opener browsing context:
- *
- * start - start_callback
- * result - result_callback
- * complete - completion_callback
- *
- * These are given the same arguments as the corresponding internal callbacks
- * described above.
- *
- * == External API through cross-document messaging ==
- *
- * Where supported, the test harness will also send messages using
- * cross-document messaging to each ancestor and opener browsing context. Since
- * it uses the wildcard keyword (*), cross-origin communication is enabled and
- * script on different origins can collect the results.
- *
- * This API follows similar conventions as those described above only slightly
- * modified to accommodate message event API. Each message is sent by the harness
- * is passed a single vanilla object, available as the `data` property of the
- * event object. These objects are structures as follows:
- *
- * start - { type: "start" }
- * result - { type: "result", test: Test }
- * complete - { type: "complete", tests: [Test, ...], status: TestsStatus }
- *
- * == List of assertions ==
- *
- * assert_true(actual, description)
- *   asserts that /actual/ is strictly true
- *
- * assert_false(actual, description)
- *   asserts that /actual/ is strictly false
- *
- * assert_equals(actual, expected, description)
- *   asserts that /actual/ is the same value as /expected/
- *
- * assert_not_equals(actual, expected, description)
- *   asserts that /actual/ is a different value to /expected/. Yes, this means
- *   that "expected" is a misnomer
- *
- * assert_in_array(actual, expected, description)
- *   asserts that /expected/ is an Array, and /actual/ is equal to one of the
- *   members -- expected.indexOf(actual) != -1
- *
- * assert_array_equals(actual, expected, description)
- *   asserts that /actual/ and /expected/ have the same length and the value of
- *   each indexed property in /actual/ is the strictly equal to the corresponding
- *   property value in /expected/
- *
- * assert_approx_equals(actual, expected, epsilon, description)
- *   asserts that /actual/ is a number within +/- /epsilon/ of /expected/
- *
- * assert_less_than(actual, expected, description)
- *   asserts that /actual/ is a number less than /expected/
- *
- * assert_greater_than(actual, expected, description)
- *   asserts that /actual/ is a number greater than /expected/
- *
- * assert_less_than_equal(actual, expected, description)
- *   asserts that /actual/ is a number less than or equal to /expected/
- *
- * assert_greater_than_equal(actual, expected, description)
- *   asserts that /actual/ is a number greater than or equal to /expected/
- *
- * assert_regexp_match(actual, expected, description)
- *   asserts that /actual/ matches the regexp /expected/
- *
- * assert_class_string(object, class_name, description)
- *   asserts that the class string of /object/ as returned in
- *   Object.prototype.toString is equal to /class_name/.
- *
- * assert_own_property(object, property_name, description)
- *   assert that object has own property property_name
- *
- * assert_inherits(object, property_name, description)
- *   assert that object does not have an own property named property_name
- *   but that property_name is present in the prototype chain for object
- *
- * assert_idl_attribute(object, attribute_name, description)
- *   assert that an object that is an instance of some interface has the
- *   attribute attribute_name following the conditions specified by WebIDL
- *
- * assert_readonly(object, property_name, description)
- *   assert that property property_name on object is readonly
- *
- * assert_throws(code, func, description)
- *   code - the expected exception:
- *     o string: the thrown exception must be a DOMException with the given
- *               name, e.g., "TimeoutError" (for compatibility with existing
- *               tests, a constant is also supported, e.g., "TIMEOUT_ERR")
- *     o object: the thrown exception must have a property called "name" that
- *               matches code.name
- *     o null:   allow any exception (in general, one of the options above
- *               should be used)
- *   func - a function that should throw
- *
- * assert_unreached(description)
- *   asserts if called. Used to ensure that some codepath is *not* taken e.g.
- *   an event does not fire.
- *
- * assert_any(assert_func, actual, expected_array, extra_arg_1, ... extra_arg_N)
- *   asserts that one assert_func(actual, expected_array_N, extra_arg1, ..., extra_arg_N)
- *   is true for some expected_array_N in expected_array. This only works for assert_func
- *   with signature assert_func(actual, expected, args_1, ..., args_N). Note that tests
- *   with multiple allowed pass conditions are bad practice unless the spec specifically
- *   allows multiple behaviours. Test authors should not use this method simply to hide
- *   UA bugs.
- *
- * assert_exists(object, property_name, description)
- *   *** deprecated ***
- *   asserts that object has an own property property_name
- *
- * assert_not_exists(object, property_name, description)
- *   *** deprecated ***
- *   assert that object does not have own property property_name
- */
+/* Documentation is in docs/testharness.md */
 
 (function ()
 {