Bug 1473614 - Add sync function Sleep for pausing async functions. r=automatedtester

This adds a new public API to the Marionette sync module that can
"pause" async functions for an arbitrary amount of hardcoded time.
This can be useful for debugging purposes.

testing/marionette/sync.js

@@ -18,6 +18,7 @@ XPCOMUtils.defineLazyGetter(this, "logger", Log.get);
 this.EXPORTED_SYMBOLS = [
   /* exported PollPromise, TimedPromise */
   "PollPromise",
+  "Sleep",
   "TimedPromise",
 
   /* exported MessageManagerDestroyedPromise */
@@ -207,6 +208,27 @@ function TimedPromise(fn, {timeout = 1500, throws = TimeoutError} = {}) {
   });
 }
 
+/**
+ * Pauses for the given duration.
+ *
+ * @param {number} timeout
+ *     Duration to wait before fulfilling promise in milliseconds.
+ *
+ * @return {Promise}
+ *     Promise that fulfills when the `timeout` is elapsed.
+ *
+ * @throws {TypeError}
+ *     If `timeout` is not a number.
+ * @throws {RangeError}
+ *     If `timeout` is not an unsigned integer.
+ */
+function Sleep(timeout) {
+  if (typeof timeout != "number") {
+    throw new TypeError();
+  }
+  return new TimedPromise(() => {}, {timeout, throws: null});
+}
+
 /**
  * Detects when the specified message manager has been destroyed.
  *

testing/marionette/test/unit/test_sync.js

@@ -4,6 +4,7 @@
 
 const {
   PollPromise,
+  Sleep,
   TimedPromise,
 } = ChromeUtils.import("chrome://marionette/content/sync.js", {});
 
@@ -131,3 +132,12 @@ add_test(function test_TimedPromise_timeoutTypes() {
 
   run_next_test();
 });
+
+add_task(async function test_Sleep() {
+  await Sleep(0);
+  for (let type of ["foo", true, null, undefined]) {
+    Assert.throws(() => Sleep(type), /TypeError/);
+  }
+  Assert.throws(() => Sleep(1.2), /RangeError/);
+  Assert.throws(() => Sleep(-1), /RangeError/);
+});