selenium-webdriver 4.1.0 → 4.2.0

package/LICENSE

@@ -187,7 +187,7 @@
       same "printed page" as the copyright notice for easier
       identification within third-party archives.
 
-   Copyright 2021 Software Freedom Conservancy (SFC)
+   Copyright 2022 Software Freedom Conservancy (SFC)
 
    Licensed under the Apache License, Version 2.0 (the "License");
    you may not use this file except in compliance with the License.

package/NOTICE

@@ -1,2 +1,2 @@
-Copyright 2011-2021 Software Freedom Conservancy
+Copyright 2011-2022 Software Freedom Conservancy
 Copyright 2004-2011 Selenium committers

package/README.md

@@ -33,10 +33,10 @@ The sample below and others are included in the `example` directory. You may
 also find the tests for selenium-webdriver informative.
 
 ```javascript
-const {Builder, By, Key, until} = require('selenium-webdriver');
+const {Builder, Browser, By, Key, until} = require('selenium-webdriver');
 
 (async function example() {
-  let driver = await new Builder().forBrowser('firefox').build();
+  let driver = await new Builder().forBrowser(Browser.FIREFOX).build();
   try {
     await driver.get('http://www.google.com/ncr');
     await driver.findElement(By.name('q')).sendKeys('webdriver', Key.RETURN);
@@ -60,7 +60,7 @@ const chrome = require('selenium-webdriver/chrome');
 const firefox = require('selenium-webdriver/firefox');
 
 let driver = new webdriver.Builder()
-    .forBrowser('firefox')
+    .forBrowser(webdriver.Browser.FIREFOX)
     .setChromeOptions(/* ... */)
     .setFirefoxOptions(/* ... */)
     .build();
@@ -99,7 +99,7 @@ API:
 
 ```javascript
 let driver = new webdriver.Builder()
-    .forBrowser('firefox')
+    .forBrowser(webdriver.Browser.FIREFOX)
     .usingServer('http://localhost:4444/wd/hub')
     .build();
 ```

package/chrome.js

@@ -236,10 +236,9 @@ class Driver extends chromium.Driver {
    */
   static createSession(opt_config, opt_serviceExecutor) {
     let caps = opt_config || new Options()
-    return /** @type {!Driver} */ (super.createSession(
-      caps,
-      opt_serviceExecutor
-    ))
+    return /** @type {!Driver} */ (
+      super.createSession(caps, opt_serviceExecutor)
+    )
   }
 }
 
@@ -287,9 +286,13 @@ Driver.getDefaultService = getDefaultService
 Driver.prototype.VENDOR_COMMAND_PREFIX = 'goog'
 
 // PUBLIC API
-exports.Driver = Driver
-exports.Options = Options
-exports.ServiceBuilder = ServiceBuilder
-exports.getDefaultService = getDefaultService
-exports.setDefaultService = setDefaultService
-exports.locateSynchronously = locateSynchronously
+
+module.exports = {
+  Driver: Driver,
+  Options,
+  ServiceBuilder ,
+  getDefaultService,
+  setDefaultService,
+  locateSynchronously
+}
+

package/chromium.js

@@ -92,11 +92,13 @@ const Command = {
   LAUNCH_APP: 'launchApp',
   GET_NETWORK_CONDITIONS: 'getNetworkConditions',
   SET_NETWORK_CONDITIONS: 'setNetworkConditions',
+  DELETE_NETWORK_CONDITIONS: 'deleteNetworkConditions',
   SEND_DEVTOOLS_COMMAND: 'sendDevToolsCommand',
   SEND_AND_GET_DEVTOOLS_COMMAND: 'sendAndGetDevToolsCommand',
   SET_PERMISSION: 'setPermission',
   GET_CAST_SINKS: 'getCastSinks',
   SET_CAST_SINK_TO_USE: 'setCastSinkToUse',
+  START_CAST_DESKTOP_MIRRORING: 'startDesktopMirroring',
   START_CAST_TAB_MIRRORING: 'setCastTabMirroring',
   GET_CAST_ISSUE_MESSAGE: 'getCastIssueMessage',
   STOP_CASTING: 'stopCasting',
@@ -105,6 +107,7 @@ const Command = {
 /**
  * Creates a command executor with support for Chromium's custom commands.
  * @param {!Promise<string>} url The server's URL.
+ * @param vendorPrefix
  * @return {!command.Executor} The new command executor.
  */
 function createExecutor(url, vendorPrefix) {
@@ -135,6 +138,11 @@ function configureExecutor(executor, vendorPrefix) {
     'POST',
     '/session/:sessionId/chromium/network_conditions'
   )
+  executor.defineCommand(
+    Command.DELETE_NETWORK_CONDITIONS,
+    'DELETE',
+    '/session/:sessionId/chromium/network_conditions'
+  )
   executor.defineCommand(
     Command.SEND_DEVTOOLS_COMMAND,
     'POST',
@@ -160,6 +168,11 @@ function configureExecutor(executor, vendorPrefix) {
     'POST',
     `/session/:sessionId/${vendorPrefix}/cast/set_sink_to_use`
   )
+  executor.defineCommand(
+    Command.START_CAST_DESKTOP_MIRRORING,
+    'POST',
+    `/session/:sessionId/${vendorPrefix}/cast/start_desktop_mirroring`
+  )
   executor.defineCommand(
     Command.START_CAST_TAB_MIRRORING,
     'POST',
@@ -217,8 +230,8 @@ class ServiceBuilder extends remote.DriverService.Builder {
    * Enables Chrome logging.
    * @returns {!ServiceBuilder} A self reference.
    */
-   enableChromeLogging() {
-    return this.addArguments('--enable-chrome-logs');
+  enableChromeLogging() {
+    return this.addArguments('--enable-chrome-logs')
   }
 
   /**
@@ -292,7 +305,7 @@ class Options extends Capabilities {
    * @return {!Options} A self reference.
    */
   debuggerAddress(address) {
-    this.options_.debuggerAddress = address;
+    this.options_.debuggerAddress = address
     return this
   }
 
@@ -648,14 +661,12 @@ class Driver extends webdriver.WebDriver {
    */
   static createSession(caps, opt_serviceExecutor) {
     let executor
-    let onQuit
     if (opt_serviceExecutor instanceof http.Executor) {
       executor = opt_serviceExecutor
       configureExecutor(executor, this.VENDOR_COMMAND_PREFIX)
     } else {
       let service = opt_serviceExecutor || this.getDefaultService()
       executor = createExecutor(service.start(), this.VENDOR_COMMAND_PREFIX)
-      onQuit = () => service.kill()
     }
 
     // W3C spec requires noProxy value to be an array of strings, but Chromium
@@ -668,7 +679,7 @@ class Driver extends webdriver.WebDriver {
       }
     }
 
-    return /** @type {!Driver} */ (super.createSession(executor, caps, onQuit))
+    return /** @type {!Driver} */ (super.createSession(executor, caps))
   }
 
   /**
@@ -699,6 +710,15 @@ class Driver extends webdriver.WebDriver {
     return this.execute(new command.Command(Command.GET_NETWORK_CONDITIONS))
   }
 
+  /**
+   * Schedules a command to delete Chromium network emulation settings.
+   * @return {!Promise} A promise that will be resolved when network
+   *     emulation settings have been deleted.
+   */
+  deleteNetworkConditions() {
+    return this.execute(new command.Command(Command.DELETE_NETWORK_CONDITIONS))
+  }
+
   /**
    * Schedules a command to set Chromium network emulation settings.
    *
@@ -833,6 +853,23 @@ class Driver extends webdriver.WebDriver {
     )
   }
 
+  /**
+   * Initiates desktop mirroring for the current browser tab on the specified device.
+   *
+   * @param {String} deviceName name of the target device.
+   * @return {!promise.Thenable<void>} A promise that will be resolved
+   *     when the mirror command has been issued to the device.
+   */
+   startDesktopMirroring(deviceName) {
+    return this.schedule(
+      new command.Command(Command.START_CAST_DESKTOP_MIRRORING).setParameter(
+        'sinkName',
+        deviceName
+      ),
+      'Driver.startDesktopMirroring(' + deviceName + ')'
+    )
+  }
+
   /**
    * Initiates tab mirroring for the current browser tab on the specified device.
    *
@@ -882,6 +919,8 @@ class Driver extends webdriver.WebDriver {
 
 // PUBLIC API
 
-exports.Driver = Driver
-exports.Options = Options
-exports.ServiceBuilder = ServiceBuilder
+module.exports = {
+  Driver,
+  Options,
+  ServiceBuilder,
+}

package/edge.js

@@ -94,7 +94,7 @@ let defaultService = null
 
 /**
  * Creates {@link selenium-webdriver/remote.DriverService} instances that manage
- * a [ChromeDriver](https://chromedriver.chromium.org/)
+ * a [MSEdgeDriver](https://developer.microsoft.com/en-us/microsoft-edge/tools/webdriver/)
  * server in a child process.
  */
 class ServiceBuilder extends chromium.ServiceBuilder {
@@ -130,7 +130,7 @@ class Options extends chromium.Options {
    * The binary path be absolute or relative to the msedgedriver server
    * executable, but it must exist on the machine that will launch edge chromium.
    *
-   * @param {string} path The path to the edgedriver binary to use.
+   * @param {string} path The path to the msedgedriver binary to use.
    * @return {!Options} A self reference.
    */
   setEdgeChromiumBinaryPath(path) {
@@ -210,9 +210,11 @@ Driver.getDefaultService = getDefaultService
 
 // PUBLIC API
 
-exports.Driver = Driver
-exports.Options = Options
-exports.ServiceBuilder = ServiceBuilder
-exports.getDefaultService = getDefaultService
-exports.setDefaultService = setDefaultService
-exports.locateSynchronously = locateSynchronously
+module.exports = {
+  Driver,
+  Options,
+  ServiceBuilder,
+  getDefaultService,
+  setDefaultService,
+  locateSynchronously,
+}

package/example/google_search.js

@@ -39,7 +39,7 @@
 
 const { Builder, By, Key, until } = require('..')
 
-var driver = new Builder().forBrowser('firefox').build()
+const driver = new Builder().forBrowser('firefox').build()
 
 driver
   .get('http://www.google.com/ncr')

package/firefox.js

@@ -116,6 +116,7 @@
 
 'use strict'
 
+const fs = require('fs')
 const path = require('path')
 const Symbols = require('./lib/symbols')
 const command = require('./lib/command')
@@ -222,7 +223,7 @@ async function buildProfile(template, extensions) {
     dir = await io.tmpDir()
     if (template) {
       await io.copyDir(
-        /** @type {string} */(template),
+        /** @type {string} */ (template),
         dir,
         /(parent\.lock|lock|\.parentlock)/
       )
@@ -400,7 +401,11 @@ class Options extends Capabilities {
    * @param {string} androidPackage The package to use
    * @return {!Options} A self reference
    */
-  enableMobile(androidPackage = "org.mozilla.firefox", androidActivity = null, deviceSerial = null) {
+  enableMobile(
+    androidPackage = 'org.mozilla.firefox',
+    androidActivity = null,
+    deviceSerial = null
+  ) {
     this.firefoxOptions_().androidPackage = androidPackage
 
     if (androidActivity) {
@@ -457,11 +462,11 @@ function findGeckoDriver() {
   if (!exe) {
     throw Error(
       'The ' +
-      GECKO_DRIVER_EXE +
-      ' executable could not be found on the current ' +
-      'PATH. Please download the latest version from ' +
-      'https://github.com/mozilla/geckodriver/releases/ ' +
-      'and ensure it can be found on your PATH.'
+        GECKO_DRIVER_EXE +
+        ' executable could not be found on the current ' +
+        'PATH. Please download the latest version from ' +
+        'https://github.com/mozilla/geckodriver/releases/ ' +
+        'and ensure it can be found on your PATH.'
     )
   }
   return exe
@@ -482,8 +487,8 @@ function findInProgramFiles(file) {
     return exists
       ? files[0]
       : io.exists(files[1]).then(function (exists) {
-        return exists ? files[1] : null
-      })
+          return exists ? files[1] : null
+        })
   })
 }
 
@@ -617,7 +622,7 @@ class Driver extends webdriver.WebDriver {
    * implementation.
    * @override
    */
-  setFileDetector() { }
+  setFileDetector() {}
 
   /**
    * Get the context that is currently in effect.
@@ -666,7 +671,15 @@ class Driver extends webdriver.WebDriver {
    * @see #uninstallAddon
    */
   async installAddon(path, temporary = false) {
-    let buf = await io.read(path)
+    let stats = fs.statSync(path)
+    let buf;
+    if (stats.isDirectory()) {
+      let zip = new Zip()
+      await zip.addDir(path)
+      buf = await zip.toBuffer('DEFLATE')
+    } else {
+      buf = await io.read(path)
+    }
     return this.execute(
       new command.Command(ExtensionCommand.INSTALL_ADDON)
         .setParameter('addon', buf.toString('base64'))
@@ -805,9 +818,11 @@ Channel.NIGHTLY = new Channel(
 
 // PUBLIC API
 
-exports.Channel = Channel
-exports.Context = Context
-exports.Driver = Driver
-exports.Options = Options
-exports.ServiceBuilder = ServiceBuilder
-exports.locateSynchronously = locateSynchronously
+module.exports = {
+  Channel,
+  Context,
+  Driver,
+  Options,
+  ServiceBuilder,
+  locateSynchronously,
+}

package/index.js

@@ -38,14 +38,13 @@ const safari = require('./safari')
 const session = require('./lib/session')
 const until = require('./lib/until')
 const webdriver = require('./lib/webdriver')
-const opera = require('./opera')
 
 const Browser = capabilities.Browser
 const Capabilities = capabilities.Capabilities
 const Capability = capabilities.Capability
 const WebDriver = webdriver.WebDriver
 
-var seleniumServer
+let seleniumServer
 
 /**
  * Starts an instance of the Selenium server if not yet running.
@@ -76,13 +75,12 @@ function startSeleniumServer(jar) {
  * @return {function(new: webdriver.WebDriver, ...?)}
  */
 function ensureFileDetectorsAreEnabled(ctor) {
-  const mixin = class extends ctor {
+  return class extends ctor {
     /** @param {input.FileDetector} detector */
-    setFileDetector(detector) {
+    setFileDetector (detector) {
       webdriver.WebDriver.prototype.setFileDetector.call(this, detector)
     }
   }
-  return mixin
 }
 
 /**
@@ -233,12 +231,6 @@ class Builder {
 
     /** @private {http.Agent} */
     this.agent_ = null
-
-    /** @private {opera.Options} */
-    this.operaOptions_ = null
-
-    /** @private {remote.DriverService.Builder} */
-    this.operaService_ = null
   }
 
   /**
@@ -433,20 +425,6 @@ class Builder {
     return this
   }
 
-  /**
-   * Sets Opera specific {@linkplain opera.Options options} for drivers
-   * created by this builder. Any logging or proxy settings defined on the given
-   * options will take precedence over those set through
-   * {@link #setLoggingPrefs} and {@link #setProxy}, respectively.
-   *
-   * @param {!opera.Options} options The OperaDriver options to use.
-   * @return {!Builder} A self reference.
-   */
-  setOperaOptions(options) {
-    this.operaOptions_ = options
-    return this
-  }
-
   /**
    * @return {chrome.Options} the Chrome specific options currently configured
    *     for this builder.
@@ -561,21 +539,6 @@ class Builder {
     return this
   }
 
-  /**
-   * Sets the {@link opera.ServiceBuilder} to use to manage the
-   * operaDriver child process when creating sessions locally.
-   *
-   * @param {opera.ServiceBuilder} service the service to use.
-   * @return {!Builder} a self reference.
-   */
-  setOperaService(service) {
-    if (service && !(service instanceof opera.ServiceBuilder)) {
-      throw TypeError('not a opera.ServiceBuilder object')
-    }
-    this.operaService_ = service
-    return this
-  }
-
   /**
    * Sets Safari specific {@linkplain safari.Options options} for drivers
    * created by this builder. Any logging settings defined on the given options
@@ -649,8 +612,6 @@ class Builder {
       capabilities.merge(this.safariOptions_)
     } else if (browser === Browser.EDGE && this.edgeOptions_) {
       capabilities.merge(this.edgeOptions_)
-    } else if (browser === Browser.OPERA && this.operaOptions_) {
-      capabilities.merge(this.operaOptions_)
     }
 
     checkOptions(
@@ -737,14 +698,6 @@ class Builder {
         return createDriver(edge.Driver, capabilities, service)
       }
 
-      case Browser.OPERA: {
-        let service = null
-        if (this.operaService_) {
-          service = this.operaService_.build()
-        }
-        return createDriver(opera.Driver, capabilities, service)
-      }
-
       case Browser.SAFARI:
         return createDriver(safari.Driver, capabilities)
 
@@ -821,6 +774,7 @@ exports.Browser = capabilities.Browser
 exports.Builder = Builder
 exports.Button = input.Button
 exports.By = by.By
+exports.RelativeBy = by.RelativeBy
 exports.withTagName = by.withTagName
 exports.locateWith = by.locateWith
 exports.Capabilities = capabilities.Capabilities

package/io/exec.js

@@ -76,7 +76,8 @@ class Result {
   }
 }
 
-const COMMAND_RESULT = /** !WeakMap<!Command, !Promise<!Result>> */ new WeakMap()
+const COMMAND_RESULT =
+  /** !WeakMap<!Command, !Promise<!Result>> */ new WeakMap()
 const KILL_HOOK = /** !WeakMap<!Command, function(string)> */ new WeakMap()
 
 /**

package/io/index.js

@@ -42,8 +42,6 @@ function checkedCall(fn) {
   })
 }
 
-// PUBLIC API
-
 /**
  * Recursively removes a directory and all of its contents. This is equivalent
  * to {@code rm -rf} on a POSIX system.
@@ -114,18 +112,18 @@ function copyDir(src, dst, opt_exclude) {
     files = files.filter(/** @type {function(string): boolean} */ (predicate))
   }
 
-  var results = []
+  const results = []
   files.forEach(function (file) {
-    var stats = fs.statSync(file)
-    var target = path.join(dst, path.basename(file))
+    const stats = fs.statSync(file)
+    const target = path.join(dst, path.basename(file))
 
     if (stats.isDirectory()) {
       if (!fs.existsSync(target)) {
         fs.mkdirSync(target, stats.mode)
       }
-      results.push(exports.copyDir(file, target, predicate))
+      results.push(copyDir(file, target, predicate))
     } else {
-      results.push(exports.copy(file, target))
+      results.push(copy(file, target))
     }
   })
 
@@ -137,7 +135,7 @@ function copyDir(src, dst, opt_exclude) {
  * @param {string} aPath The path to test.
  * @return {!Promise<boolean>} A promise for whether the file exists.
  */
-exports.exists = function (aPath) {
+function exists(aPath) {
   return new Promise(function (fulfill, reject) {
     let type = typeof aPath
     if (type !== 'string') {
@@ -153,7 +151,7 @@ exports.exists = function (aPath) {
  * @param {string} aPath The path to stat.
  * @return {!Promise<!fs.Stats>} A promise for the file stats.
  */
-exports.stat = function stat(aPath) {
+function stat(aPath) {
   return checkedCall((callback) => fs.stat(aPath, callback))
 }
 
@@ -335,15 +333,19 @@ function walkDir(rootPath) {
 }
 
 // PUBLIC API
-module.exports.walkDir = walkDir
-module.exports.rmDir = rmDir
-module.exports.mkdirp = mkdirp
-module.exports.mkdir = mkdir
-module.exports.write = write
-module.exports.read = read
-module.exports.findInPath = findInPath
-module.exports.tmpFile = tmpFile
-module.exports.tmpDir = tmpDir
-module.exports.unlink = unlink
-module.exports.copy = copy
-module.exports.copyDir = copyDir
+module.exports = {
+  walkDir,
+  rmDir,
+  mkdirp,
+  mkdir,
+  write,
+  read,
+  findInPath,
+  tmpFile,
+  tmpDir,
+  unlink,
+  copy,
+  copyDir,
+  exists,
+  stat,
+}

package/io/zip.js

@@ -218,6 +218,4 @@ function unzip(src, dst) {
 }
 
 // PUBLIC API
-module.exports.Zip = Zip
-module.exports.load = load
-module.exports.unzip = unzip
+module.exports = { Zip, load, unzip }

package/lib/by.js

@@ -225,7 +225,7 @@ class By {
    * @return {!By} The new locator.
    */
   static tagName(name) {
-    return By.css(name)
+    return new By('tag name', name)
   }
 
   /**
@@ -424,10 +424,10 @@ function check(locator) {
 // PUBLIC API
 
 module.exports = {
-  By: By,
-  RelativeBy: RelativeBy,
-  withTagName: withTagName,
-  locateWith: locateWith,
+  By,
+  RelativeBy,
+  withTagName,
+  locateWith,
+  escapeCss,
   checkedLocator: check,
-  escapeCss: escapeCss
 }

package/lib/capabilities.js

@@ -34,7 +34,6 @@ const Browser = {
   FIREFOX: 'firefox',
   INTERNET_EXPLORER: 'internet explorer',
   SAFARI: 'safari',
-  OPERA: 'opera',
 }
 
 /**
@@ -282,13 +281,6 @@ 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

@@ -83,7 +83,6 @@ class Command {
  * will support.
  * @enum {string}
  */
-// TODO: Delete obsolete command names.
 const Name = {
   GET_SERVER_STATUS: 'getStatus',
 
@@ -115,14 +114,9 @@ const Name = {
   CLEAR_ELEMENT: 'clearElement',
   CLICK_ELEMENT: 'clickElement',
   SEND_KEYS_TO_ELEMENT: 'sendKeysToElement',
-  SUBMIT_ELEMENT: 'submitElement',
 
   GET_CURRENT_WINDOW_HANDLE: 'getCurrentWindowHandle',
   GET_WINDOW_HANDLES: 'getWindowHandles',
-  GET_WINDOW_POSITION: 'getWindowPosition',
-  SET_WINDOW_POSITION: 'setWindowPosition',
-  GET_WINDOW_SIZE: 'getWindowSize',
-  SET_WINDOW_SIZE: 'setWindowSize',
   GET_WINDOW_RECT: 'getWindowRect',
   SET_WINDOW_RECT: 'setWindowRect',
   MAXIMIZE_WINDOW: 'maximizeWindow',
@@ -146,17 +140,14 @@ const Name = {
   IS_ELEMENT_SELECTED: 'isElementSelected',
   IS_ELEMENT_ENABLED: 'isElementEnabled',
   IS_ELEMENT_DISPLAYED: 'isElementDisplayed',
-  GET_ELEMENT_LOCATION: 'getElementLocation',
-  GET_ELEMENT_LOCATION_IN_VIEW: 'getElementLocationOnceScrolledIntoView',
   GET_ELEMENT_RECT: 'getElementRect',
-  GET_ELEMENT_SIZE: 'getElementSize',
   GET_ELEMENT_ATTRIBUTE: 'getElementAttribute',
+  GET_DOM_ATTRIBUTE: 'getDomAttribute',
   GET_ELEMENT_VALUE_OF_CSS_PROPERTY: 'getElementValueOfCssProperty',
   GET_ELEMENT_PROPERTY: 'getElementProperty',
 
   SCREENSHOT: 'screenshot',
   TAKE_ELEMENT_SCREENSHOT: 'takeElementScreenshot',
-  SET_SCRIPT_TIMEOUT: 'setScriptTimeout',
 
   PRINT_PAGE: 'printPage',
 
@@ -175,7 +166,6 @@ const Name = {
 
   GET_AVAILABLE_LOG_TYPES: 'getAvailableLogTypes',
   GET_LOG: 'getLog',
-  GET_SESSION_LOGS: 'getSessionLogs',
 
   // Non-standard commands used by the standalone Selenium server.
   UPLOAD_FILE: 'uploadFile',