selenium-webdriver 4.0.0-beta.1 → 4.0.0-rc-1

package/lib/by.js

@@ -258,8 +258,36 @@ class By {
   }
 }
 
+/**
+ * Start Searching for relative objects using the value returned from
+ * `By.tagName()`.
+ *
+ * Note: this method will likely be removed in the future please use
+ * `locateWith`.
+ * @param {By} The value returned from calling By.tagName()
+ * @returns
+ */
 function withTagName(tagName) {
-  return new RelativeBy(tagName)
+  return new RelativeBy({ 'css selector': tagName })
+}
+
+/**
+ * Start searching for relative objects using search criteria with By.
+ * @param {string} A By map that shows how to find the initial element
+ * @returns {RelativeBy}
+ */
+function locateWith(by) {
+  return new RelativeBy(getLocator(by));
+}
+
+function getLocator(locatorOrElement) {
+  let toFind
+  if (locatorOrElement instanceof By) {
+    toFind = locatorOrElement.toObject()
+  } else {
+    toFind = locatorOrElement
+  }
+  return toFind
 }
 
 /**
@@ -269,11 +297,11 @@ function withTagName(tagName) {
  */
 class RelativeBy {
   /**
-   * @param {string} tagName
+   * @param {By} findDetails
    * @param {Array<Object>} filters
    */
-  constructor(tagName, filters = null) {
-    this.root = tagName
+  constructor(findDetails, filters = null) {
+    this.root = findDetails
     this.filters = filters || []
   }
 
@@ -285,7 +313,7 @@ class RelativeBy {
   above(locatorOrElement) {
     this.filters.push({
       kind: 'above',
-      args: [this.getLocator(locatorOrElement)],
+      args: [getLocator(locatorOrElement)],
     })
     return this
   }
@@ -298,7 +326,7 @@ class RelativeBy {
   below(locatorOrElement) {
     this.filters.push({
       kind: 'below',
-      args: [this.getLocator(locatorOrElement)],
+      args: [getLocator(locatorOrElement)],
     })
     return this
   }
@@ -311,7 +339,7 @@ class RelativeBy {
   toLeftOf(locatorOrElement) {
     this.filters.push({
       kind: 'left',
-      args: [this.getLocator(locatorOrElement)],
+      args: [getLocator(locatorOrElement)],
     })
     return this
   }
@@ -324,7 +352,7 @@ class RelativeBy {
   toRightOf(locatorOrElement) {
     this.filters.push({
       kind: 'right',
-      args: [this.getLocator(locatorOrElement)],
+      args: [getLocator(locatorOrElement)],
     })
     return this
   }
@@ -337,7 +365,7 @@ class RelativeBy {
   near(locatorOrElement) {
     this.filters.push({
       kind: 'near',
-      args: [this.getLocator(locatorOrElement)],
+      args: [getLocator(locatorOrElement)],
     })
     return this
   }
@@ -350,22 +378,12 @@ class RelativeBy {
   marshall() {
     return {
       relative: {
-        root: { 'css selector': this.root },
+        root: this.root,
         filters: this.filters,
       },
     }
   }
 
-  getLocator(locatorOrElement) {
-    let toFind
-    if (locatorOrElement instanceof By) {
-      toFind = locatorOrElement.toObject()
-    } else {
-      toFind = locatorOrElement
-    }
-    return toFind
-  }
-
   /** @override */
   toString() {
     // The static By.name() overrides this.constructor.name.  Shame...
@@ -411,5 +429,6 @@ module.exports = {
   By: By,
   RelativeBy: RelativeBy,
   withTagName: withTagName,
+  locateWith: locateWith,
   checkedLocator: check,
 }

package/lib/capabilities.js

@@ -32,7 +32,6 @@ const Browser = {
   CHROME: 'chrome',
   EDGE: 'MicrosoftEdge',
   FIREFOX: 'firefox',
-  IE: 'internet explorer',
   INTERNET_EXPLORER: 'internet explorer',
   SAFARI: 'safari',
   OPERA: 'opera',
@@ -264,7 +263,9 @@ class Capabilities {
    * @return {!Capabilities} A basic set of capabilities for Firefox.
    */
   static firefox() {
-    return new Capabilities().setBrowserName(Browser.FIREFOX).set("moz:debuggerAddress", true)
+    return new Capabilities()
+      .setBrowserName(Browser.FIREFOX)
+      .set('moz:debuggerAddress', true)
   }
 
   /**
@@ -281,6 +282,13 @@ class Capabilities {
     return new Capabilities().setBrowserName(Browser.SAFARI)
   }
 
+  /**
+   * @return {!Capabilities} A basic set of capabilities for Opera
+   */
+  static opera() {
+    return new Capabilities().setBrowserName(Browser.OPERA)
+  }
+
   /**
    * @return {!Object<string, ?>} The JSON representation of this instance.
    *     Note, the returned object may contain nested promised values.

package/lib/command.js

@@ -177,21 +177,6 @@ const Name = {
 
   ACTIONS: 'actions',
   CLEAR_ACTIONS: 'clearActions',
-
-  LEGACY_ACTION_CLICK: 'legacyAction:click',
-  LEGACY_ACTION_DOUBLE_CLICK: 'legacyAction:doubleclick',
-  LEGACY_ACTION_MOUSE_DOWN: 'legacyAction:mouseDown',
-  LEGACY_ACTION_MOUSE_UP: 'legacyAction:mouseUp',
-  LEGACY_ACTION_MOUSE_MOVE: 'legacyAction:mouseMove',
-  LEGACY_ACTION_SEND_KEYS: 'legacyAction:sendKeys',
-  LEGACY_ACTION_TOUCH_DOWN: 'legacyAction:touchDown',
-  LEGACY_ACTION_TOUCH_UP: 'legacyAction:touchUp',
-  LEGACY_ACTION_TOUCH_MOVE: 'legacyAction:touchMove',
-  LEGACY_ACTION_TOUCH_SCROLL: 'legacyAction:touchScroll',
-  LEGACY_ACTION_TOUCH_LONG_PRESS: 'legacyAction:touchLongPress',
-  LEGACY_ACTION_TOUCH_FLICK: 'legacyAction:touchFlick',
-  LEGACY_ACTION_TOUCH_SINGLE_TAP: 'legacyAction:singleTap',
-  LEGACY_ACTION_TOUCH_DOUBLE_TAP: 'legacyAction:doubleTap',
 }
 
 /**

package/lib/http.js

@@ -305,35 +305,6 @@ const COMMAND_MAP = new Map([
   [cmd.Name.GET_AVAILABLE_LOG_TYPES, get('/session/:sessionId/log/types')],
   [cmd.Name.GET_SESSION_LOGS, post('/logs')],
   [cmd.Name.UPLOAD_FILE, post('/session/:sessionId/se/file')],
-  [cmd.Name.LEGACY_ACTION_CLICK, post('/session/:sessionId/click')],
-  [
-    cmd.Name.LEGACY_ACTION_DOUBLE_CLICK,
-    post('/session/:sessionId/doubleclick'),
-  ],
-  [cmd.Name.LEGACY_ACTION_MOUSE_DOWN, post('/session/:sessionId/buttondown')],
-  [cmd.Name.LEGACY_ACTION_MOUSE_UP, post('/session/:sessionId/buttonup')],
-  [cmd.Name.LEGACY_ACTION_MOUSE_MOVE, post('/session/:sessionId/moveto')],
-  [cmd.Name.LEGACY_ACTION_SEND_KEYS, post('/session/:sessionId/keys')],
-  [cmd.Name.LEGACY_ACTION_TOUCH_DOWN, post('/session/:sessionId/touch/down')],
-  [cmd.Name.LEGACY_ACTION_TOUCH_UP, post('/session/:sessionId/touch/up')],
-  [cmd.Name.LEGACY_ACTION_TOUCH_MOVE, post('/session/:sessionId/touch/move')],
-  [
-    cmd.Name.LEGACY_ACTION_TOUCH_SCROLL,
-    post('/session/:sessionId/touch/scroll'),
-  ],
-  [
-    cmd.Name.LEGACY_ACTION_TOUCH_LONG_PRESS,
-    post('/session/:sessionId/touch/longclick'),
-  ],
-  [cmd.Name.LEGACY_ACTION_TOUCH_FLICK, post('/session/:sessionId/touch/flick')],
-  [
-    cmd.Name.LEGACY_ACTION_TOUCH_SINGLE_TAP,
-    post('/session/:sessionId/touch/click'),
-  ],
-  [
-    cmd.Name.LEGACY_ACTION_TOUCH_DOUBLE_TAP,
-    post('/session/:sessionId/touch/doubleclick'),
-  ],
 ])
 
 /** @const {!Map<string, (CommandSpec|CommandTransformer)>} */
@@ -519,7 +490,8 @@ function buildRequest(customCommands, w3c, command) {
   }
 }
 
-const CLIENTS = /** !WeakMap<!Executor, !(Client|IThenable<!Client>)> */ new WeakMap()
+const CLIENTS =
+  /** !WeakMap<!Executor, !(Client|IThenable<!Client>)> */ new WeakMap()
 
 /**
  * A command executor that communicates with the server using JSON over HTTP.

package/lib/input.js

@@ -20,14 +20,8 @@
 /**
  * @fileoverview Defines types related to user input with the WebDriver API.
  */
-
-const promise = require('./promise')
 const { Command, Name } = require('./command')
-const {
-  InvalidArgumentError,
-  UnknownCommandError,
-  UnsupportedOperationError,
-} = require('./error')
+const { InvalidArgumentError } = require('./error')
 
 /**
  * Enumeration of the buttons used in the advanced interactions API.
@@ -489,67 +483,6 @@ Pointer.Type = {
  * | Keyboard | pause(100)            | keyDown(SHIFT) |
  * | Mouse    | move({duration: 300}) |                |
  *
- *
- * #### Bridge Mode
- *
- * As of January 2018, only Firefox natively supports this API. For other
- * browsers, you may either use the
- * {@link ./actions.LegacyActionSequence LegacyActionSequence} class, _or_ you
- * can put the Actions class into bridge mode by passing `{bridge: true}` on
- * creation:
- *
- *     const actions = driver.actions({bridge: true});
- *     await actions.click(element).sendKeys('abc').perform();
- *
- * In bridge mode, {@link #perform perform()} will first attempt to execute the
- * configured action sequence using the W3C action protocol. If this is rejected
- * by the remote end, the sequence will be translated to and executed against
- * the legacy protocol.
- *
- * Bridge mode __is not enabled by default__ as there are several notable
- * differences between W3C-specified and legacy protocols. Care must be
- * taken to configure your action sequences to account for these differences:
- *
- * 1.  For W3C actions, the entire action sequence is executed in a single
- *     call to the remote end. For legacy sequences, multiple calls must be
- *     made for each step in the sequence. This introduces additional latency
- *     which may impact how the browser responds to the emulated user actions.
- *
- * 2.  For the legacy actions, {@linkplain #pause pauses} are handled _locally_.
- *
- * 3.  For legacy actions, a {@linkplain #keyDown keyDown()} for a
- *     _non-modifier key_ **must** be followed by a {@linkplain #keyUP keyUp()}
- *     for the same key. This will be handled for you if you use the
- *     {@linkplain #sendKeys sendKeys()} method.
- *
- * 4.  Mouse movements may not be specified relative to
- *     {@linkplain ./input.Origin.VIEWPORT Origin.VIEWPORT}.
- *     All movements must be relative to an element or the mouse's current
- *     position ({@linkplain ./input.Origin.POINTER Origin.POINTER}).
- *     The {@linkplain #move move()} method defaults to viewport relative
- *     offsets, so you must always specify an appropriate origin in bridge mode:
- *
- *         driver.actions({bridge: true})
- *             .move({x: 0, y: 0, origin: Origin.POINTER})
- *             .perform();
- *         driver.actions({bridge: true})
- *             .move({x: 0, y: 0, origin: someWebElement})
- *             .perform();
- *
- * 5.  The legacy protocol does not support specifying the duration of a
- *     {@linkplain #move mouse movement}; any specified duration _is ignored_
- *     when translating actions to the legacy protocol.
- *
- * 6.  For W3C actions, move offsets relative to a
- *     {@linkplain ./webdriver.WebElement WebElement} are interpreted relative
- *     to the center of an element's _first_ [client rect] in the viewport. For
- *     legacy actions, element offsets are relative to the top-left corner of
- *     the element's [bounding client rect]. When translating actions to the
- *     legacy protocol in bridge mode, an extra command must be inserted to
- *     translate move offsets from one frame of reference to the other. This
- *     extra command contributes to the overall latency issue outlined in
- *     point 1.
- *
  * [client rect]: https://developer.mozilla.org/en-US/docs/Web/API/Element/getClientRects
  * [bounding client rect]: https://developer.mozilla.org/en-US/docs/Web/API/Element/getBoundingClientRect
  *
@@ -560,26 +493,16 @@ class Actions {
   /**
    * @param {!Executor} executor The object to execute the configured
    *     actions with.
-   * @param {{async: (boolean|undefined),
-   *          bridge: (boolean|undefined)}} options Options for this action
+   * @param {{async: (boolean|undefined)}} options Options for this action
    *     sequence (see class description for details).
    */
-  constructor(executor, { async = false, bridge = false } = {}) {
-    if (async && bridge) {
-      throw new InvalidArgumentError(
-        'Async sequences not supported with bridge mode'
-      )
-    }
-
+  constructor(executor, { async = false } = {}) {
     /** @private @const */
     this.executor_ = executor
 
     /** @private @const */
     this.sync_ = !async
 
-    /** @private @const */
-    this.bridge_ = !!bridge
-
     /** @private @const */
     this.keyboard_ = new Keyboard('default keyboard')
 
@@ -952,20 +875,9 @@ class Actions {
       return Promise.resolve()
     }
 
-    try {
-      await this.executor_.execute(
-        new Command(Name.ACTIONS).setParameter('actions', _actions)
-      )
-    } catch (ex) {
-      if (
-        this.bridge_ &&
-        (ex instanceof UnknownCommandError ||
-          ex instanceof UnsupportedOperationError)
-      ) {
-        return executeLegacy(this.executor_, this.sequences_)
-      }
-      throw ex
-    }
+    await this.executor_.execute(
+      new Command(Name.ACTIONS).setParameter('actions', _actions)
+    )
   }
 }
 
@@ -980,213 +892,6 @@ function isIdle(actions) {
   )
 }
 
-const MODIFIER_KEYS = new Set([Key.ALT, Key.CONTROL, Key.SHIFT, Key.COMMAND])
-
-/**
- * @param {!Executor} executor
- * @param {!Map<!Device, !Array<!Action>>} sequences
- * @return {!Promise<void>}
- * @suppress {deprecated} Ignore warnings about using LegacyActionSequence.
- */
-async function executeLegacy(executor, sequences) {
-  let maxLength = 0
-  sequences.forEach((seq) => (maxLength = Math.max(maxLength, seq.length)))
-
-  const actions = []
-  for (let i = 0; i < maxLength; i++) {
-    let next
-    for (const device of sequences.keys()) {
-      const seq = sequences.get(device)
-
-      if (
-        device instanceof Pointer &&
-        device.pointerType_ !== Pointer.Type.MOUSE
-      ) {
-        throw new UnsupportedOperationError(
-          `${device.pointerType_} pointer not supported in bridge mode`
-        )
-      }
-
-      const action = seq[i]
-      if (!action || (action.type === Action.Type.PAUSE && !action.duration)) {
-        continue
-      }
-
-      // -  If we've already found an action for this tick:
-      //    -  If we have two pauses, use the one with a longer duration
-      //    -  If one is a pause and the other isn't, use the non-pause
-      //    -  Otherwise, two non-pauses is an error.
-      // - Otherwise, we haven't selected an action yet.
-      if (next) {
-        if (next.type === Action.Type.PAUSE) {
-          if (action.type === Action.Type.PAUSE) {
-            next = next.duration > action.duration ? next : action
-          } else {
-            next = action
-          }
-        } else if (action.type !== Action.Type.PAUSE) {
-          throw new UnsupportedOperationError(
-            'parallel actions not supported in bridge mode'
-          )
-        }
-      } else {
-        next = action
-      }
-
-      if (action.type === Action.Type.KEY_DOWN) {
-        // If this action is a keydown for a non-modifier key, the next action
-        // must be a keyup for the same key, otherwise it cannot be translated
-        // to the legacy action API.
-        if (!MODIFIER_KEYS.has(action.value)) {
-          const nextAction = seq[i + 1]
-          if (
-            !nextAction ||
-            nextAction.type !== Action.Type.KEY_UP ||
-            nextAction.value !== action.value
-          ) {
-            throw new UnsupportedOperationError(
-              `in bridge mode, keydown for <${action.value}> must be followed` +
-                ' by a keyup for the same key'
-            )
-          }
-        }
-      } else if (
-        action.type === Action.Type.KEY_UP &&
-        !MODIFIER_KEYS.has(action.value)
-      ) {
-        next = null
-      }
-    }
-
-    if (next) {
-      actions.push(next)
-    }
-  }
-
-  for (let i = 0; i < actions.length; i++) {
-    const action = actions[i]
-    switch (action.type) {
-      case Action.Type.PAUSE: {
-        await promise.delayed(action.duration || 0)
-        break
-      }
-      case Action.Type.KEY_DOWN: {
-        const keys = [action.value]
-        if (!MODIFIER_KEYS.has(action.value)) {
-          // eslint-disable-next-line no-inner-declarations
-          function nextIsKeyDown() {
-            const next = actions[i + 1]
-            return (
-              !!next &&
-              next.type === Action.Type.KEY_DOWN &&
-              !MODIFIER_KEYS.has(next.value)
-            )
-          }
-          for (; nextIsKeyDown(); i++) {
-            keys.push(actions[i + 1].value)
-          }
-        }
-        await executor.execute(
-          new Command(Name.LEGACY_ACTION_SEND_KEYS).setParameter('value', keys)
-        )
-        break
-      }
-      case Action.Type.KEY_UP: {
-        await executor.execute(
-          new Command(Name.LEGACY_ACTION_SEND_KEYS).setParameter('value', [
-            action.value,
-          ])
-        )
-        break
-      }
-      case Action.Type.POINTER_DOWN: {
-        // eslint-disable-next-line no-inner-declarations
-        function isClick(startAt) {
-          const first = actions[startAt]
-          const second = actions[startAt + 1]
-          return (
-            !!first &&
-            !!second &&
-            first.type === Action.Type.POINTER_DOWN &&
-            second.type === Action.Type.POINTER_UP &&
-            first.button === second.button
-          )
-        }
-
-        // eslint-disable-next-line no-inner-declarations
-        function isDoubleClick(startAt) {
-          return (
-            isClick(startAt) &&
-            isClick(startAt + 2) &&
-            actions[startAt].button === actions[(startAt = 2)].button
-          )
-        }
-
-        let cmd
-        if (isDoubleClick(i)) {
-          i += 3 // Consume the pointer up/down/up.
-          cmd = Name.LEGACY_ACTION_DOUBLE_CLICK
-        } else if (isClick(i)) {
-          i++ // Consume the pointer-up.
-          cmd = Name.LEGACY_ACTION_CLICK
-        } else {
-          cmd = Name.LEGACY_ACTION_MOUSE_DOWN
-        }
-        await executor.execute(
-          new Command(cmd).setParameter('button', action.button)
-        )
-        break
-      }
-      case Action.Type.POINTER_UP: {
-        await executor.execute(
-          new Command(Name.LEGACY_ACTION_MOUSE_UP).setParameter(
-            'button',
-            action.button
-          )
-        )
-        break
-      }
-      case Action.Type.POINTER_MOVE: {
-        if (action.origin === Origin.VIEWPORT) {
-          throw new UnsupportedOperationError(
-            `pointer movements relative to ${Origin.VIEWPORT} are not` +
-              ' supported in bridge mode'
-          )
-        }
-
-        let x = action.x
-        let y = action.y
-        const cmd = new Command(Name.LEGACY_ACTION_MOUSE_MOVE)
-        if (action.origin && action.origin !== Origin.POINTER) {
-          const el = /** @type {!./webdriver.WebElement} */ (action.origin)
-
-          // Need to translate frame of reference from center of element's first
-          // client rect to the top-left of its bounding client rect. See:
-          // https://w3c.github.io/webdriver/webdriver-spec.html#dfn-center-point
-          let diff = await executor.execute(
-            new Command(Name.EXECUTE_SCRIPT)
-              .setParameter('script', INTERNAL_COMPUTE_OFFSET_SCRIPT)
-              .setParameter('args', [el])
-          )
-          x += diff[0]
-          y += diff[1]
-
-          const id = await el.getId()
-          cmd.setParameter('element', id)
-        }
-        cmd.setParameter('xoffset', x).setParameter('yoffset', y)
-        await executor.execute(cmd)
-        break
-      }
-      default: {
-        throw new UnsupportedOperationError(
-          `${action.type} actions not supported in bridge mode`
-        )
-      }
-    }
-  }
-}
-
 /**
  * Script used to compute the offset from the center of a DOM element's first
  * client rect from the top-left corner of the element's bounding client rect.

package/lib/promise.js

@@ -30,17 +30,7 @@
  * @return {boolean} Whether the value is a promise.
  */
 function isPromise(value) {
-  try {
-    // Use array notation so the Closure compiler does not obfuscate away our
-    // contract.
-    return (
-      value &&
-      (typeof value === 'object' || typeof value === 'function') &&
-      typeof value['then'] === 'function'
-    )
-  } catch (ex) {
-    return false
-  }
+  return Object.prototype.toString.call(value) === '[object Promise]'
 }
 
 /**
@@ -50,9 +40,7 @@ function isPromise(value) {
  * @return {!Promise<void>} The promise.
  */
 function delayed(ms) {
-  return new Promise((resolve) => {
-    setTimeout(resolve, ms)
-  })
+  return new Promise((resolve) => setTimeout(resolve, ms))
 }
 
 /**
@@ -199,8 +187,8 @@ async function filter(array, fn, self = undefined) {
 
   for (let i = 0; i < n; i++) {
     if (i in arr) {
-      let value = arr[i]
-      let include = await fn.call(self, value, i, arr)
+      const value = arr[i]
+      const include = await fn.call(self, value, i, arr)
       if (include) {
         values[valuesLength++] = value
       }

package/lib/until.js

@@ -137,14 +137,13 @@ exports.alertIsPresent = function alertIsPresent() {
  * @return {!Condition<boolean>} The new condition.
  */
 exports.titleIs = function titleIs(title) {
-  return new Condition(
-    'for title to be ' + JSON.stringify(title),
-    function (driver) {
-      return driver.getTitle().then(function (t) {
-        return t === title
-      })
-    }
-  )
+  return new Condition('for title to be ' + JSON.stringify(title), function (
+    driver
+  ) {
+    return driver.getTitle().then(function (t) {
+      return t === title
+    })
+  })
 }
 
 /**
@@ -189,14 +188,13 @@ exports.titleMatches = function titleMatches(regex) {
  * @return {!Condition<boolean>} The new condition.
  */
 exports.urlIs = function urlIs(url) {
-  return new Condition(
-    'for URL to be ' + JSON.stringify(url),
-    function (driver) {
-      return driver.getCurrentUrl().then(function (u) {
-        return u === url
-      })
-    }
-  )
+  return new Condition('for URL to be ' + JSON.stringify(url), function (
+    driver
+  ) {
+    return driver.getCurrentUrl().then(function (u) {
+      return u === url
+    })
+  })
 }
 
 /**