From db59eed031721bfb5d39da79746d736c8911b590 Mon Sep 17 00:00:00 2001
From: James Graham <james@hoppipolla.co.uk>
Date: Tue, 24 Feb 2015 11:57:46 +0000
Subject: [PATCH] Add test_on and test_onload convenience functions.

---
 apisample.htm  |  8 ++++++++
 docs/api.md    | 14 ++++++++++++++
 testharness.js | 17 +++++++++++++++++
 3 files changed, 39 insertions(+)

diff --git a/apisample.htm b/apisample.htm
index 6eb3279..a598e5c 100644
--- a/apisample.htm
+++ b/apisample.htm
@@ -29,6 +29,14 @@ <h1>Sample HTML5 API Tests</h1>
     var load_test_attr = async_test("body element fires the onload event set from the attribute");
 </script>
 <script>
+    test_on(function(e) {
+                assert_equals(e.type, "DOMContentLoaded");
+            }, window, "DOMContentLoaded", "test_on test for window DOMContentLoaded event");
+
+    test_onload(function () {
+                    assert_true(true)
+                }, "test_onload test");
+
     function bodyElement()
     {
         assert_equals(document.body, document.getElementsByTagName("body")[0]);
diff --git a/docs/api.md b/docs/api.md
index 788b2e0..d4499b1 100644
--- a/docs/api.md
+++ b/docs/api.md
@@ -88,12 +88,26 @@ tests instances.
 
 The properties argument is identical to that for `test()`.
 
+## Testing with Events ##
+
 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 the special case of a test that has a single step run in reponse
+to some event, the convenience function `test_on` can be used, for
+example:
+
+    test_on(function(e) {assert_equals(e.type, "DOMContentLoaded")},
+            window, "DOMcontentLoaded");
+
+The most common case of all is running a test after the document has
+fully loaded; this can be achieved using `test_onload`:
+
+    test_onload(function() {assert_equals(window.readyState, "complete")})
+
 For asynchronous callbacks that should never execute, `unreached_func` can
 be used. For example:
 
diff --git a/testharness.js b/testharness.js
index a31ca7d..d46b2f9 100644
--- a/testharness.js
+++ b/testharness.js
@@ -447,6 +447,21 @@ policies and contribution forms [3].
         return test_obj;
     }
 
+    function test_on(func, obj, event, name, properties) {
+        var t = async_test(name, properties);
+        obj.addEventListener(event, function f(e) {
+            t.add_cleanup(function() {obj.removeEventListener(f)});
+            t.step(function() {
+                func.call(t, e);
+            });
+            t.done();
+        });
+    }
+
+    function test_onload(func, name, properties) {
+        test_on(func, window, "load", name, properties);
+    }
+
     function promise_test(func, name, properties) {
         var test = async_test(name, properties);
         Promise.resolve(test.step(func, test, test))
@@ -516,6 +531,8 @@ policies and contribution forms [3].
 
     expose(test, 'test');
     expose(async_test, 'async_test');
+    expose(test_on, 'test_on');
+    expose(test_onload, 'test_onload');
     expose(promise_test, 'promise_test');
     expose(promise_rejects, 'promise_rejects');
     expose(generate_tests, 'generate_tests');