selenium-webdriver 4.0.0-beta.3 → 4.0.0

package/CHANGES.md

@@ -1,3 +1,45 @@
+## 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)
+* Allow relativeby with findElement  (#9396)
+
 ## v4.0.0-beta.3
 
 * Removed support for legacy actions.

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/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)
+    )
   }
 }
 

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.
    *
@@ -549,6 +570,21 @@ class Options extends Capabilities {
     return this
   }
 
+  /**
+   * Sets a list of the window types that will appear when getting window
+   * handles. For access to <webview> elements, include "webview" in the list.
+   * @param {...(string|!Array<string>)} args The window types that will appear
+   * when getting window handles.
+   * @return {!Options} A self reference.
+   */
+  windowTypes(...args) {
+    let windowTypes = (this.options_.windowTypes || []).concat(...args)
+    if (windowTypes.length) {
+      this.options_.windowTypes = windowTypes
+    }
+    return this
+  }
+
   /**
    * Converts this instance to its JSON wire protocol representation. Note this
    * function is an implementation not intended for general use.
@@ -565,7 +601,7 @@ class Options extends Capabilities {
           return extension.toString('base64')
         }
         return io
-          .read(/** @type {string} */(extension))
+          .read(/** @type {string} */ (extension))
           .then((buffer) => buffer.toString('base64'))
       })
     }
@@ -618,7 +654,7 @@ class Driver extends webdriver.WebDriver {
    * implementation.
    * @override
    */
-  setFileDetector() { }
+  setFileDetector() {}
 
   /**
    * Schedules a command to launch Chrome App with given ID.

package/devtools/networkinterceptor.js

@@ -0,0 +1,89 @@
+// 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

@@ -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
 
@@ -88,12 +89,33 @@ class HttpClient {
      */
     this.options_ = getRequestOptions(serverUrl)
 
+    /**
+     * 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 +128,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)
@@ -232,7 +254,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,

package/ie.js

@@ -18,7 +18,7 @@
 /**
  * @fileoverview Defines a {@linkplain Driver WebDriver} client for Microsoft's
  * Internet Explorer. Before using the IEDriver, you must download the latest
- * [IEDriverServer](http://selenium-release.storage.googleapis.com/index.html)
+ * [IEDriverServer](https://www.selenium.dev/downloads/)
  * and place it on your
  * [PATH](http://en.wikipedia.org/wiki/PATH_%28variable%29). You must also apply
  * the system configuration outlined on the Selenium project
@@ -370,7 +370,7 @@ class Options extends Capabilities {
       behavior !== SCROLL_BEHAVIOUR.TOP &&
       behavior !== SCROLL_BEHAVIOUR.BOTTOM
     ) {
-      throw new error.InvalidArgumentError(`Element Scroll Behavior out of range. 
+      throw new error.InvalidArgumentError(`Element Scroll Behavior out of range.
       It should be either ${SCROLL_BEHAVIOUR.TOP} or ${SCROLL_BEHAVIOUR.BOTTOM}`)
     }
     this.options_[Key.ELEMENT_SCROLL_BEHAVIOR] = behavior
@@ -402,9 +402,9 @@ function createServiceFromCapabilities(capabilities) {
   if (!exe || !fs.existsSync(exe)) {
     throw Error(
       `${IEDRIVER_EXE} could not be found on the current PATH. Please ` +
-        `download the latest version of ${IEDRIVER_EXE} from ` +
-        'http://selenium-release.storage.googleapis.com/index.html and ' +
-        'ensure it can be found on your system PATH.'
+      `download the latest version of ${IEDRIVER_EXE} from ` +
+      'https://www.selenium.dev/downloads/ and ' +
+      'ensure it can be found on your system PATH.'
     )
   }
 
@@ -478,9 +478,9 @@ class Driver extends webdriver.WebDriver {
     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()
-    ))
+    return /** @type {!Driver} */ (
+      super.createSession(executor, options, () => service.kill())
+    )
   }
 
   /**

package/index.js

@@ -103,7 +103,7 @@ function ensureFileDetectorsAreEnabled(ctor) {
  */
 class ThenableWebDriver {
   /** @param {...?} args */
-  static createSession(...args) {} // eslint-disable-line
+  static createSession(...args) { } // eslint-disable-line
 }
 
 /**
@@ -162,7 +162,7 @@ function createDriver(ctor, ...args) {
  *   option always takes precedence over {@code SELENIUM_SERVER_JAR}.
  *
  * - {@code SELENIUM_SERVER_JAR}: defines the path to the
- *   <a href="http://selenium-release.storage.googleapis.com/index.html">
+ *   <a href="https://www.selenium.dev/downloads/">
  *   standalone Selenium server</a> jar to use. The server will be started the
  *   first time a WebDriver instance and be killed when the process exits.
  *
@@ -318,6 +318,8 @@ class Builder {
   }
 
   /**
+   * Recommended way is to use set*Options where * is the browser(eg setChromeOptions)
+   *
    * Sets the desired capabilities when requesting a new session. This will
    * overwrite any previously set capabilities.
    * @param {!(Object|Capabilities)} capabilities The desired capabilities for
@@ -337,6 +339,19 @@ class Builder {
   getCapabilities() {
     return this.capabilities_
   }
+  
+  /**
+   * Sets the desired capability when requesting a new session. 
+   * If there is already a capability named key, its value will be overwritten with value. 
+   * This is a convenience wrapper around builder.getCapabilities().set(key, value) to support Builder method chaining.
+   * @param {string} key The capability key.
+   * @param {*} value The capability value.
+   * @return {!Builder} A self reference.
+   */
+  setCapability(key, value) {
+    this.capabilities_.set(key, value)
+    return this
+  }
 
   /**
    * Configures the target browser for clients created by this instance.
@@ -615,7 +630,7 @@ class Builder {
     if (typeof browser !== 'string') {
       throw TypeError(
         `Target browser must be a string, but is <${typeof browser}>;` +
-          ' did you forget to call forBrowser()?'
+        ' did you forget to call forBrowser()?'
       )
     }
 
@@ -736,8 +751,8 @@ class Builder {
       default:
         throw new Error(
           'Do not know how to build driver: ' +
-            browser +
-            '; did you forget to call usingServer(url)?'
+          browser +
+          '; did you forget to call usingServer(url)?'
         )
     }
   }
@@ -793,9 +808,9 @@ function checkOptions(caps, key, optionType, setMethod) {
   if (val instanceof optionType) {
     throw new error.InvalidArgumentError(
       'Options class extends Capabilities and should not be set as key ' +
-        `"${key}"; set browser-specific options with ` +
-        `Builder.${setMethod}(). For more information, see the ` +
-        'documentation attached to the function that threw this error'
+      `"${key}"; set browser-specific options with ` +
+      `Builder.${setMethod}(). For more information, see the ` +
+      'documentation attached to the function that threw this error'
     )
   }
 }
@@ -807,6 +822,7 @@ exports.Builder = Builder
 exports.Button = input.Button
 exports.By = by.By
 exports.withTagName = by.withTagName
+exports.withLocator = by.withLocator
 exports.Capabilities = capabilities.Capabilities
 exports.Capability = capabilities.Capability
 exports.Condition = webdriver.Condition

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()
 
 /**