From fd3d4b8a6f24d51f018d6912f60997cad4dfccc7 Mon Sep 17 00:00:00 2001
From: James Graham <james@hoppipolla.co.uk>
Date: Fri, 8 May 2015 17:52:50 +0100
Subject: [PATCH] fixup! Add after_timeout function

---
 docs/api.md    | 27 +++++++++++++++++++++++++++
 testharness.js | 12 ++++++++++--
 2 files changed, 37 insertions(+), 2 deletions(-)

diff --git a/docs/api.md b/docs/api.md
index 78c00a9..1e4fd32 100644
--- a/docs/api.md
+++ b/docs/api.md
@@ -243,6 +243,33 @@ the test result is known. For example
              assert_true(false);
          });
 
+## Timeouts in Tests ##
+
+In general the use of timeouts in tests is discouraged because this is
+an observed source of instability in real tests when run on CI
+infrastructure. In particular if a test should fail when something
+doesn't happen it is good practice to simply let the test run to the
+full timeout rather than trying to guess an appropriate shorter
+timeout to use.
+
+In other cases it may be necessary to use a timeout (e.g. for a test
+that only passes if some event is *not* fired. In this case it is
+*not* permitted to use the standard `setTimeout` function. Instead one
+must use the `step_timeout` function:
+
+    var t = async_test("Some test that does something after a timeout");
+
+    t.step_timeout(function() {assert_true(true); this.done()}, 2000);
+
+The difference between `setTimeout` and `step_timeout` is that the
+latter takes account of the timeout multiplier when computing the
+delay e.g. in the above case a timeout multiplier of 2 would cause a
+pause of 4000ms before calling the callback. This makes it less likely
+to produce unstable results in slow configurations.
+
+For single-page tests, `step_timeout` is also available as a global
+function.
+
 ## Harness Timeout ##
 
 The overall harness admits two timeout values `"normal"` (the
diff --git a/testharness.js b/testharness.js
index c6298d8..9edf118 100644
--- a/testharness.js
+++ b/testharness.js
@@ -603,7 +603,7 @@ policies and contribution forms [3].
         object.addEventListener(event, callback, false);
     }
 
-    function after_timeout(f, t) {
+    function step_timeout(f, t) {
         return setTimeout(f, t * tests.timeout_multiplier);
     }
 
@@ -615,7 +615,7 @@ policies and contribution forms [3].
     expose(setup, 'setup');
     expose(done, 'done');
     expose(on_event, 'on_event');
-    expose(after_timeout, 'after_timeout');
+    expose(step_timeout, 'step_timeout');
 
     /*
      * Return a string truncated to the given length, with ... added at the end
@@ -1372,6 +1372,14 @@ policies and contribution forms [3].
         });
     };
 
+    Test.prototype.step_timeout = function(f, timeout) {
+        var test_this = this;
+
+        return setTimeout(this.step_func(function() {
+            return f.call(test_this);
+        }, timeout * tests.timeout_multiplier));
+    }
+
     Test.prototype.add_cleanup = function(callback) {
         this.cleanup_callbacks.push(callback);
     };