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

package/CHANGES.md

@@ -1,3 +1,49 @@
+## 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.
+  This will also remove "Bride Mode" support, which was introduced to translate of action class to legacy API.
+* Remove devtools support for v86,v87 and adding support for v89, v90, v91
+* make isPromise() return boolean value for null and undefined cases (#6785)
+* code cleanup  (#9158)
+* replacing asserts equal with strictEqual and deepEqual with deepStrictEqual
+
+
+## v4.0.0-beta.2
+
+* Removed support for Edge legacy.
+* Make the build silent for WebDriver Bidi generated code
+* resolve file path correctly (#9223)
+* Update example in edge.js (#9231)
+* Use a flat namespace for selenium options for finding WebDriver Bidi endpoint
+* Removing duplicate license text updated by update_copyright.js
+* Updating copyright text
+* Minor code cleanup
+* Removing duplicate variable declaration of IE from capabilities
+
 ## v4.0.0-beta.1
 
 * JS Binding support for WebDriver Bidi in Firefox

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/CDPConnection.js

@@ -1,21 +1,19 @@
-/*
- * 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.
- */
+// 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 CDPConnection {
   constructor(wsConnection) {

package/edge.js

@@ -17,23 +17,19 @@
 
 /**
  * @fileoverview Defines a {@linkplain Driver WebDriver} client for
- * Microsoft's Edge web browser. Both Edge (Chromium), and Edge Legacy (EdgeHTML) are
- * supported. Before using this module, you must download and install the correct
- * [WebDriver](https://developer.microsoft.com/en-us/microsoft-edge/tools/webdriver/)
- * server.
+ * Microsoft's Edge web browser. Edge (Chromium) is supported and support
+ * for Edge Legacy (EdgeHTML) as part of https://github.com/SeleniumHQ/selenium/issues/9166.
+ * Before using this module, you must download and install the correct
+ * [WebDriver](https://developer.microsoft.com/en-us/microsoft-edge/tools/webdriver/) server.
  *
- * Ensure that the either MicrosoftWebDriver (EdgeHTML) or msedgedriver (Chromium)
- * is on your [PATH](http://en.wikipedia.org/wiki/PATH_%28variable%29). MicrosoftWebDriver
- * and Edge Legacy (EdgeHTML) will be used by default.
+ * Ensure that the msedgedriver (Chromium)
+ * is on your [PATH](http://en.wikipedia.org/wiki/PATH_%28variable%29).
  *
- * You may use {@link Options} to specify whether Edge Chromium should be used:
+ * You may use {@link Options} to specify whether Edge Chromium options should be used:
 
- *     var options = new edge.Options();
- *     options.useEdgeChromium(true);
- *     // configure browser options ...
+ *     const edge = require('selenium-webdriver/edge');
+ *     const options = new edge.Options();
 
- * Note that Chromium-specific {@link Options} will be ignored when using Edge Legacy.
- *
  * There are three primary classes exported by this module:
  *
  * 1. {@linkplain ServiceBuilder}: configures the
@@ -60,134 +56,115 @@
  * You may also create a {@link Driver} with its own driver service. This is
  * useful if you need to capture the server's log output for a specific session:
  *
- *     var edge = require('selenium-webdriver/edge');
+ *     const edge = require('selenium-webdriver/edge');
  *
- *     var service = new edge.ServiceBuilder()
+ *     const service = new edge.ServiceBuilder()
  *         .setPort(55555)
  *         .build();
  *
- *     var options = new edge.Options();
+ *     let options = new edge.Options();
  *     // configure browser options ...
  *
- *     var driver = edge.Driver.createSession(options, service);
+ *     let driver = edge.Driver.createSession(options, service);
  *
  * Users should only instantiate the {@link Driver} class directly when they
  * need a custom driver service configuration (as shown above). For normal
- * operation, users should start MicrosoftEdge using the
+ * operation, users should start msedgedriver using the
  * {@link ./builder.Builder selenium-webdriver.Builder}.
  *
- * [WebDriver (EdgeHTML)]: https://docs.microsoft.com/en-us/microsoft-edge/webdriver
  * [WebDriver (Chromium)]: https://docs.microsoft.com/en-us/microsoft-edge/webdriver-chromium
  */
 
 'use strict'
 
-const http = require('./http')
+const { Browser } = require('./lib/capabilities')
 const io = require('./io')
-const webdriver = require('./lib/webdriver')
-const { Browser, Capabilities } = require('./lib/capabilities')
 const chromium = require('./chromium')
 
-const EDGE_CHROMIUM_BROWSER_NAME = 'msedge'
-const EDGEDRIVER_LEGACY_EXE = 'MicrosoftWebDriver.exe'
+/**
+ * Name of the EdgeDriver executable.
+ * @type {string}
+ * @const
+ */
 const EDGEDRIVER_CHROMIUM_EXE =
   process.platform === 'win32' ? 'msedgedriver.exe' : 'msedgedriver'
 
+/** @type {remote.DriverService} */
+let defaultService = null
+
 /**
- * _Synchronously_ attempts to locate the Edge driver executable
- * on the current system. Searches for the legacy MicrosoftWebDriver by default.
- *
- * @param {string=} browserName Name of the Edge driver executable to locate.
- *   May be either 'msedge' to locate the Edge Chromium driver, or 'MicrosoftEdge' to
- *   locate the Edge Legacy driver. If omitted, will attempt to locate Edge Legacy.
- * @return {?string} the located executable, or `null`.
+ * Creates {@link selenium-webdriver/remote.DriverService} instances that manage
+ * a [ChromeDriver](https://chromedriver.chromium.org/)
+ * server in a child process.
  */
-function locateSynchronously(browserName) {
-  browserName = browserName || Browser.EDGE
-
-  if (browserName === EDGE_CHROMIUM_BROWSER_NAME) {
-    return io.findInPath(EDGEDRIVER_CHROMIUM_EXE, true)
+class ServiceBuilder extends chromium.ServiceBuilder {
+  /**
+   * @param {string=} opt_exe Path to the server executable to use. If omitted,
+   *     the builder will attempt to locate the msedgedriver on the current
+   *     PATH.
+   * @throws {Error} If provided executable does not exist, or the msedgedriver
+   *     cannot be found on the PATH.
+   */
+  constructor(opt_exe) {
+    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.`
+      )
+    }
+    super(exe)
+    this.setLoopback(true)
   }
-
-  return process.platform === 'win32'
-    ? io.findInPath(EDGEDRIVER_LEGACY_EXE, true)
-    : null
 }
 
 /**
- * Class for managing Edge specific options.
+ * Class for managing edge chromium specific options.
  */
 class Options extends chromium.Options {
   /**
-   * Instruct the EdgeDriver to use Edge Chromium if true.
-   * Otherwise, use Edge Legacy (EdgeHTML). Defaults to using Edge Legacy.
+   * Sets the path to the edge binary to use
    *
-   * @param {boolean} useEdgeChromium
+   * 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.
    * @return {!Options} A self reference.
    */
-  setEdgeChromium(useEdgeChromium) {
-    this.set(Options.USE_EDGE_CHROMIUM, !!useEdgeChromium)
-    return this
+  setEdgeChromiumBinaryPath(path) {
+    return this.setBinaryPath(path)
   }
 }
 
-Options.USE_EDGE_CHROMIUM = 'ms:edgeChromium'
-Options.prototype.BROWSER_NAME_VALUE = Browser.EDGE
-Options.prototype.CAPABILITY_KEY = 'ms:edgeOptions'
-Options.prototype.VENDOR_CAPABILITY_PREFIX = 'ms'
-
 /**
- * @param  {(Capabilities|Object<string, *>)=} o The options object
- * @return {boolean}
+ * Creates a new WebDriver client for Microsoft's Edge.
  */
-function useEdgeChromium(o) {
-  if (o instanceof Capabilities) {
-    return !!o.get(Options.USE_EDGE_CHROMIUM)
-  }
-
-  if (o && typeof o === 'object') {
-    return !!o[Options.USE_EDGE_CHROMIUM]
+class Driver extends chromium.Driver {
+  /**
+   * Creates a new browser session for Microsoft's Edge browser.
+   *
+   * @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(opt_config, opt_serviceExecutor) {
+    let caps = opt_config || new Options()
+    return /** @type {!Driver} */ (
+      super.createSession(caps, opt_serviceExecutor)
+    )
   }
 
-  return false
-}
-
-/**
- * Creates {@link remote.DriverService} instances that manage a
- * WebDriver server in a child process. Used for driving both
- * Microsoft Edge Legacy and Chromium. A ServiceBuilder constructed
- * with default parameters will launch a MicrosoftWebDriver child
- * process for driving Edge Legacy. You may pass in a path to
- * msedgedriver.exe to use Edge Chromium instead.
- */
-class ServiceBuilder extends chromium.ServiceBuilder {
   /**
-   * @param {string=} opt_exe Path to the server executable to use. If omitted,
-   *   the builder will attempt to locate MicrosoftWebDriver on the current
-   *   PATH.
-   * @throws {Error} If provided executable does not exist, or the
-   *   MicrosoftWebDriver cannot be found on the PATH.
+   * This function is a no-op as file detectors are not supported by this
+   * implementation.
+   * @override
    */
-  constructor(opt_exe) {
-    const 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_LEGACY_EXE +
-          ' from ' +
-          'https://developer.microsoft.com/en-us/microsoft-edge/tools/webdriver/ and ' +
-          'ensure it can be found on your PATH.'
-      )
-    }
-
-    super(exe)
-  }
+  setFileDetector() {}
 }
 
-/** @type {remote.DriverService} */
-var defaultService = null
-
 /**
  * Sets the default service to use for new Edge instances.
  * @param {!remote.DriverService} service The service to use.
@@ -216,45 +193,21 @@ function getDefaultService() {
   return defaultService
 }
 
-function createServiceFromCapabilities(options) {
-  let exe
-  if (useEdgeChromium(options)) {
-    exe = locateSynchronously(EDGE_CHROMIUM_BROWSER_NAME)
-  }
-  return new ServiceBuilder(exe).build()
-}
-
 /**
- * Creates a new WebDriver client for Microsoft's Edge.
+ * _Synchronously_ attempts to locate the chromedriver executable on the current
+ * system.
+ *
+ * @return {?string} the located executable, or `null`.
  */
-class Driver extends webdriver.WebDriver {
-  /**
-   * 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
-   *     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 || createServiceFromCapabilities(options)
-    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()
-    ))
-  }
-
-  /**
-   * This function is a no-op as file detectors are not supported by this
-   * implementation.
-   * @override
-   */
-  setFileDetector() {}
+function locateSynchronously() {
+  return io.findInPath(EDGEDRIVER_CHROMIUM_EXE, true)
 }
 
+Options.prototype.BROWSER_NAME_VALUE = Browser.EDGE
+Options.prototype.CAPABILITY_KEY = 'ms:edgeOptions'
+Driver.prototype.VENDOR_CAPABILITY_PREFIX = 'ms'
+Driver.getDefaultService = getDefaultService
+
 // PUBLIC API
 
 exports.Driver = Driver

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,24 @@ 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
+  }
 }
 
 /**

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