selenium-webdriver 4.0.0-beta.4 → 4.1.0

package/CHANGES.md

@@ -1,3 +1,57 @@
+## v4.1.0
+
+* add support for handling Shadow DOM elements
+* Capture browser console logs when using BiDi onLogEvent api
+* add CDP support for v96 and remove v93
+* remove useless package, change io public api import to more common approach (#10037)
+* Fix flaky CDP dom mutation (#10029)
+* Fix edge test failures (#10012)
+* code cleanup second iteration (#9979)
+* Ensure correct serialization of extensions in chromium.Options (#6676)
+* Remove explicit id passing for CDP commands
+* Attach to page target while creating a CDP connection (#10005)
+* Add support for form submit in W3C mode (fixes #9916) (#9936)
+* Fixes relative locator 'locateWith' export
+* update doc string for CDP Commands (#9929)
+
+
+## v4.0.0
+
+* Fixes cdp for Chrome and Firefox (#9909)
+* Add cdp 95 to python and JS
+* Removing unused target for cdpConnection
+
+
+## v4.0.0-rc-2
+
+* Fix builder test
+* Allow builder to set a single arbitrary capability (#9857)
+* Restore withCapabilities() to ensure backward compatibility
+* Add new websocketUrl capability
+* update ruby, python and JS to add support for v94 and remove support for v92
+* Add a check for Grid CDP endpoint
+* Implement network request interceptions
+* Update connections to devtools so it works in Firefox and Chrome
+
+## v4.0.0-rc-1
+
+* Deprecates withCapabilities method and removes tests (#9701)
+* expose `withLocator` method at the top level
+* Enables Mobile feature for Firefox (Still need to expand this to chromium based browsers)
+
+* Add the ability to do Relative Locators with all By types. Fixes #9559
+* Add default Opera capabilities. Fixes #9654
+* Add support for ChromeDriver `--enable-chrome-logs` (#9575) [Author: Mark Stacey]
+
+  The `--enable-chrome-logs` ChromeDriver option can now be enabled using
+  the Chromium (or Chrome) ServiceBuilder, similarly to the other options
+  provided by ChromeDriver.
+
+* Add the debuggerAddress option to chromium.js (#9561) [Author: Brandon Walderman]
+* Adds http client options (#9638)[Author: Dharin Shah]
+* Updating edge.js to extend chromium.driver (fixes #9626)
+
+
 ## v4.0.0-beta.4
 
 * Add windowTypes option support for ChromiumDriver (#7897)
@@ -479,7 +533,7 @@ This release requires [geckodriver 0.15.0](https://github.com/mozilla/geckodrive
   DriverService instances that run in a child-process. The
   `chrome.ServiceBuilder`, `edge.ServiceBuilder`, and `opera.ServiceBuilder`
   classes now all extend this base class with browser-specific options.
-* For each of the ServiceBuilder clases, renamed `usingPort` and
+* For each of the ServiceBuilder classes, renamed `usingPort` and
   `withEnvironment` to `setPort` and `setEnvironment`, respectively.
 * Renamed `chrome.ServiceBuilder#setUrlBasePath` to `#setPath`
 * Changed the signature of the `firefox.Driver` from `(config, flow, executor)`

package/README.md

@@ -223,7 +223,9 @@ under the License.
 [edge]: http://go.microsoft.com/fwlink/?LinkId=619687
 [geckodriver]: https://github.com/mozilla/geckodriver/releases/
 [reduction]: http://www.webkit.org/quality/reduction.html
-[release]: http://selenium-release.storage.googleapis.com/index.html
+
+[release]: https://www.selenium.dev/downloads/
+
 [users]: https://groups.google.com/forum/#!forum/selenium-users
 [safaridriver]: https://developer.apple.com/library/prerelease/content/releasenotes/General/WhatsNewInSafari/Articles/Safari_10_0.html#//apple_ref/doc/uid/TP40014305-CH11-DontLinkElementID_28
-[operadriver]: https://github.com/operasoftware/operachromiumdriver/releases
+[operadriver]: https://github.com/operasoftware/operachromiumdriver/releases

package/chromium.js

@@ -213,6 +213,14 @@ class ServiceBuilder extends remote.DriverService.Builder {
     return this.addArguments('--log-path=' + path)
   }
 
+  /**
+   * Enables Chrome logging.
+   * @returns {!ServiceBuilder} A self reference.
+   */
+   enableChromeLogging() {
+    return this.addArguments('--enable-chrome-logs');
+  }
+
   /**
    * Enables verbose logging.
    * @return {!ServiceBuilder} A self reference.
@@ -275,6 +283,19 @@ class Options extends Capabilities {
     return this
   }
 
+  /**
+   * Sets the address of a Chromium remote debugging server to connect to.
+   * Address should be of the form "{hostname|IP address}:port"
+   * (e.g. "localhost:9222").
+   *
+   * @param {string} address The address to connect to.
+   * @return {!Options} A self reference.
+   */
+  debuggerAddress(address) {
+    this.options_.debuggerAddress = address;
+    return this
+  }
+
   /**
    * Configures the driver to start the browser in headless mode.
    *
@@ -337,8 +358,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
   }
 
@@ -557,35 +581,53 @@ class Options extends Capabilities {
    * @return {!Options} A self reference.
    */
   windowTypes(...args) {
-    let windowTypes = (this.options_.windowTypes || []).concat(...args);
+    let windowTypes = (this.options_.windowTypes || []).concat(...args)
     if (windowTypes.length) {
-      this.options_.windowTypes = windowTypes;
+      this.options_.windowTypes = windowTypes
     }
-    return this;
+    return this
   }
+}
 
+/**
+ * A list of extensions to install when launching the browser.
+ */
+class Extensions {
+  constructor() {
+    this.extensions = []
+  }
+
+  /**
+   * @return {number} The length of the extensions list.
+   */
+  get length() {
+    return this.extensions.length
+  }
 
   /**
-   * Converts this instance to its JSON wire protocol representation. Note this
-   * function is an implementation not intended for general use.
+   * 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'))
+    })
   }
 }
 
@@ -634,7 +676,7 @@ class Driver extends webdriver.WebDriver {
    * implementation.
    * @override
    */
-  setFileDetector() { }
+  setFileDetector() {}
 
   /**
    * Schedules a command to launch Chrome App with given ID.
@@ -705,11 +747,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/>
    */

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

@@ -0,0 +1,88 @@
+// Licensed to the Software Freedom Conservancy (SFC) under one
+// or more contributor license agreements.  See the NOTICE file
+// distributed with this work for additional information
+// regarding copyright ownership.  The SFC licenses this file
+// to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance
+// with the License.  You may obtain a copy of the License at
+//
+//   http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing,
+// software distributed under the License is distributed on an
+// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+// KIND, either express or implied.  See the License for the
+// specific language governing permissions and limitations
+// 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
+  }
+
+  /**
+   * 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
+  }
+
+  /**
+   * 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
+  }
+
+  /**
+   * 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')
+  }
+
+  /**
+   * 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

@@ -80,8 +80,6 @@
 const { Browser } = require('./lib/capabilities')
 const io = require('./io')
 const chromium = require('./chromium')
-const http = require('./http')
-const webdriver = require('./lib/webdriver')
 
 /**
  * Name of the EdgeDriver executable.
@@ -111,10 +109,10 @@ class ServiceBuilder extends chromium.ServiceBuilder {
     let exe = opt_exe || locateSynchronously()
     if (!exe) {
       throw Error(
-        `The WebDriver for Edge could not be found on the current PATH. Please download the `+
-        `latest version of ${EDGEDRIVER_CHROMIUM_EXE} from `+
-        `https://developer.microsoft.com/en-us/microsoft-edge/tools/webdriver/ `+
-        `and ensure it can be found on your PATH.`
+        `The WebDriver for Edge could not be found on the current PATH. Please download the ` +
+          `latest version of ${EDGEDRIVER_CHROMIUM_EXE} from ` +
+          `https://developer.microsoft.com/en-us/microsoft-edge/tools/webdriver/ ` +
+          `and ensure it can be found on your PATH.`
       )
     }
     super(exe)
@@ -143,24 +141,20 @@ class Options extends chromium.Options {
 /**
  * Creates a new WebDriver client for Microsoft's Edge.
  */
-class Driver extends webdriver.WebDriver {
+class Driver extends chromium.Driver {
   /**
    * Creates a new browser session for Microsoft's Edge browser.
    *
-   * @param {(Capabilities|Options)=} options The configuration options.
-   * @param {remote.DriverService=} opt_service The service to use; will create
+   * @param {(Capabilities|Options)=} opt_config The configuration options.
+   * @param {remote.DriverService=} opt_serviceExecutor The service to use; will create
    *     a new Legacy or Chromium service based on {@linkplain Options} by default.
    * @return {!Driver} A new driver instance.
    */
-  static createSession(options, opt_service) {
-    options = options || new Options()
-    let service = opt_service || getDefaultService()
-    let client = service.start().then((url) => new http.HttpClient(url))
-    let executor = new http.Executor(client)
-
-    return /** @type {!Driver} */ (super.createSession(executor, options, () =>
-      service.kill()
-    ))
+  static createSession(opt_config, opt_serviceExecutor) {
+    let caps = opt_config || new Options()
+    return /** @type {!Driver} */ (
+      super.createSession(caps, opt_serviceExecutor)
+    )
   }
 
   /**
@@ -180,7 +174,7 @@ function setDefaultService(service) {
   if (defaultService && defaultService.isRunning()) {
     throw Error(
       'The previously configured EdgeDriver service is still running. ' +
-      'You must shut it down before you may adjust its configuration.'
+        'You must shut it down before you may adjust its configuration.'
     )
   }
   defaultService = service
@@ -199,7 +193,6 @@ function getDefaultService() {
   return defaultService
 }
 
-
 /**
  * _Synchronously_ attempts to locate the chromedriver executable on the current
  * system.
@@ -213,6 +206,7 @@ function locateSynchronously() {
 Options.prototype.BROWSER_NAME_VALUE = Browser.EDGE
 Options.prototype.CAPABILITY_KEY = 'ms:edgeOptions'
 Driver.prototype.VENDOR_CAPABILITY_PREFIX = 'ms'
+Driver.getDefaultService = getDefaultService
 
 // PUBLIC API
 

package/firefox.js

@@ -124,7 +124,6 @@ const io = require('./io')
 const remote = require('./remote')
 const webdriver = require('./lib/webdriver')
 const zip = require('./io/zip')
-const cdp = require('./devtools/CDPConnection')
 const { Browser, Capabilities } = require('./lib/capabilities')
 const { Zip } = require('./io/zip')
 
@@ -394,6 +393,31 @@ class Options extends Capabilities {
     }
     throw TypeError('binary must be a string path or Channel object')
   }
+
+  /**
+   * Enables Mobile start up features
+   *
+   * @param {string} androidPackage The package to use
+   * @return {!Options} A self reference
+   */
+  enableMobile(androidPackage = "org.mozilla.firefox", androidActivity = null, deviceSerial = null) {
+    this.firefoxOptions_().androidPackage = androidPackage
+
+    if (androidActivity) {
+      this.firefoxOptions_().androidActivity = androidActivity
+    }
+    if (deviceSerial) {
+      this.firefoxOptions_().deviceSerial = deviceSerial
+    }
+    return this
+  }
+
+  /**
+   * Enables moz:debuggerAddress for firefox cdp
+   */
+  enableDebugger() {
+    return this.set('moz:debuggerAddress', true)
+  }
 }
 
 /**

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.
@@ -77,8 +77,9 @@ class HttpClient {
    *     Defaults to `http.globalAgent`.
    * @param {?string=} opt_proxy The proxy to use for the connection to the
    *     server. Default is to use no proxy.
+   * @param {?Object.<string,Object>} client_options
    */
-  constructor(serverUrl, opt_agent, opt_proxy) {
+  constructor(serverUrl, opt_agent, opt_proxy, client_options = {}) {
     /** @private {http.Agent} */
     this.agent_ = opt_agent || null
 
@@ -89,11 +90,30 @@ class HttpClient {
     this.options_ = getRequestOptions(serverUrl)
 
     /**
-     * @private {?RequestOptions}
+     * client options, header overrides
      */
+    this.client_options = client_options
+
+    /**
+     * sets keep-alive for the agent
+     * see https://stackoverflow.com/a/58332910
+     */
+    this.keepAlive = this.client_options['keep-alive']
+
+    /**  @private {?RequestOptions} */
     this.proxyOptions_ = opt_proxy ? getRequestOptions(opt_proxy) : null
   }
 
+  get keepAlive() {
+    return this.agent_.keepAlive
+  }
+
+  set keepAlive(value) {
+    if (value === 'true' || value === true) {
+      this.agent_.keepAlive = true
+    }
+  }
+
   /** @override */
   send(httpRequest) {
     let data
@@ -106,7 +126,7 @@ class HttpClient {
       })
     }
 
-    headers['User-Agent'] = USER_AGENT
+    headers['User-Agent'] = this.client_options['user-agent'] || USER_AGENT
     headers['Content-Length'] = 0
     if (httpRequest.method == 'POST' || httpRequest.method == 'PUT') {
       data = JSON.stringify(httpRequest.data)
@@ -197,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(
@@ -218,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',
@@ -232,7 +253,7 @@ function sendRequest(options, onOk, onError, opt_data, opt_proxy, opt_retries) {
           hash: location.hash,
           headers: {
             Accept: 'application/json; charset=utf-8',
-            'User-Agent': USER_AGENT,
+            'User-Agent': options.headers['User-Agent'] || USER_AGENT,
           },
         },
         onOk,
@@ -243,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, '')
@@ -266,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
       }
@@ -317,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

package/http/util.js

@@ -21,12 +21,12 @@
 
 'use strict'
 
-const Executor = require('./index').Executor,
-  HttpClient = require('./index').HttpClient,
-  HttpRequest = require('./index').Request,
-  Command = require('../lib/command').Command,
-  CommandName = require('../lib/command').Name,
-  error = require('../lib/error')
+const Executor = require('./index').Executor
+const HttpClient = require('./index').HttpClient
+const HttpRequest = require('./index').Request
+const Command = require('../lib/command').Command
+const CommandName = require('../lib/command').Name
+const error = require('../lib/error')
 
 /**
  * Queries a WebDriver server for its current status.
@@ -43,18 +43,6 @@ function getStatus(url) {
 
 class CancellationError {}
 
-// PUBLIC API
-
-/**
- * Queries a WebDriver server for its current status.
- * @param {string} url Base URL of the server to query.
- * @return {!Promise<!Object>} A promise that resolves with
- *     a hash of the server status.
- */
-exports.getStatus = getStatus
-
-exports.CancellationError = CancellationError
-
 /**
  * Waits for a WebDriver server to be healthy and accepting requests.
  * @param {string} url Base URL of the server to query.
@@ -65,7 +53,7 @@ exports.CancellationError = CancellationError
  * @return {!Promise} A promise that will resolve when the server is ready, or
  *     if the wait is cancelled.
  */
-exports.waitForServer = function (url, timeout, opt_cancelToken) {
+function waitForServer(url, timeout, opt_cancelToken) {
   return new Promise((onResolve, onReject) => {
     let start = Date.now()
 
@@ -120,7 +108,7 @@ exports.waitForServer = function (url, timeout, opt_cancelToken) {
  * @return {!Promise} A promise that will resolve when a 2xx is received from
  *     the given URL, or if the wait is cancelled.
  */
-exports.waitForUrl = function (url, timeout, opt_cancelToken) {
+function waitForUrl(url, timeout, opt_cancelToken) {
   return new Promise((onResolve, onReject) => {
     let client = new HttpClient(url)
     let request = new HttpRequest('GET', '')
@@ -170,3 +158,9 @@ exports.waitForUrl = function (url, timeout, opt_cancelToken) {
     }
   })
 }
+
+// PUBLIC API
+module.exports.getStatus = getStatus
+module.exports.CancellationError = CancellationError
+module.exports.waitForServer = waitForServer
+module.exports.waitForUrl = waitForUrl