Add test_on and test_onload convenience functions.

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]);

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:
 

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');