selenium-webdriver 3.0.0 → 3.0.1

package/CHANGES.md

@@ -1,3 +1,16 @@
+## v3.0.1
+
+* More API adjustments to align with native Promises
+  - Deprecated `promise.fulfilled(value)`, use `promise.Promise#resolve(value)`
+  - Deprecated `promise.rejected(reason)`, use `promise.Promise#reject(reason)`
+* When a `wait()` condition times out, the returned promise will now be
+  rejected with an `error.TimeoutError` instead of a generic `Error` object.
+* `WebDriver#wait()` will now throw a TypeError if an invalid wait condition is
+  provided.
+* Properly catch unhandled promise rejections with an action sequence (only
+  impacts when the promise manager is disabled).
+
+
 ## v3.0.0
 
 * (__NOTICE__) The minimum supported version of Node is now 6.9.0 LTS

package/lib/actions.js

@@ -120,9 +120,10 @@ class ActionSequence {
     let actions = this.actions_.concat();
     let driver = this.driver_;
     return driver.controlFlow().execute(function() {
-      actions.forEach(function(action) {
-        driver.schedule(action.command, action.description);
+      let results = actions.map(action => {
+        return driver.schedule(action.command, action.description);
       });
+      return Promise.all(results);
     }, 'ActionSequence.perform');
   }
 
@@ -431,9 +432,10 @@ class TouchSequence {
     let actions = this.actions_.concat();
     let driver = this.driver_;
     return driver.controlFlow().execute(function() {
-      actions.forEach(function(action) {
-        driver.schedule(action.command, action.description);
+      let results = actions.map(action => {
+        return driver.schedule(action.command, action.description);
       });
+      return Promise.all(results);
     }, 'TouchSequence.perform');
   }
 

package/lib/promise.js

@@ -628,6 +628,7 @@
 
 'use strict';
 
+const error = require('./error');
 const events = require('./events');
 const logging = require('./logging');
 
@@ -1073,6 +1074,30 @@ class ManagedPromise {
     }
   }
 
+  /**
+   * Creates a promise that is immediately resolved with the given value.
+   *
+   * @param {T=} opt_value The value to resolve.
+   * @return {!ManagedPromise<T>} A promise resolved with the given value.
+   * @template T
+   */
+  static resolve(opt_value) {
+    if (opt_value instanceof ManagedPromise) {
+      return opt_value;
+    }
+    return new ManagedPromise(resolve => resolve(opt_value));
+  }
+
+  /**
+   * Creates a promise that is immediately rejected with the given reason.
+   *
+   * @param {*=} opt_reason The rejection reason.
+   * @return {!ManagedPromise<?>} A new rejected promise.
+   */
+  static reject(opt_reason) {
+    return new ManagedPromise((_, reject) => reject(opt_reason));
+  }
+
   /** @override */
   toString() {
     return 'ManagedPromise::' + getUid(this) +
@@ -1475,15 +1500,11 @@ function defer() {
  * Creates a promise that has been resolved with the given value.
  * @param {T=} opt_value The resolved value.
  * @return {!ManagedPromise<T>} The resolved promise.
+ * @deprecated Use {@link ManagedPromise#resolve Promise.resolve(value)}.
  * @template T
  */
 function fulfilled(opt_value) {
-  if (opt_value instanceof ManagedPromise) {
-    return opt_value;
-  }
-  return new ManagedPromise(function(fulfill) {
-    fulfill(opt_value);
-  });
+  return ManagedPromise.resolve(opt_value);
 }
 
 
@@ -1491,16 +1512,11 @@ function fulfilled(opt_value) {
  * Creates a promise that has been rejected with the given reason.
  * @param {*=} opt_reason The rejection reason; may be any value, but is
  *     usually an Error or a string.
- * @return {!ManagedPromise<T>} The rejected promise.
- * @template T
+ * @return {!ManagedPromise<?>} The rejected promise.
+ * @deprecated Use {@link ManagedPromise#reject Promise.reject(reason)}.
  */
 function rejected(opt_reason) {
-  if (opt_reason instanceof ManagedPromise) {
-    return opt_reason;
-  }
-  return new ManagedPromise(function(_, reject) {
-    reject(opt_reason);
-  });
+  return ManagedPromise.reject(opt_reason);
 }
 
 
@@ -2045,9 +2061,11 @@ function scheduleWait(scheduler, condition, opt_timeout, opt_message) {
         let start = Date.now();
         let timer = setTimeout(function() {
           timer = null;
-          reject(Error((opt_message ? opt_message + '\n' : '') +
-                       'Timed out waiting for promise to resolve after ' +
-                       (Date.now() - start) + 'ms'));
+          reject(
+              new error.TimeoutError(
+                  (opt_message ? opt_message + '\n' : '')
+                      + 'Timed out waiting for promise to resolve after '
+                      + (Date.now() - start) + 'ms'));
         }, timeout);
 
         /** @type {Thenable} */(condition).then(
@@ -2085,8 +2103,10 @@ function scheduleWait(scheduler, condition, opt_timeout, opt_message) {
           if (!!value) {
             fulfill(value);
           } else if (timeout && elapsed >= timeout) {
-            reject(new Error((opt_message ? opt_message + '\n' : '') +
-                             'Wait timed out after ' + elapsed + 'ms'));
+            reject(
+                new error.TimeoutError(
+                    (opt_message ? opt_message + '\n' : '')
+                        + `Wait timed out after ${elapsed}ms`));
           } else {
             // Do not use asyncRun here because we need a non-micro yield
             // here so the UI thread is given a chance when running in a

package/lib/webdriver.js

@@ -497,6 +497,7 @@ class IWebDriver {
    *     function, or rejected if the condition times out. If the input
    *     input condition is an instance of a {@link WebElementCondition},
    *     the returned value will be a {@link WebElementPromise}.
+   * @throws {TypeError} if the provided `condition` is not a valid type.
    * @template T
    */
   wait(condition, opt_timeout, opt_message) {}
@@ -932,6 +933,12 @@ class WebDriver {
       fn = condition.fn;
     }
 
+    if (typeof fn !== 'function') {
+      throw TypeError(
+          'Wait condition must be a promise-like object, function, or a '
+              + 'Condition object');
+    }
+
     var driver = this;
     var result = this.flow_.wait(function() {
       if (promise.isGenerator(fn)) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "selenium-webdriver",
-  "version": "3.0.0",
+  "version": "3.0.1",
   "description": "The official WebDriver JavaScript bindings from the Selenium project",
   "license": "Apache-2.0",
   "keywords": [

package/test/lib/promise_flow_test.js

@@ -22,6 +22,7 @@ const fail = assert.fail;
 const sinon = require('sinon');
 
 const testutil = require('./testutil');
+const {TimeoutError} = require('../../lib/error');
 const promise = require('../../lib/promise');
 const {enablePromiseManager} = require('../../lib/test/promise');
 
@@ -1133,6 +1134,7 @@ describe('promise control flow', function() {
             default:
               fail('unexpected polling count: ' + count);
           }
+          assert.ok(e instanceof TimeoutError, 'Unexpected error: ' + e);
           assert.ok(
               /^counting to 3\nWait timed out after \d+ms$/.test(e.message));
         });
@@ -1190,6 +1192,7 @@ describe('promise control flow', function() {
       it('promiseThatDoesNotResolveBeforeTimeout', function() {
         var d = promise.defer();
         flow.wait(d.promise, 5).then(fail, function(e) {
+          assert.ok(e instanceof TimeoutError, 'Unexpected error: ' + e);
           assert.ok(
               /Timed out waiting for promise to resolve after \d+ms/
                   .test(e.message),

package/test/lib/webdriver_test.js

@@ -30,6 +30,7 @@ const logging = require('../../lib/logging');
 const Session = require('../../lib/session').Session;
 const promise = require('../../lib/promise');
 const {enablePromiseManager, promiseManagerSuite} = require('../../lib/test/promise');
+const until = require('../../lib/until');
 const Alert = require('../../lib/webdriver').Alert;
 const AlertPromise = require('../../lib/webdriver').AlertPromise;
 const UnhandledAlertError = require('../../lib/webdriver').UnhandledAlertError;
@@ -1549,43 +1550,26 @@ describe('WebDriver', function() {
   });
 
   describe('waiting', function() {
-    it('waitSucceeds', function() {
-      let executor = new FakeExecutor().
-          expect(CName.FIND_ELEMENTS,
-                 {using: 'css selector', value: '*[id="foo"]'}).
-              andReturnSuccess([]).
-              times(2).
-          expect(CName.FIND_ELEMENTS,
-                 {using: 'css selector', value: '*[id="foo"]'}).
-              andReturnSuccess([WebElement.buildId('bar')]).
-          end();
-
-      var driver = executor.createDriver();
-      driver.wait(function() {
-        return driver.findElements(By.id('foo')).then(els => els.length > 0);
-      }, 200);
-      return waitForIdle();
-    });
-
-    it('waitTimesout_timeoutCaught', function() {
-      let executor = new FakeExecutor().
-          expect(CName.FIND_ELEMENTS,
-                 {using: 'css selector', value: '*[id="foo"]'}).
-              andReturnSuccess([]).
-              anyTimes().
-          end();
+    describe('supports custom wait functions', function() {
+      it('waitSucceeds', function() {
+        let executor = new FakeExecutor().
+            expect(CName.FIND_ELEMENTS,
+                   {using: 'css selector', value: '*[id="foo"]'}).
+                andReturnSuccess([]).
+                times(2).
+            expect(CName.FIND_ELEMENTS,
+                   {using: 'css selector', value: '*[id="foo"]'}).
+                andReturnSuccess([WebElement.buildId('bar')]).
+            end();
 
-      var driver = executor.createDriver();
-      return driver.wait(function() {
-        return driver.findElements(By.id('foo')).then(els => els.length > 0);
-      }, 25).then(fail, function(e) {
-        assert.equal('Wait timed out after ',
-            e.message.substring(0, 'Wait timed out after '.length));
+        var driver = executor.createDriver();
+        driver.wait(function() {
+          return driver.findElements(By.id('foo')).then(els => els.length > 0);
+        }, 200);
+        return waitForIdle();
       });
-    });
 
-    enablePromiseManager(() => {
-      it('waitTimesout_timeoutNotCaught', function() {
+      it('waitTimesout_timeoutCaught', function() {
         let executor = new FakeExecutor().
             expect(CName.FIND_ELEMENTS,
                    {using: 'css selector', value: '*[id="foo"]'}).
@@ -1594,14 +1578,94 @@ describe('WebDriver', function() {
             end();
 
         var driver = executor.createDriver();
-        driver.wait(function() {
+        return driver.wait(function() {
           return driver.findElements(By.id('foo')).then(els => els.length > 0);
-        }, 25);
-        return waitForAbort().then(function(e) {
+        }, 25).then(fail, function(e) {
           assert.equal('Wait timed out after ',
               e.message.substring(0, 'Wait timed out after '.length));
         });
       });
+
+      enablePromiseManager(() => {
+        it('waitTimesout_timeoutNotCaught', function() {
+          let executor = new FakeExecutor().
+              expect(CName.FIND_ELEMENTS,
+                     {using: 'css selector', value: '*[id="foo"]'}).
+                  andReturnSuccess([]).
+                  anyTimes().
+              end();
+
+          var driver = executor.createDriver();
+          driver.wait(function() {
+            return driver.findElements(By.id('foo')).then(els => els.length > 0);
+          }, 25);
+          return waitForAbort().then(function(e) {
+            assert.equal('Wait timed out after ',
+                e.message.substring(0, 'Wait timed out after '.length));
+          });
+        });
+      });
+    });
+
+    describe('supports condition objects', function() {
+      it('wait succeeds', function() {
+        let executor = new FakeExecutor()
+            .expect(CName.FIND_ELEMENTS,
+                    {using: 'css selector', value: '*[id="foo"]'})
+                .andReturnSuccess([])
+                .times(2)
+            .expect(CName.FIND_ELEMENTS,
+                    {using: 'css selector', value: '*[id="foo"]'})
+                .andReturnSuccess([WebElement.buildId('bar')])
+            .end();
+
+        let driver = executor.createDriver();
+        return driver.wait(until.elementLocated(By.id('foo')), 200);
+      });
+
+      it('wait times out', function() {
+        let executor = new FakeExecutor()
+            .expect(CName.FIND_ELEMENTS,
+                    {using: 'css selector', value: '*[id="foo"]'})
+            .andReturnSuccess([])
+            .anyTimes()
+            .end();
+
+        let driver = executor.createDriver();
+        return driver.wait(until.elementLocated(By.id('foo')), 5)
+            .then(fail, err => assert.ok(err instanceof error.TimeoutError));
+      });
+    });
+
+    describe('supports promise objects', function() {
+      it('wait succeeds', function() {
+        let promise = new Promise(resolve => {
+          setTimeout(() => resolve(1), 10);
+        });
+
+        let driver = new FakeExecutor().createDriver();
+        return driver.wait(promise, 200).then(v => assert.equal(v, 1));
+      });
+
+      it('wait times out', function() {
+        let promise = new Promise(resolve => {/* never resolves */});
+
+        let driver = new FakeExecutor().createDriver();
+        return driver.wait(promise, 5)
+            .then(fail, err => assert.ok(err instanceof error.TimeoutError));
+      });
+
+      it('wait fails if promise is rejected', function() {
+        let err = Error('boom');
+        let driver = new FakeExecutor().createDriver();
+        return driver.wait(Promise.reject(err), 5)
+            .then(fail, e => assert.strictEqual(e, err));
+      });
+    });
+
+    it('fails if not supported condition type provided', function() {
+      let driver = new FakeExecutor().createDriver();
+      assert.throws(() => driver.wait({}, 5), TypeError);
     });
   });
 
@@ -1773,7 +1837,7 @@ describe('WebDriver', function() {
 
   describe('actions()', function() {
     it('failsIfInitialDriverCreationFailed', function() {
-      let session = Promise.reject(new StubError);
+      let session = Promise.reject(new StubError('no session for you'));
       let driver = new FakeExecutor().createDriver(session);
       driver.getSession().catch(function() {});
       return driver.