Add doc and sample for fetch_tests_from_window.

sfuqua · jgraham · commit a5802df60175 · 2017-03-13T14:44:07.000Z
diff --git a/docs/api.md b/docs/api.md
@@ -522,6 +522,19 @@ object. These objects are structured as follows:
  * result - `{ type: "result", test: Test }`
  * complete - `{ type: "complete", tests: [Test, ...], status: TestsStatus }`
 
+## Consolidating tests from other documents ##
+
+If it is desirable to coalesce multiple test suites running in separate
+documents into one primary test document, that is possible through
+`fetch_tests_from_window`. The argument to `fetch_tests_from_window` is any [`Window`](https://html.spec.whatwg.org/multipage/browsers.html#the-window-object)
+capable of accessing the browsing context as either an ancestor or opener.
+
+This can be used, for example, to pull in tests from a child that was created
+with `window.open`, or in a frame, such that all tests are ultimately reported
+in the same document. The current test suite will not report completion until
+all fetched tests are complete, and errors in the child contexts will result in
+failures for the suite in the current context.
+
 ## Web Workers ##
 
 The `testharness.js` script can be used from within [dedicated workers, shared
diff --git a/examples/apisample18.html b/examples/apisample18.html
@@ -0,0 +1,26 @@
+<!DOCTYPE HTML>
+<html>
+<head>
+<title>Example with iframe that consolidates tests via fetch_tests_from_window</title>
+<script src="../testharness.js"></script>
+<script src="../testharnessreport.js"></script>
+<script>
+var parent_test = async_test("Test executing in parent context");
+</script>
+</head>
+<body onload="parent_test.done()">
+<h1>Fetching Tests From a Child Context</h1>
+<p>This test demonstrates the use of <tt>fetch_tests_from_window</tt> to pull
+tests from an <tt>iframe</tt> into the primary document.</p>
+<p>The test suite is expected to fail due to an unhandled exception in the
+child context.</p>
+<div id="log"></div>
+
+<iframe id="childContext" src="apisample4.htm" style="display:none"></iframe>
+<!-- apisample4 is a failing suite due to an unhandled Error. -->
+
+<script>
+	var childContext = document.getElementById("childContext");
+	fetch_tests_from_window(childContext.contentWindow);
+</script>
+</body>
diff --git a/testharness.js b/testharness.js
@@ -1614,7 +1614,10 @@ policies and contribution forms [3].
                 stack: error.stack
             }
         });
-        error.preventDefault();
+
+        if (error.preventDefault) {
+            error.preventDefault();
+        }
     };
 
     RemoteContext.prototype.test_state = function(data) {

-Original file line number
+Diff line change
@@ @@ -0,0 +1,26 @@ @@
 +>
 +<html>
 +<head>
 +<title>Example with iframe that consolidates tests via fetch_tests_from_windowtitle>
 +<script src="../testharness.js">script>
 +<script src="../testharnessreport.js">script>
 +<script>
 +var parent_test = async_test("Test executing in parent context");
 +script>
 +head>
 +<body onload="parent_test.done()">
 +<h1>Fetching Tests From a Child Contexth1>
 +<p>This test demonstrates the use of <tt>fetch_tests_from_windowtt> to pull
 +tests from an <tt>iframett> into the primary document.p>
 +<p>The test suite is expected to fail due to an unhandled exception in the
 +child context.p>
 +<div id="log">div>
++
 +<iframe id="childContext" src="apisample4.htm" style="display:none">iframe>
++
++
 +<script>
 +	var childContext = document.getElementById("childContext");
 +	fetch_tests_from_window(childContext.contentWindow);
 +script>
 +body>