Change ControlFlow.wait() to accept promises

This makes it possible to block the control flow on the resolution of an
arbitrary promise (with optional timeout).

Fixes issue 8448.

Author: jleyba

javascript/node/selenium-webdriver/CHANGES.md

@@ -53,6 +53,8 @@
     `promise.ControlFlow#clearHistory`, and `promise.ControlFlow#annotateError`.
     These functions were all intended for internal use and are no longer
     necessary, so they have been made no-ops.
+* `WebDriver.wait()` may now be used to wait for a promise to resolve, with
+    an optional timeout. Refer to the API documentation for more information.
 * FIXED: 8380: `firefox.Driver` will delete its temporary profile on `quit`.
 * FIXED: 8306: Stack overflow in promise callbacks eliminated.
 * FIXED: 8221: Added support for defining custom command mappings. Includes

javascript/webdriver/promise.js

@@ -1533,17 +1533,63 @@ promise.ControlFlow.prototype.timeout = function(ms, opt_description) {
  * <p>If the condition function throws, or returns a rejected promise, the
  * wait task will fail.
  *
- * @param {function(): T} condition The condition function to poll.
- * @param {number} timeout How long to wait, in milliseconds, for the condition
- *     to hold before timing out.
+ * <p>If the condition is defined as a promise, the flow will block on that
+ * promise's resolution, up to {@code timeout} milliseconds. If
+ * {@code timeout === 0}, the flow will block indefinitely on the promise's
+ * resolution.
+ *
+ * @param {(!promise.Promise<T>|function())} condition The condition to poll,
+ *     or a promise to wait on.
+ * @param {number=} opt_timeout How long to wait, in milliseconds, for the
+ *     condition to hold before timing out; defaults to 0.
  * @param {string=} opt_message An optional error message to include if the
  *     wait times out; defaults to the empty string.
  * @return {!promise.Promise<T>} A promise that will be fulfilled
  *     when the condition has been satisified. The promise shall be rejected if
  *     the wait times out waiting for the condition.
+ * @throws {TypeError} If condition is not a function or promise or if timeout
+ *     is not a number >= 0.
  * @template T
  */
-promise.ControlFlow.prototype.wait = function(condition, timeout, opt_message) {
+promise.ControlFlow.prototype.wait = function(
+    condition, opt_timeout, opt_message) {
+  var timeout = opt_timeout || 0;
+  if (!goog.isNumber(timeout) || timeout < 0) {
+    throw TypeError('timeout must be a number >= 0: ' + timeout);
+  }
+
+  if (promise.isPromise(condition)) {
+    return this.execute(function() {
+      if (!timeout) {
+        return condition;
+      }
+      return new promise.Promise(function(fulfill, reject) {
+        var start = goog.now();
+        var timer = setTimeout(function() {
+          timer = null;
+          reject(Error((opt_message ? opt_message + '\n' : '') +
+              'Timed out waiting for promise to resolve after ' +
+              (goog.now() - start) + 'ms'));
+        }, timeout);
+
+        /** @type {Thenable} */(condition).then(
+            function(value) {
+              timer && clearTimeout(timer);
+              fulfill(value);
+            },
+            function(error) {
+              timer && clearTimeout(timer);
+              reject(error);
+            });
+      });
+    }, opt_message || '<anonymous wait: promise resolution>');
+  }
+
+  if (!goog.isFunction(condition)) {
+    throw TypeError('Invalid condition; must be a function or promise: ' +
+        goog.typeOf(condition));
+  }
+
   if (promise.isGenerator(condition)) {
     condition = goog.partial(promise.consume, condition);
   }
@@ -1557,7 +1603,7 @@ promise.ControlFlow.prototype.wait = function(condition, timeout, opt_message) {
 
       function pollCondition() {
         self.resume_();
-        self.execute(condition).then(function(value) {
+        self.execute(/**@type {function()}*/(condition)).then(function(value) {
           var elapsed = goog.now() - startTime;
           if (!!value) {
             fulfill(value);
@@ -1584,6 +1630,7 @@ promise.ControlFlow.prototype.wait = function(condition, timeout, opt_message) {
  * @param {!promise.Promise} promise The promise to wait on.
  * @return {!promise.Promise} A promise that will resolve when the
  *     task has completed.
+ * @deprecated Use {@link #wait() wait(promise)} instead.
  */
 promise.ControlFlow.prototype.await = function(promise) {
   return this.execute(function() {

javascript/webdriver/test/promise_flow_test.js

@@ -1149,7 +1149,53 @@ function testWaiting_scheduleWithIntermittentAndNestedWaits() {
         '0: wait 4');
   });
 }
-  
+
+
+function testWait_requiresConditionToBeAPromiseOrFunction() {
+  assertThrows(function() {
+    flow.wait(1234, 0);
+  });
+  flow.wait(function() { return true;}, 0);
+  flow.wait(webdriver.promise.fulfilled(), 0);
+  return waitForIdle();
+}
+
+
+function testWait_promiseThatDoesNotResolveBeforeTimeout() {
+  var d = webdriver.promise.defer();
+  flow.wait(d.promise, 5).then(fail, function(e) {
+    assertRegExp(/Timed out waiting for promise to resolve after \d+ms/,
+        e.message);
+  });
+  return waitForIdle().then(function() {
+    assertTrue('Promise should not be cancelled', d.promise.isPending());
+  });
+}
+
+
+function testWait_unboundedWaitOnPromiseResolution() {
+  var messages = [];
+  var d = webdriver.promise.defer();
+  var waitResult = flow.wait(d.promise).then(function(value) {
+    messages.push('b');
+    assertEquals(1234, value);
+  });
+  setTimeout(function() {
+    messages.push('a');
+  }, 5);
+
+  webdriver.promise.delayed(10).then(function() {
+    assertArrayEquals(['a'], messages);
+    assertTrue(waitResult.isPending());
+    d.fulfill(1234);
+    return waitResult;
+  }).then(function(value) {
+    assertArrayEquals(['a', 'b'], messages);
+  });
+
+  return waitForIdle();
+}
+
 
 function testSubtasks() {
   schedule('a');
@@ -1333,6 +1379,7 @@ function testEventLoopWaitsOnPendingPromiseRejections_multipleRejections() {
           }
         });
   }).then(function() {
+    seen.sort();
     assertArrayEquals([once, twice], seen);
     assertFlowHistory('one');
     assertFalse('Did not cancel the second task', twoResult.isPending());

javascript/webdriver/webdriver.js

@@ -624,28 +624,59 @@ webdriver.WebDriver.prototype.call = function(fn, opt_scope, var_args) {
 
 
 /**
- * Schedules a command to wait for a condition to hold, as defined by some
- * user supplied function. If any errors occur while evaluating the wait, they
- * will be allowed to propagate.
+ * Schedules a command to wait for a condition to hold. The condition may be
+ * specified by a {@link webdriver.until.Condition}, as a custom function, or
+ * as a {@link webdriver.promise.Promise}.
  *
- * <p>In the event a condition returns a {@link webdriver.promise.Promise}, the
+ * For a {@link webdriver.until.Condition} or function, the wait will repeatedly
+ * evaluate the condition until it returns a truthy value. If any errors occur
+ * while evaluating the condition, they will be allowed to propagate. In the
+ * event a condition returns a {@link webdriver.promise.Promise promise}, the
  * polling loop will wait for it to be resolved and use the resolved value for
- * evaluating whether the condition has been satisfied. The resolution time for
+ * whether the condition has been satisified. Note the resolution time for
  * a promise is factored into whether a wait has timed out.
  *
- * @param {!(webdriver.until.Condition.<T>|
- *           function(!webdriver.WebDriver): T)} condition Either a condition
- *     object, or a function to evaluate as a condition.
- * @param {number} timeout How long to wait for the condition to be true.
+ * *Example:* waiting up to 10 seconds for an element to be present and visible
+ * on the page.
+ *
+ *     var button = driver.wait(until.elementLocated(By.id('foo'), 10000);
+ *     button.click();
+ *
+ * This function may also be used to block the command flow on the resolution
+ * of a {@link webdriver.promise.Promise promise}. When given a promise, the
+ * command will simply wait for its resolution before completing. A timeout may
+ * be provided to fail the command if the promise does not resolve before the
+ * timeout expires.
+ *
+ * *Example:* Suppose you have a function, `startTestServer`, that returns a
+ * promise for when a server is ready for requests. You can block a `WebDriver`
+ * client on this promise with:
+ *
+ *     var started = startTestServer();
+ *     driver.wait(started, 5 * 1000, 'Server should start within 5 seconds');
+ *     driver.get(getServerUrl());
+ *
+ * @param {!(webdriver.promise.Promise<T>|
+ *           webdriver.until.Condition<T>|
+ *           function(!webdriver.WebDriver): T)} condition The condition to
+ *     wait on, defined as a promise, condition object, or  a function to
+ *     evaluate as a condition.
+ * @param {number=} opt_timeout How long to wait for the condition to be true.
  * @param {string=} opt_message An optional message to use if the wait times
  *     out.
- * @return {!webdriver.promise.Promise.<T>} A promise that will be fulfilled
+ * @return {!webdriver.promise.Promise<T>} A promise that will be fulfilled
  *     with the first truthy value returned by the condition function, or
  *     rejected if the condition times out.
  * @template T
  */
 webdriver.WebDriver.prototype.wait = function(
-    condition, timeout, opt_message) {
+    condition, opt_timeout, opt_message) {
+  if (webdriver.promise.isPromise(condition)) {
+    return this.flow_.wait(
+        /** @type {!webdriver.promise.Promise<T>} */(condition),
+        opt_timeout, opt_message);
+  }
+
   var message = opt_message;
   var fn = /** @type {!Function} */(condition);
   if (condition instanceof webdriver.until.Condition) {
@@ -659,7 +690,7 @@ webdriver.WebDriver.prototype.wait = function(
       return webdriver.promise.consume(fn, null, [driver]);
     }
     return fn(driver);
-  }, timeout, message);
+  }, opt_timeout, message);
 };