selenium-webdriver 4.0.0 → 4.1.2

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

@@ -286,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
   }
 
@@ -358,8 +371,11 @@ class Options extends Capabilities {
    * @return {!Options} A self reference.
    */
   addExtensions(...args) {
-    let current = this.options_.extensions || []
-    this.options_.extensions = current.concat(...args)
+    let extensions = this.options_.extensions || new Extensions()
+    extensions.add(...args)
+    if (extensions.length) {
+      this.options_.extensions = extensions
+    }
     return this
   }
 
@@ -584,28 +600,47 @@ class Options extends Capabilities {
     }
     return this
   }
+}
+
+/**
+ * A list of extensions to install when launching the browser.
+ */
+class Extensions {
+  constructor() {
+    this.extensions = []
+  }
 
   /**
-   * Converts this instance to its JSON wire protocol representation. Note this
-   * function is an implementation not intended for general use.
+   * @return {number} The length of the extensions list.
+   */
+  get length() {
+    return this.extensions.length
+  }
+
+  /**
+   * Add additional extensions to install when launching the browser. Each
+   * extension should be specified as the path to the packed CRX file, or a
+   * Buffer for an extension.
    *
-   * @return {!Object} The JSON wire protocol representation of this instance.
-   * @suppress {checkTypes} Suppress [] access on a struct.
+   * @param {...(string|!Buffer|!Array<(string|!Buffer)>)} args The
+   *     extensions to add.
+   */
+  add(...args) {
+    this.extensions = this.extensions.concat(...args)
+  }
+
+  /**
+   * @return {!Object} A serialized representation of this Extensions object.
    */
   [Symbols.serialize]() {
-    if (this.options_.extensions && this.options_.extensions.length) {
-      this.options_.extensions = this.options_.extensions.map(function (
-        extension
-      ) {
-        if (Buffer.isBuffer(extension)) {
-          return extension.toString('base64')
-        }
-        return io
-          .read(/** @type {string} */ (extension))
-          .then((buffer) => buffer.toString('base64'))
-      })
-    }
-    return super[Symbols.serialize]()
+    return this.extensions.map(function (extension) {
+      if (Buffer.isBuffer(extension)) {
+        return extension.toString('base64')
+      }
+      return io
+        .read(/** @type {string} */ (extension))
+        .then((buffer) => buffer.toString('base64'))
+    })
   }
 }
 
@@ -626,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
@@ -646,7 +679,7 @@ class Driver extends webdriver.WebDriver {
       }
     }
 
-    return /** @type {!Driver} */ (super.createSession(executor, caps, onQuit))
+    return /** @type {!Driver} */ (super.createSession(executor, caps))
   }
 
   /**
@@ -677,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.
    *
@@ -725,11 +767,11 @@ class Driver extends webdriver.WebDriver {
   }
 
   /**
-   * ends an arbitrary devtools command to the browser and get the result.
+   * Sends an arbitrary devtools command to the browser and get the result.
    *
    * @param {string} cmd The name of the command to send.
    * @param {Object=} params The command parameters.
-   * @return {!Promise<void>} A promise that will be resolved when the command
+   * @return {!Promise<string>} A promise that will be resolved when the command
    *     has finished.
    * @see <https://chromedevtools.github.io/devtools-protocol/>
    */
@@ -811,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.
    *
@@ -860,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/devtools/CDPConnection.js

@@ -18,16 +18,21 @@
 class CDPConnection {
   constructor(wsConnection) {
     this._wsConnection = wsConnection
+    this.cmd_id = 0
+    this.targetID = null;
+    this.sessionId = null
   }
 
-  execute(method, id, params, callback) {
-    const message = {
+  execute(method, params, callback) {
+    let message = {
       method,
-      id: id,
+      id: this.cmd_id++,
+    }
+    if (this.sessionId) {
+      message['sessionId'] = this.sessionId
     }
 
     const mergedMessage = Object.assign({ params: params }, message)
-
     this._wsConnection.send(JSON.stringify(mergedMessage), callback)
   }
 }

package/devtools/networkinterceptor.js

@@ -16,74 +16,73 @@
 // under the License.
 
 class HttpResponse {
-    /**
-     * Creates a HTTP Response that will be used to
-     * mock out network interceptions.
-     * @param {*} urlToIntercept
-     */
-    constructor(urlToIntercept = "") {
-        this.returnBody = ""
-        this.returnHeaders = []
-        this.returnMethod = "GET"
-        this.returnStatus = 200
-        this.urlToIntercept = urlToIntercept
-    }
+  /**
+   * Creates a HTTP Response that will be used to
+   * mock out network interceptions.
+   * @param {*} urlToIntercept
+   */
+  constructor(urlToIntercept = '') {
+    this.returnBody = ''
+    this.returnHeaders = []
+    this.returnMethod = 'GET'
+    this.returnStatus = 200
+    this.urlToIntercept = urlToIntercept
+  }
 
-    /**
-     * Add headers that will be returned when we intercept
-     * a HTTP Request
-     * @param {*} header
-     * @param {*} value
-     */
-    addHeaders(header, value) {
-        this.returnHeaders.push({ name: header, value: value })
-    }
+  /**
+   * Add headers that will be returned when we intercept
+   * a HTTP Request
+   * @param {*} header
+   * @param {*} value
+   */
+  addHeaders(header, value) {
+    this.returnHeaders.push({ name: header, value: value })
+  }
 
-    get headers() {
-        return this.returnHeaders
-    }
+  get headers() {
+    return this.returnHeaders
+  }
 
-    /**
-     * Set the STATUS value of the returned HTTP Request
-     * @param {*} value
-     */
-    set status(value) {
-        // Add in check that his should be a number
-        this.returnStatus = value
-    }
+  /**
+   * Set the STATUS value of the returned HTTP Request
+   * @param {*} value
+   */
+  set status(value) {
+    // Add in check that his should be a number
+    this.returnStatus = value
+  }
 
-    get status() {
-        return this.returnStatus
-    }
+  get status() {
+    return this.returnStatus
+  }
 
-    /**
-     * Sets the value of the body of the HTTP Request that
-     * will be returned.
-     * @param {*} value
-     */
-    set body(value) {
-        this.returnBody = value
-    }
+  /**
+   * Sets the value of the body of the HTTP Request that
+   * will be returned.
+   * @param {*} value
+   */
+  set body(value) {
+    this.returnBody = value
+  }
 
-    get body() {
-        let buff = Buffer.from(this.returnBody, "utf-8")
-        return buff.toString("base64")
-    }
+  get body() {
+    let buff = Buffer.from(this.returnBody, 'utf-8')
+    return buff.toString('base64')
+  }
 
-    /**
-     * Sets the method of the HTTP Request
-     * @param {*} value the method of the request.
-     */
-    set method(value) {
-        this.returnMethod = value
-    }
-
-    /**
-     * Returns the Method to be used in the intercept
-     */
-    get method() {
-        return this.returnMethod
-    }
+  /**
+   * Sets the method of the HTTP Request
+   * @param {*} value the method of the request.
+   */
+  set method(value) {
+    this.returnMethod = value
+  }
 
+  /**
+   * Returns the Method to be used in the intercept
+   */
+  get method() {
+    return this.returnMethod
+  }
 }
 exports.HttpResponse = HttpResponse

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/http/index.js

@@ -37,7 +37,7 @@ const httpLib = require('../lib/http')
  *            path: (?string|undefined),
  *            pathname: (?string|undefined)}}
  */
-var RequestOptions // eslint-disable-line
+let RequestOptions // eslint-disable-line
 
 /**
  * @param {string} aUrl The request URL to parse.
@@ -100,9 +100,7 @@ class HttpClient {
      */
     this.keepAlive = this.client_options['keep-alive']
 
-    /**
-     * @private {?RequestOptions}
-     */
+    /**  @private {?RequestOptions} */
     this.proxyOptions_ = opt_proxy ? getRequestOptions(opt_proxy) : null
   }
 
@@ -219,9 +217,10 @@ function sendRequest(options, onOk, onError, opt_data, opt_proxy, opt_retries) {
   let requestFn = options.protocol === 'https:' ? https.request : http.request
   var request = requestFn(options, function onResponse(response) {
     if (response.statusCode == 302 || response.statusCode == 303) {
+      let location
       try {
         // eslint-disable-next-line node/no-deprecated-api
-        var location = url.parse(response.headers['location'])
+        location = url.parse(response.headers['location'])
       } catch (ex) {
         onError(
           Error(
@@ -240,7 +239,7 @@ function sendRequest(options, onOk, onError, opt_data, opt_proxy, opt_retries) {
         location.auth = options.auth
       }
 
-      request.abort()
+      request.destroy()
       sendRequest(
         {
           method: 'GET',
@@ -265,10 +264,10 @@ function sendRequest(options, onOk, onError, opt_data, opt_proxy, opt_retries) {
       return
     }
 
-    var body = []
+    const body = []
     response.on('data', body.push.bind(body))
     response.on('end', function () {
-      var resp = new httpLib.Response(
+      const resp = new httpLib.Response(
         /** @type {number} */ (response.statusCode),
         /** @type {!Object<string>} */ (response.headers),
         Buffer.concat(body).toString('utf8').replace(/\0/g, '')
@@ -288,7 +287,7 @@ function sendRequest(options, onOk, onError, opt_data, opt_proxy, opt_retries) {
         sendRequest(options, onOk, onError, opt_data, opt_proxy, opt_retries)
       }, 15)
     } else {
-      var message = e.message
+      let message = e.message
       if (e.code) {
         message = e.code + ' ' + message
       }
@@ -339,8 +338,8 @@ function isRetryableNetworkError(err) {
 
 // PUBLIC API
 
-exports.Agent = http.Agent
-exports.Executor = httpLib.Executor
-exports.HttpClient = HttpClient
-exports.Request = httpLib.Request
-exports.Response = httpLib.Response
+module.exports.Agent = http.Agent
+module.exports.Executor = httpLib.Executor
+module.exports.HttpClient = HttpClient
+module.exports.Request = httpLib.Request
+module.exports.Response = httpLib.Response