selenium-webdriver 4.4.0 → 4.6.0

package/CHANGES.md

@@ -1,3 +1,60 @@
+## v4.6.0
+
+#### :rocket: New Feature
+
+* [grid] Add ability to use Enter key to confirm (#11178)
+* [grid][ui] Add search field for running sessions (#11197)
+* Add support for selenium manager (#11189)
+
+#### :bug: Bug Fix
+
+* isPromise() thenable fix (#11048)
+* Fix: making methods static (#11182)
+
+#### :nail_care: Polish
+
+* fix a tiny typo in chromium.js (#11073)
+* Adding CDP files for v107 and removing v104
+
+## v4.5.0
+
+#### :rocket: New Feature
+
+* Adds 'Select' support package
+  * selectByIndex
+  * selectByValue
+  * selectByVisibleText
+  * getAllSelectedOptions
+  * getFirstSelectedOption
+  * deselectAll
+  * deselectByVisibleText
+  * deselectByIndex
+  * deselectByValue
+* Add support for Actions API sendKeys to designated element
+* Adds mouse button enum for forward and backward navigation
+
+#### :bug: Bug Fix
+
+* Set min node support to 14.x.x (issue 1 in #10970)
+* fix: geckodriver session with node 18.x.x (issue 2 in #10970)
+* fix: JS firefox driver crashes on setting a profile (fixed with [commit](https://github.com/SeleniumHQ/selenium/commit/fa6deeea6bda1e73317157845772e114bd569b7d))
+* fix: "SetExperimental" option is not available in webdriverjs (Javascript/Typescript) (#10959)
+* fix: Do not allow Select class to select disabled options (#10812)
+
+#### :nail_care: Polish
+
+* Stop sending desiredCapabilities to local end and remote end
+* tests: Quit driver instance after each test
+* tests: Adds select by multiple(index,value, text) tests
+* chore/code style changes, add util (#10975)
+* chore/code style changes to common format (#10964)
+* destructuring exports
+* Moving from static to const to make js-dossier happy
+* Removing circular dependency Between webdriver.js and http.js
+* fix some typos in code and documentation 
+* add cdp v105 remove v102
+* add cdp v106 remove v103
+
 ## v4.4.0
 * Add support CDP 104 and remove CDP 101
 
@@ -1129,3 +1186,4 @@ major version release (i.e. 1.0.0).
 * Initial release for npm:
 
         npm install selenium-webdriver
+

package/README.md

@@ -13,19 +13,19 @@ Selenium may be installed via npm with
 You will need to download additional components to work with each of the major
 browsers. The drivers for Chrome, Firefox, and Microsoft's IE and Edge web
 browsers are all standalone executables that should be placed on your system
-[PATH]. Apple's safaridriver is shipped with Safari 10 for OS X El Capitan and
-macOS Sierra. You will need to enable Remote Automation in the Develop menu of
-Safari 10 before testing.
+[PATH]. Apple's safaridriver (v10 and above) can be found at the 
+following path – /usr/bin/safaridriver. To enable automation on safari, 
+you need to run command `safaridriver --enable`.
 
 
-| Browser           | Component                          |
-| ----------------- | ---------------------------------- |
-| Chrome            | [chromedriver(.exe)][chrome]       |
-| Internet Explorer | [IEDriverServer.exe][release]      |
-| Edge              | [MicrosoftWebDriver.msi][edge]     |
-| Firefox           | [geckodriver(.exe)][geckodriver]   |
-| Opera             | [operadriver(.exe)][operadriver]   |
-| Safari            | [safaridriver]                     |
+| Browser            | Component                           |
+|:-------------------|:------------------------------------|
+| Chrome             | [chromedriver(.exe)][chrome]        |
+| Internet Explorer  | [IEDriverServer.exe][release]       |
+| Edge               | [MicrosoftWebDriver.msi][edge]      |
+| Firefox            | [geckodriver(.exe)][geckodriver]    |
+| Opera              | [operadriver(.exe)][operadriver]    |
+| Safari             | [safaridriver]                      |
 
 ## Usage
 
@@ -38,7 +38,7 @@ const {Builder, Browser, By, Key, until} = require('selenium-webdriver');
 (async function example() {
   let driver = await new Builder().forBrowser(Browser.FIREFOX).build();
   try {
-    await driver.get('http://www.google.com/ncr');
+    await driver.get('https://www.google.com/ncr');
     await driver.findElement(By.name('q')).sendKeys('webdriver', Key.RETURN);
     await driver.wait(until.titleIs('webdriver - Google Search'), 1000);
   } finally {
@@ -92,7 +92,7 @@ To use the Selenium Server, you will need to install the
 download the latest server from [Selenium][release]. Once downloaded, run the
 server with
 
-    java -jar selenium-server-standalone-2.45.0.jar
+    java -jar selenium-server-4.4.0.jar standalone
 
 You may configure your tests to run against a remote server through the Builder
 API:
@@ -135,17 +135,17 @@ will also have "best effort" support. Releases older than the latest LTS,
 _semver-major_ releases, and all unstable release branches (e.g. "v.Next")
 are considered strictly unsupported.
 
-For example, suppose the current LTS and stable releases are v6.9.5 and v7.5.0,
+For example, suppose the current LTS and stable releases are v14.20.0 and v18.8.0,
 respectively. Then a Selenium release would have the following support levels:
 
-| Version | Support       |
-| ------- | ------------- |
-| <= 6.8  | _unsupported_ |
-| 6.9     | supported     |
-| 7.0-4   | best effort   |
-| 7.5     | supported     |
-| >= 7.5  | best effort   |
-| v.Next  | _unsupported_ |
+|  Version   |     Support     |
+|:----------:|:---------------:|
+|  <= 14.19  |  _unsupported_  |
+|  14.20.0   |    supported    |
+|   18.0-7   |   best effort   |
+|   18.8.0   |    supported    |
+| >= 18.8.0  |   best effort   |
+|   v.Next   |  _unsupported_  |
 
 ### Support Level Definitions
 
@@ -165,13 +165,13 @@ respectively. Then a Selenium release would have the following support levels:
 If Node releases a new [LTS] each October and a new major version every 6
 months, the support window for selenium-webdriver will be roughly:
 
-| Date      | LTS  | Stable |
-| --------- | ---: | -----: |
-| (current) |  8.9 |    9.0 |
-| 2018-04   |  8.x |   10.0 |
-| 2018-10   | 10.x |   11.0 |
-| 2019-04   | 10.x |   12.0 |
-| 2019-10   | 12.x |   13.0 |
+|  Release  |      Status      | END-OF-LIFE  |
+|:---------:|:----------------:|:------------:|
+|   v14.x   | Maintenance LTS  |  2023-04-30  |
+|   v16.x   |    Active LTS    |  2023-09-11  |
+|   v18.x   |     Current      |  2025-04-30  |
+|   v19.x   |     Pending      |  2023-06-01  |
+|    v20    |     Pending      |  2026-04-30  |
 
 ## Issues
 

package/chrome.js

@@ -130,6 +130,7 @@
 const io = require('./io')
 const { Browser } = require('./lib/capabilities')
 const chromium = require('./chromium')
+const { driverLocation } = require('./common/seleniumManager')
 
 /**
  * Name of the ChromeDriver executable.
@@ -150,20 +151,35 @@ 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 chromedriver on the current
-   *     PATH.
+   *     PATH. If the chromedriver is not available in path, selenium-manager will
+   *     download the chromedriver
    * @throws {Error} If provided executable does not exist, or the chromedriver
    *     cannot be found on the PATH.
    */
   constructor(opt_exe) {
     let exe = opt_exe || locateSynchronously()
+
+    if (!exe) {
+      console.log(
+        ` The ChromeDriver could not be found on the current PATH, trying Selenium Manager`
+      )
+
+      try {
+        exe = driverLocation(Browser.CHROME)
+      } catch (err) {
+        console.log(`Unable to obtain driver using Selenium Manager: ${err}`)
+      }
+    }
+
     if (!exe) {
       throw Error(
-        `The ChromeDriver could not be found on the current PATH. Please ` +
-          `download the latest version of the ChromeDriver from ` +
-          `http://chromedriver.storage.googleapis.com/index.html and ensure ` +
-          `it can be found on your PATH.`
+        `The ChromeDriver could not be found on the current PATH.
+      Please download the latest version of the ChromeDriver
+      from http://chromedriver.storage.googleapis.com/index.html
+      and ensure it can be found on your PATH.`
       )
     }
+
     super(exe)
   }
 }

package/chromium.js

@@ -706,7 +706,7 @@ class Driver extends webdriver.WebDriver {
   /**
    * Schedules a command to get Chromium network emulation settings.
    * @return {!Promise} A promise that will be resolved when network
-   *     emulation settings are retrievied.
+   *     emulation settings are retrieved.
    */
   getNetworkConditions() {
     return this.execute(new command.Command(Command.GET_NETWORK_CONDITIONS))

package/common/seleniumManager.js

@@ -0,0 +1,91 @@
+// 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.
+
+/**
+ *  This implementation is still in beta, and may change.
+ *
+ *  Wrapper for getting information from the Selenium Manager binaries
+ */
+
+const { platform } = require('process')
+const path = require('path')
+const fs = require('fs')
+const execSync = require('child_process').execSync
+
+/**
+ * currently supported browsers for selenium-manager
+ * @type {string[]}
+ */
+const Browser = ['chrome', 'firefox', 'edge']
+
+/**
+ * Determines the path of the correct Selenium Manager binary
+ * @returns {string}
+ */
+function getBinary() {
+  const directory = {
+    darwin: 'macos',
+    win32: 'windows',
+    cygwin: 'windows',
+    linux: 'linux',
+  }[platform]
+
+  const file =
+    directory === 'windows' ? 'selenium-manager.exe' : 'selenium-manager'
+
+  const filePath = path.join(__dirname, '..', '/bin', directory, file)
+
+  if (!fs.existsSync(filePath)) {
+    throw new Error(`Unable to obtain Selenium Manager`)
+  }
+
+  return filePath
+}
+
+/**
+ * Determines the path of the correct driver
+ * @param {Browser|string} browser name to fetch the driver
+ * @returns {string} path of the driver location
+ */
+
+function driverLocation(browser) {
+  if (!Browser.includes(browser.toLocaleString())) {
+    throw new Error(
+      `Unable to locate driver associated with browser name: ${browser}`
+    )
+  }
+
+  let args = [getBinary(), '--browser', browser]
+  let result
+
+  try {
+    result = execSync(args.join(' ')).toString()
+  } catch (e) {
+    throw new Error(
+      `Error executing command with ${args} : Error ${e.stderr.toString()}`
+    )
+  }
+
+  if (!result.startsWith('INFO\t')) {
+    throw new Error(`Unsuccessful command executed ${args}}`)
+  }
+
+  return result.replace('INFO\t', '').trim()
+}
+
+// PUBLIC API
+module.exports = { driverLocation }

package/edge.js

@@ -80,6 +80,7 @@
 const { Browser } = require('./lib/capabilities')
 const io = require('./io')
 const chromium = require('./chromium')
+const { driverLocation } = require('./common/seleniumManager')
 
 /**
  * Name of the EdgeDriver executable.
@@ -106,6 +107,19 @@ class ServiceBuilder extends chromium.ServiceBuilder {
    */
   constructor(opt_exe) {
     let exe = opt_exe || locateSynchronously()
+
+    if (!exe) {
+      console.log(
+        `The WebDriver for Edge could not be found on the current PATH, trying Selenium Manager`
+      )
+
+      try {
+        exe = driverLocation('edge')
+      } catch (err) {
+        console.log(`Unable to obtain driver using Selenium Manager: ${err}`)
+      }
+    }
+
     if (!exe) {
       throw Error(
         `The WebDriver for Edge could not be found on the current PATH. Please download the ` +
@@ -114,6 +128,7 @@ class ServiceBuilder extends chromium.ServiceBuilder {
           `and ensure it can be found on your PATH.`
       )
     }
+
     super(exe)
     this.setLoopback(true)
   }

package/firefox.js

@@ -127,6 +127,7 @@ const webdriver = require('./lib/webdriver')
 const zip = require('./io/zip')
 const { Browser, Capabilities } = require('./lib/capabilities')
 const { Zip } = require('./io/zip')
+const { driverLocation } = require('./common/seleniumManager')
 
 /**
  * Thrown when there an add-on is malformed.
@@ -459,16 +460,27 @@ function locateSynchronously() {
  */
 function findGeckoDriver() {
   let exe = locateSynchronously()
+
+  if (!exe) {
+    console.log(
+      `The ${GECKO_DRIVER_EXE} executable could not be found on the current PATH, trying Selenium Manager`
+    )
+
+    try {
+      exe = driverLocation(Browser.FIREFOX)
+    } catch (err) {
+      console.log(`Unable to obtain driver using Selenium Manager: ${err}`)
+    }
+  }
+
   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.'
+      `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.`
     )
   }
+
   return exe
 }
 

package/index.js

@@ -38,6 +38,7 @@ const safari = require('./safari')
 const session = require('./lib/session')
 const until = require('./lib/until')
 const webdriver = require('./lib/webdriver')
+const select = require('./lib/select')
 
 const Browser = capabilities.Browser
 const Capabilities = capabilities.Capabilities
@@ -793,3 +794,4 @@ exports.error = error
 exports.logging = logging
 exports.promise = promise
 exports.until = until
+exports.Select = select.Select

package/io/exec.js

@@ -121,7 +121,7 @@ class Command {
  * @param {Options=} opt_options The command options.
  * @return {!Command} The launched command.
  */
-module.exports = function exec(command, opt_options) {
+function exec(command, opt_options) {
   const options = opt_options || {}
 
   let proc = childProcess.spawn(command, options.args || [], {
@@ -158,6 +158,9 @@ module.exports = function exec(command, opt_options) {
 
 // Exported to improve generated API documentation.
 
-module.exports.Command = Command
-module.exports.Options = Options
-module.exports.Result = Result
+module.exports = {
+  Command,
+  Options,
+  Result,
+  exec,
+}

package/lib/by.js

@@ -41,9 +41,8 @@
  *     {name: string}|
  *     {partialLinkText: string}|
  *     {tagName: string}|
- *     {xpath: string})}
+ *     {xpath: string})} ByHash
  */
-var ByHash // eslint-disable-line
 
 /**
  * Error thrown if an invalid character is encountered while escaping a CSS

package/lib/command.js

@@ -204,7 +204,7 @@ class Executor {
 // PUBLIC API
 
 module.exports = {
-  Command: Command,
-  Name: Name,
-  Executor: Executor,
+  Command,
+  Name,
+  Executor,
 }

package/lib/error.js

@@ -17,6 +17,8 @@
 
 'use strict'
 
+const { isObject } = require('./util')
+
 /**
  * The base WebDriver error type. This error type is only used directly when a
  * more appropriate category is not defined for the offending error.
@@ -505,7 +507,7 @@ function encodeError(err) {
  * @see https://w3c.github.io/webdriver/webdriver-spec.html#protocol
  */
 function isErrorResponse(data) {
-  return data && typeof data === 'object' && typeof data.error === 'string'
+  return isObject(data) && typeof data.error === 'string'
 }
 
 /**
@@ -540,15 +542,13 @@ function throwDecodedError(data) {
 function checkLegacyResponse(responseObj) {
   // Handle the legacy Selenium error response format.
   if (
-    responseObj &&
-    typeof responseObj === 'object' &&
-    typeof responseObj['status'] === 'number' &&
-    responseObj['status'] !== 0
+    isObject(responseObj) &&
+    typeof responseObj.status === 'number' &&
+    responseObj.status !== 0
   ) {
-    let status = responseObj['status']
-    let ctor = LEGACY_ERROR_CODE_TO_TYPE.get(status) || WebDriverError
+    const { status, value } = responseObj
 
-    let value = responseObj['value']
+    let ctor = LEGACY_ERROR_CODE_TO_TYPE.get(status) || WebDriverError
 
     if (!value || typeof value !== 'object') {
       throw new ctor(value + '')

package/lib/http.js

@@ -31,7 +31,8 @@ const error = require('./error')
 const logging = require('./logging')
 const promise = require('./promise')
 const { Session } = require('./session')
-const { WebElement } = require('./webdriver')
+const webElement = require('./webelement')
+const { isObject } = require('./util')
 
 const getAttribute = requireAtom(
   'get-attribute.js',
@@ -462,7 +463,7 @@ const CLIENTS =
 class Executor {
   /**
    * @param {!(Client|IThenable<!Client>)} client The client to use for sending
-   *     requests to the server, or a promise-like object that will resolve to
+   *     requests to the server, or a promise-like object that will resolve
    *     to the client.
    */
   constructor(client) {
@@ -572,10 +573,7 @@ function parseHttpResponse(command, httpResponse) {
 
   if (parsed && typeof parsed === 'object') {
     let value = parsed.value
-    let isW3C =
-      value !== null &&
-      typeof value === 'object' &&
-      typeof parsed.status === 'undefined'
+    let isW3C = isObject(value) && typeof parsed.status === 'undefined'
 
     if (!isW3C) {
       error.checkLegacyResponse(parsed)
@@ -625,10 +623,10 @@ function buildPath(path, parameters) {
       let key = pathParameters[i].substring(2) // Trim the /:
       if (key in parameters) {
         let value = parameters[key]
-        if (WebElement.isId(value)) {
+        if (webElement.isId(value)) {
           // When inserting a WebElement into the URL, only use its ID value,
           // not the full JSON.
-          value = WebElement.extractId(value)
+          value = webElement.extractId(value)
         }
         path = path.replace(pathParameters[i], '/' + value)
         delete parameters[key]
@@ -645,10 +643,10 @@ function buildPath(path, parameters) {
 // PUBLIC API
 
 module.exports = {
-  Executor: Executor,
-  Client: Client,
-  Request: Request,
-  Response: Response,
+  Executor,
+  Client,
+  Request,
+  Response,
   // Exported for testing.
-  buildPath: buildPath,
+  buildPath,
 }

package/lib/input.js

@@ -31,6 +31,8 @@ const Button = {
   LEFT: 0,
   MIDDLE: 1,
   RIGHT: 2,
+  BACK: 3,
+  FORWARD: 4,
 }
 
 /**
@@ -159,7 +161,8 @@ class FileDetector {
    * @return {!Promise<string>} A promise for the processed file path.
    * @package
    */
-  handleFile(driver, path) { // eslint-disable-line
+  handleFile(_driver, path) {
+    // eslint-disable-line
     return Promise.resolve(path)
   }
 }
@@ -801,7 +804,13 @@ class Actions {
    * @return {!Actions} a self reference.
    */
   sendKeys(...keys) {
+    const { WebElement } = require('./webdriver')
+
     const actions = []
+    if (keys.length > 1 && keys[0] instanceof WebElement) {
+      this.click(keys[0])
+      keys.shift()
+    }
     for (const key of keys) {
       if (typeof key === 'string') {
         for (const symbol of key) {

package/lib/promise.js

@@ -22,16 +22,7 @@
 
 'use strict'
 
-/**
- * Determines whether a {@code value} should be treated as a promise.
- * Any object whose "then" property is a function will be considered a promise.
- *
- * @param {?} value The value to test.
- * @return {boolean} Whether the value is a promise.
- */
-function isPromise(value) {
-  return Object.prototype.toString.call(value) === '[object Promise]'
-}
+const { isObject, isPromise } = require('./util')
 
 /**
  * Creates a promise that will be resolved at a set time in the future.
@@ -218,7 +209,7 @@ async function fullyResolved(value) {
     return fullyResolveKeys(/** @type {!Array} */ (value))
   }
 
-  if (value && typeof value === 'object') {
+  if (isObject(value)) {
     return fullyResolveKeys(/** @type {!Object} */ (value))
   }