selenium-webdriver 3.6.0 → 4.0.0-alpha.1

package/lib/actions.js

@@ -70,7 +70,7 @@ function checkModifierKey(key) {
  *
  * Sample usage:
  *
- *     driver.actions().
+ *     new LegacyActions(driver).
  *         keyDown(Key.SHIFT).
  *         click(element1).
  *         click(element2).
@@ -78,8 +78,14 @@ function checkModifierKey(key) {
  *         keyUp(Key.SHIFT).
  *         perform();
  *
+ * @deprecated This class is strongly deprecated and will be removed once
+ *     [Google's Chrome][Chrome] and [Microsoft's Edge][Edge] browsers
+ *     support the new action sequence API.
+ *
+ * [Chrome]: https://chromium.googlesource.com/chromium/src/+/master/docs/chromedriver_status.md
+ * [Edge]: https://docs.microsoft.com/en-us/microsoft-edge/webdriver
  */
-class ActionSequence {
+class LegacyActionSequence {
   /**
    * @param {!./webdriver.WebDriver} driver The driver that should be used to
    *     perform this action sequence.
@@ -110,21 +116,17 @@ class ActionSequence {
   /**
    * Executes this action sequence.
    *
-   * @return {!./promise.Thenable} A promise that will be resolved once
-   *     this sequence has completed.
+   * @return {!Promise} A promise that will be resolved once this sequence has
+   *     completed.
    */
-  perform() {
+  async perform() {
     // Make a protected copy of the scheduled actions. This will protect against
     // users defining additional commands before this sequence is actually
     // executed.
     let actions = this.actions_.concat();
-    let driver = this.driver_;
-    return driver.controlFlow().execute(function() {
-      let results = actions.map(action => {
-        return driver.schedule(action.command, action.description);
-      });
-      return Promise.all(results);
-    }, 'ActionSequence.perform');
+    for (let action of actions) {
+      await this.driver_.execute(action.command);
+    }
   }
 
   /**
@@ -140,10 +142,10 @@ class ActionSequence {
    *     an offset within that element. The offset should be specified in pixels
    *     relative to the top-left corner of the element's bounding box. If
    *     omitted, the element's center will be used as the target offset.
-   * @return {!ActionSequence} A self reference.
+   * @return {!LegacyActionSequence} A self reference.
    */
   mouseMove(location, opt_offset) {
-    let cmd = new command.Command(command.Name.MOVE_TO);
+    let cmd = new command.Command(command.Name.LEGACY_ACTION_MOUSE_MOVE);
 
     if (typeof location.x === 'number') {
       setOffset(/** @type {{x: number, y: number}} */(location));
@@ -176,7 +178,7 @@ class ActionSequence {
    * @param {input.Button=} opt_button The button to use. Defaults to
    *     {@link input.Button.LEFT}. Ignored if the previous argument is
    *     provided as a button.
-   * @return {!ActionSequence} A self reference.
+   * @return {!LegacyActionSequence} A self reference.
    * @private
    */
   scheduleMouseAction_(
@@ -219,11 +221,11 @@ class ActionSequence {
    * @param {input.Button=} opt_button The button to use. Defaults to
    *     {@link input.Button.LEFT}. Ignored if a button is provided as the
    *     first argument.
-   * @return {!ActionSequence} A self reference.
+   * @return {!LegacyActionSequence} A self reference.
    */
   mouseDown(opt_elementOrButton, opt_button) {
     return this.scheduleMouseAction_('mouseDown',
-        command.Name.MOUSE_DOWN, opt_elementOrButton, opt_button);
+        command.Name.LEGACY_ACTION_MOUSE_DOWN, opt_elementOrButton, opt_button);
   }
 
   /**
@@ -245,11 +247,11 @@ class ActionSequence {
    * @param {input.Button=} opt_button The button to use. Defaults to
    *     {@link input.Button.LEFT}. Ignored if a button is provided as the
    *     first argument.
-   * @return {!ActionSequence} A self reference.
+   * @return {!LegacyActionSequence} A self reference.
    */
   mouseUp(opt_elementOrButton, opt_button) {
     return this.scheduleMouseAction_('mouseUp',
-        command.Name.MOUSE_UP, opt_elementOrButton, opt_button);
+        command.Name.LEGACY_ACTION_MOUSE_UP, opt_elementOrButton, opt_button);
   }
 
   /**
@@ -261,7 +263,7 @@ class ActionSequence {
    * @param {(!./webdriver.WebElement|{x: number, y: number})} location The
    *     location to drag to, either as another WebElement or an offset in
    *     pixels.
-   * @return {!ActionSequence} A self reference.
+   * @return {!LegacyActionSequence} A self reference.
    */
   dragAndDrop(element, location) {
     return this.mouseDown(element).mouseMove(location).mouseUp();
@@ -282,11 +284,11 @@ class ActionSequence {
    * @param {input.Button=} opt_button The button to use. Defaults to
    *     {@link input.Button.LEFT}. Ignored if a button is provided as the
    *     first argument.
-   * @return {!ActionSequence} A self reference.
+   * @return {!LegacyActionSequence} A self reference.
    */
   click(opt_elementOrButton, opt_button) {
     return this.scheduleMouseAction_('click',
-        command.Name.CLICK, opt_elementOrButton, opt_button);
+        command.Name.LEGACY_ACTION_CLICK, opt_elementOrButton, opt_button);
   }
 
   /**
@@ -307,11 +309,12 @@ class ActionSequence {
    * @param {input.Button=} opt_button The button to use. Defaults to
    *     {@link input.Button.LEFT}. Ignored if a button is provided as the
    *     first argument.
-   * @return {!ActionSequence} A self reference.
+   * @return {!LegacyActionSequence} A self reference.
    */
   doubleClick(opt_elementOrButton, opt_button) {
     return this.scheduleMouseAction_('doubleClick',
-        command.Name.DOUBLE_CLICK, opt_elementOrButton, opt_button);
+        command.Name.LEGACY_ACTION_DOUBLE_CLICK, opt_elementOrButton,
+        opt_button);
   }
 
   /**
@@ -320,11 +323,11 @@ class ActionSequence {
    * @param {string} description A simple descriptive label for the scheduled
    *     action.
    * @param {!Array<(string|!input.Key)>} keys The keys to send.
-   * @return {!ActionSequence} A self reference.
+   * @return {!LegacyActionSequence} A self reference.
    * @private
    */
   scheduleKeyboardAction_(description, keys) {
-    let cmd = new command.Command(command.Name.SEND_KEYS_TO_ACTIVE_ELEMENT)
+    let cmd = new command.Command(command.Name.LEGACY_ACTION_SEND_KEYS)
         .setParameter('value', keys);
     this.schedule_(description, cmd);
     return this;
@@ -337,7 +340,7 @@ class ActionSequence {
    *
    * @param {!input.Key} key The modifier key to push. Must be one of
    *     {ALT, CONTROL, SHIFT, COMMAND, META}.
-   * @return {!ActionSequence} A self reference.
+   * @return {!LegacyActionSequence} A self reference.
    * @throws {error.InvalidArgumentError} If the key is not a valid modifier
    *     key.
    */
@@ -351,7 +354,7 @@ class ActionSequence {
    * focused element.
    * @param {!input.Key} key The modifier key to release. Must be one of
    *     {ALT, CONTROL, SHIFT, COMMAND, META}.
-   * @return {!ActionSequence} A self reference.
+   * @return {!LegacyActionSequence} A self reference.
    * @throws {error.InvalidArgumentError} If the key is not a valid modifier
    *     key.
    */
@@ -367,7 +370,7 @@ class ActionSequence {
    *
    * @param {...(string|!input.Key|!Array<(string|!input.Key)>)} var_args
    *     The keys to type.
-   * @return {!ActionSequence} A self reference.
+   * @return {!LegacyActionSequence} A self reference.
    * @throws {Error} If the key is not a valid modifier key.
    */
   sendKeys(var_args) {
@@ -386,14 +389,20 @@ class ActionSequence {
  *
  * Sample usage:
  *
- *     driver.touchActions().
+ *     new LegacyActions(driver).
  *         tapAndHold({x: 0, y: 0}).
  *         move({x: 3, y: 4}).
  *         release({x: 10, y: 10}).
  *         perform();
  *
+ * @deprecated This class is strongly deprecated and will be removed once
+ *     [Google's Chrome][Chrome] and [Microsoft's Edge][Edge] browsers
+ *     support the new action sequence API.
+ *
+ * [Chrome]: https://chromium.googlesource.com/chromium/src/+/master/docs/chromedriver_status.md
+ * [Edge]: https://docs.microsoft.com/en-us/microsoft-edge/webdriver
  */
-class TouchSequence {
+class LegacyTouchSequence {
   /**
    * @param {!./webdriver.WebDriver} driver The driver that should be used to
    *     perform this action sequence.
@@ -422,31 +431,27 @@ class TouchSequence {
 
   /**
    * Executes this action sequence.
-   * @return {!./promise.Thenable} A promise that will be resolved once
-   *     this sequence has completed.
+   * @return {!Promise} A promise that will be resolved once this sequence has
+   *     completed.
    */
-  perform() {
+  async perform() {
     // Make a protected copy of the scheduled actions. This will protect against
     // users defining additional commands before this sequence is actually
     // executed.
     let actions = this.actions_.concat();
-    let driver = this.driver_;
-    return driver.controlFlow().execute(function() {
-      let results = actions.map(action => {
-        return driver.schedule(action.command, action.description);
-      });
-      return Promise.all(results);
-    }, 'TouchSequence.perform');
+    for (let action of actions) {
+      await this.driver_.execute(action.command);
+    }
   }
 
   /**
    * Taps an element.
    *
    * @param {!./webdriver.WebElement} elem The element to tap.
-   * @return {!TouchSequence} A self reference.
+   * @return {!LegacyTouchSequence} A self reference.
    */
   tap(elem) {
-    let cmd = new command.Command(command.Name.TOUCH_SINGLE_TAP).
+    let cmd = new command.Command(command.Name.LEGACY_ACTION_TOUCH_SINGLE_TAP).
         setParameter('element', elem.getId());
 
     this.schedule_('tap', cmd);
@@ -457,10 +462,10 @@ class TouchSequence {
    * Double taps an element.
    *
    * @param {!./webdriver.WebElement} elem The element to double tap.
-   * @return {!TouchSequence} A self reference.
+   * @return {!LegacyTouchSequence} A self reference.
    */
   doubleTap(elem) {
-    let cmd = new command.Command(command.Name.TOUCH_DOUBLE_TAP).
+    let cmd = new command.Command(command.Name.LEGACY_ACTION_TOUCH_DOUBLE_TAP).
         setParameter('element', elem.getId());
 
     this.schedule_('doubleTap', cmd);
@@ -471,10 +476,10 @@ class TouchSequence {
    * Long press on an element.
    *
    * @param {!./webdriver.WebElement} elem The element to long press.
-   * @return {!TouchSequence} A self reference.
+   * @return {!LegacyTouchSequence} A self reference.
    */
   longPress(elem) {
-    let cmd = new command.Command(command.Name.TOUCH_LONG_PRESS).
+    let cmd = new command.Command(command.Name.LEGACY_ACTION_TOUCH_LONG_PRESS).
         setParameter('element', elem.getId());
 
     this.schedule_('longPress', cmd);
@@ -485,10 +490,10 @@ class TouchSequence {
    * Touch down at the given location.
    *
    * @param {{x: number, y: number}} location The location to touch down at.
-   * @return {!TouchSequence} A self reference.
+   * @return {!LegacyTouchSequence} A self reference.
    */
   tapAndHold(location) {
-    let cmd = new command.Command(command.Name.TOUCH_DOWN).
+    let cmd = new command.Command(command.Name.LEGACY_ACTION_TOUCH_DOWN).
         setParameter('x', location.x).
         setParameter('y', location.y);
 
@@ -500,10 +505,10 @@ class TouchSequence {
    * Move a held {@linkplain #tapAndHold touch} to the specified location.
    *
    * @param {{x: number, y: number}} location The location to move to.
-   * @return {!TouchSequence} A self reference.
+   * @return {!LegacyTouchSequence} A self reference.
    */
   move(location) {
-    let cmd = new command.Command(command.Name.TOUCH_MOVE).
+    let cmd = new command.Command(command.Name.LEGACY_ACTION_TOUCH_MOVE).
         setParameter('x', location.x).
         setParameter('y', location.y);
 
@@ -515,10 +520,10 @@ class TouchSequence {
    * Release a held {@linkplain #tapAndHold touch} at the specified location.
    *
    * @param {{x: number, y: number}} location The location to release at.
-   * @return {!TouchSequence} A self reference.
+   * @return {!LegacyTouchSequence} A self reference.
    */
   release(location) {
-    let cmd = new command.Command(command.Name.TOUCH_UP).
+    let cmd = new command.Command(command.Name.LEGACY_ACTION_TOUCH_UP).
         setParameter('x', location.x).
         setParameter('y', location.y);
 
@@ -530,10 +535,10 @@ class TouchSequence {
    * Scrolls the touch screen by the given offset.
    *
    * @param {{x: number, y: number}} offset The offset to scroll to.
-   * @return {!TouchSequence} A self reference.
+   * @return {!LegacyTouchSequence} A self reference.
    */
   scroll(offset) {
-    let cmd = new command.Command(command.Name.TOUCH_SCROLL).
+    let cmd = new command.Command(command.Name.LEGACY_ACTION_TOUCH_SCROLL).
         setParameter('xoffset', offset.x).
         setParameter('yoffset', offset.y);
 
@@ -547,10 +552,10 @@ class TouchSequence {
    *
    * @param {!./webdriver.WebElement} elem The element where scroll starts.
    * @param {{x: number, y: number}} offset The offset to scroll to.
-   * @return {!TouchSequence} A self reference.
+   * @return {!LegacyTouchSequence} A self reference.
    */
   scrollFromElement(elem, offset) {
-    let cmd = new command.Command(command.Name.TOUCH_SCROLL).
+    let cmd = new command.Command(command.Name.LEGACY_ACTION_TOUCH_SCROLL).
         setParameter('element', elem.getId()).
         setParameter('xoffset', offset.x).
         setParameter('yoffset', offset.y);
@@ -564,10 +569,10 @@ class TouchSequence {
    *
    * @param {{xspeed: number, yspeed: number}} speed The speed to flick in each
          direction, in pixels per second.
-   * @return {!TouchSequence} A self reference.
+   * @return {!LegacyTouchSequence} A self reference.
    */
   flick(speed) {
-    let cmd = new command.Command(command.Name.TOUCH_FLICK).
+    let cmd = new command.Command(command.Name.LEGACY_ACTION_TOUCH_FLICK).
         setParameter('xspeed', speed.xspeed).
         setParameter('yspeed', speed.yspeed);
 
@@ -581,10 +586,10 @@ class TouchSequence {
    * @param {!./webdriver.WebElement} elem The element where flick starts.
    * @param {{x: number, y: number}} offset The offset to flick to.
    * @param {number} speed The speed to flick at in pixels per second.
-   * @return {!TouchSequence} A self reference.
+   * @return {!LegacyTouchSequence} A self reference.
    */
   flickElement(elem, offset, speed) {
-    let cmd = new command.Command(command.Name.TOUCH_FLICK).
+    let cmd = new command.Command(command.Name.LEGACY_ACTION_TOUCH_FLICK).
         setParameter('element', elem.getId()).
         setParameter('xoffset', offset.x).
         setParameter('yoffset', offset.y).
@@ -599,6 +604,6 @@ class TouchSequence {
 // PUBLIC API
 
 module.exports = {
-  ActionSequence: ActionSequence,
-  TouchSequence: TouchSequence,
+  LegacyActionSequence,
+  LegacyTouchSequence,
 };

package/lib/by.js

@@ -182,7 +182,7 @@ class By {
    *
    * @param {!(string|Function)} script The script to execute.
    * @param {...*} var_args The arguments to pass to the script.
-   * @return {function(!./webdriver.WebDriver): !./promise.Promise}
+   * @return {function(!./webdriver.WebDriver): !Promise}
    *     A new JavaScript-based locator function.
    */
   static js(script, var_args) {