selenium-webdriver 4.18.1 → 4.20.0

package/bidi/storage.js

@@ -0,0 +1,201 @@
+// 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.
+
+const { CookieFilter } = require('./cookieFilter')
+const { BrowsingContextPartitionDescriptor, StorageKeyPartitionDescriptor } = require('./partitionDescriptor')
+const { PartitionKey } = require('./partitionKey')
+const { PartialCookie } = require('./partialCookie')
+const { Cookie, BytesValue } = require('./networkTypes')
+
+/**
+ * Represents commands of Storage module.
+ * Described in https://w3c.github.io/webdriver-bidi/#module-storage.
+ * @class
+ */
+class Storage {
+  constructor(driver) {
+    this._driver = driver
+  }
+
+  async init() {
+    if (!(await this._driver.getCapabilities()).get('webSocketUrl')) {
+      throw Error('WebDriver instance must support BiDi protocol')
+    }
+
+    this.bidi = await this._driver.getBidi()
+  }
+
+  /**
+   * Retrieves cookies based on the provided filter and partition.
+   *
+   * @param {CookieFilter} [filter] - The filter to apply to the cookies.
+   * @param {(BrowsingContextPartitionDescriptor|StorageKeyPartitionDescriptor)} [partition] - The partition to retrieve cookies from.
+   * @returns {Promise<{ cookies: Cookie[], partitionKey?: PartitionKey }>} - A promise that resolves to an object containing the retrieved cookies and an optional partition key.
+   * @throws {Error} If the filter parameter is provided but is not an instance of CookieFilter.
+   * @throws {Error} If the partition parameter is provided but is not an instance of BrowsingContextPartitionDescriptor or StorageKeyPartitionDescriptor.
+   */
+  async getCookies(filter = undefined, partition = undefined) {
+    if (filter !== undefined && !(filter instanceof CookieFilter)) {
+      throw new Error(`Params must be an instance of CookieFilter. Received:'${filter}'`)
+    }
+
+    if (
+      partition !== undefined &&
+      !(partition instanceof (BrowsingContextPartitionDescriptor || StorageKeyPartitionDescriptor))
+    ) {
+      throw new Error(`Params must be an instance of PartitionDescriptor. Received:'${partition}'`)
+    }
+
+    const command = {
+      method: 'storage.getCookies',
+      params: {
+        filter: filter ? Object.fromEntries(filter.asMap()) : undefined,
+        partition: partition ? Object.fromEntries(partition.asMap()) : undefined,
+      },
+    }
+
+    let response = await this.bidi.send(command)
+
+    let cookies = []
+    response.result.cookies.forEach((cookie) => {
+      cookies.push(
+        new Cookie(
+          cookie.name,
+          new BytesValue(cookie.value.type, cookie.value.value),
+          cookie.domain,
+          cookie.path,
+          cookie.size,
+          cookie.httpOnly,
+          cookie.secure,
+          cookie.sameSite,
+          cookie.expiry,
+        ),
+      )
+    })
+
+    if (Object.prototype.hasOwnProperty.call(response.result, 'partitionKey')) {
+      if (
+        Object.prototype.hasOwnProperty.call(response.result.partitionKey, 'userContext') &&
+        Object.prototype.hasOwnProperty.call(response.result.partitionKey, 'sourceOrigin')
+      ) {
+        let partitionKey = new PartitionKey(
+          response.result.partitionKey.userContext,
+          response.result.partitionKey.sourceOrigin,
+        )
+        return { cookies, partitionKey }
+      }
+
+      return { cookies }
+    }
+  }
+
+  /**
+   * Sets a cookie using the provided cookie object and partition.
+   *
+   * @param {PartialCookie} cookie - The cookie object to set.
+   * @param {(BrowsingContextPartitionDescriptor|StorageKeyPartitionDescriptor)} [partition] - The partition to use for the cookie.
+   * @returns {PartitionKey} The partition key of the set cookie.
+   * @throws {Error} If the cookie parameter is not an instance of PartialCookie or if the partition parameter is not an instance of PartitionDescriptor.
+   */
+  async setCookie(cookie, partition = undefined) {
+    if (!(cookie instanceof PartialCookie)) {
+      throw new Error(`Params must be an instance of PartialCookie. Received:'${cookie}'`)
+    }
+
+    if (
+      partition !== undefined &&
+      !(partition instanceof (BrowsingContextPartitionDescriptor || StorageKeyPartitionDescriptor))
+    ) {
+      throw new Error(`Params must be an instance of PartitionDescriptor. Received:'${partition}'`)
+    }
+
+    const command = {
+      method: 'storage.setCookie',
+      params: {
+        cookie: cookie ? Object.fromEntries(cookie.asMap()) : undefined,
+        partition: partition ? Object.fromEntries(partition.asMap()) : undefined,
+      },
+    }
+
+    let response = await this.bidi.send(command)
+
+    if (Object.prototype.hasOwnProperty.call(response.result, 'partitionKey')) {
+      if (
+        Object.prototype.hasOwnProperty.call(response.result.partitionKey, 'userContext') &&
+        Object.prototype.hasOwnProperty.call(response.result.partitionKey, 'sourceOrigin')
+      ) {
+        let partitionKey = new PartitionKey(
+          response.result.partitionKey.userContext,
+          response.result.partitionKey.sourceOrigin,
+        )
+        return partitionKey
+      }
+    }
+  }
+
+  /**
+   * Deletes cookies based on the provided filter and partition.
+   *
+   * @param {CookieFilter} [cookieFilter] - The filter to apply to the cookies. Must be an instance of CookieFilter.
+   * @param {(BrowsingContextPartitionDescriptor|StorageKeyPartitionDescriptor)} [partition] - The partition to delete cookies from. Must be an instance of either BrowsingContextPartitionDescriptor or StorageKeyPartitionDescriptor.
+   * @returns {PartitionKey} - The partition key of the deleted cookies, if available.
+   * @throws {Error} - If the provided parameters are not of the correct type.
+   */
+  async deleteCookies(cookieFilter = undefined, partition = undefined) {
+    if (cookieFilter !== undefined && !(cookieFilter instanceof CookieFilter)) {
+      throw new Error(`Params must be an instance of CookieFilter. Received:'${cookieFilter}'`)
+    }
+
+    if (
+      partition !== undefined &&
+      !(partition instanceof (BrowsingContextPartitionDescriptor || StorageKeyPartitionDescriptor))
+    ) {
+      throw new Error(`Params must be an instance of PartitionDescriptor. Received:'${partition}'`)
+    }
+
+    const command = {
+      method: 'storage.deleteCookies',
+      params: {
+        filter: cookieFilter ? Object.fromEntries(cookieFilter.asMap()) : undefined,
+        partition: partition ? Object.fromEntries(partition.asMap()) : undefined,
+      },
+    }
+
+    let response = await this.bidi.send(command)
+
+    if (Object.prototype.hasOwnProperty.call(response.result, 'partitionKey')) {
+      if (
+        Object.prototype.hasOwnProperty.call(response.result.partitionKey, 'userContext') &&
+        Object.prototype.hasOwnProperty.call(response.result.partitionKey, 'sourceOrigin')
+      ) {
+        let partitionKey = new PartitionKey(
+          response.result.partitionKey.userContext,
+          response.result.partitionKey.sourceOrigin,
+        )
+        return partitionKey
+      }
+    }
+  }
+}
+
+async function getStorageInstance(driver) {
+  let instance = new Storage(driver)
+  await instance.init()
+  return instance
+}
+
+module.exports = getStorageInstance

package/bidi/urlPattern.js

@@ -15,21 +15,42 @@
 // specific language governing permissions and limitations
 // under the License.
 
-const {LocalValue} = require('./protocolValue')
-
+/**
+ * Represents a URL pattern to intercept.
+ * Described in network.UrlPatternPattern https://w3c.github.io/webdriver-bidi/#type-network-UrlPattern
+ */
 class UrlPattern {
   #map = new Map()
 
+  /**
+   * Sets the protocol for the URL pattern.
+   *
+   * @param {string} protocol - The protocol to set.
+   * @returns {UrlPattern} - Returns the updated instance of the URL pattern for chaining.
+   */
   protocol(protocol) {
     this.#map.set('protocol', protocol)
     return this
   }
 
+  /**
+   * Sets the hostname for the URL pattern.
+   *
+   * @param {string} hostname - The hostname to set.
+   * @returns {UrlPattern} - Returns the updated instance of the URL pattern for chaining.
+   */
   hostname(hostname) {
     this.#map.set('hostname', hostname)
     return this
   }
 
+  /**
+   * Sets the port for the URL pattern.
+   *
+   * @param {number} port - The port number to set.
+   * @returns {UrlPattern} - Returns the updated instance of the URL pattern for chaining.
+   * @throws {Error} - Throws an error if the port is not a number.
+   */
   port(port) {
     if (typeof port === 'number') {
       this.#map.set('port', port.toString())
@@ -39,11 +60,23 @@ class UrlPattern {
     return this
   }
 
+  /**
+   * Sets the pathname for the URL pattern.
+   *
+   * @param {string} pathname - The pathname to set.
+   * @returns {UrlPattern} - Returns the updated instance of the URL pattern for chaining.
+   */
   pathname(pathname) {
     this.#map.set('pathname', pathname)
     return this
   }
 
+  /**
+   * Sets the search parameter in the URL pattern.
+   *
+   * @param {string} search - The search parameter to be set.
+   * @returns {UrlPattern} - Returns the updated instance of the URL pattern for chaining.
+   */
   search(search) {
     this.#map.set('search', search)
     return this
@@ -55,4 +88,4 @@ class UrlPattern {
   }
 }
 
-module.exports = {UrlPattern}
+module.exports = { UrlPattern }

package/chromium.js

@@ -78,7 +78,7 @@ const error = require('./lib/error')
 const Symbols = require('./lib/symbols')
 const webdriver = require('./lib/webdriver')
 const remote = require('./remote')
-const { getPath } = require('./common/driverFinder')
+const { getBinaryPaths } = require('./common/driverFinder')
 
 /**
  * Custom command names supported by Chromium WebDriver.
@@ -287,6 +287,7 @@ class Options extends Capabilities {
         throw TypeError('Arguments must be {width, height} with numbers > 0')
       }
     }
+
     checkArg(width)
     checkArg(height)
     return this.addArguments(`window-size=${width},${height}`)
@@ -621,14 +622,17 @@ class Driver extends webdriver.WebDriver {
     } else {
       let service = opt_serviceExecutor || this.getDefaultService()
       if (!service.getExecutable()) {
-        const { driverPath, browserPath } = getPath(caps)
+        const { driverPath, browserPath } = getBinaryPaths(caps)
         service.setExecutable(driverPath)
-        const vendorOptions = caps.get(vendorCapabilityKey)
-        if (vendorOptions) {
-          vendorOptions['binary'] = browserPath
-          caps.set(vendorCapabilityKey, vendorOptions)
-        } else {
-          caps.set(vendorCapabilityKey, { binary: browserPath })
+        if (browserPath) {
+          const vendorOptions = caps.get(vendorCapabilityKey)
+          if (vendorOptions) {
+            vendorOptions['binary'] = browserPath
+            caps.set(vendorCapabilityKey, vendorOptions)
+          } else {
+            caps.set(vendorCapabilityKey, { binary: browserPath })
+          }
+          caps.delete(Capability.BROWSER_VERSION)
         }
       }
       onQuit = () => service.kill()
@@ -742,7 +746,7 @@ class Driver extends webdriver.WebDriver {
    * Set a permission state to the given value.
    *
    * @param {string} name A name of the permission to update.
-   * @param {('granted'|'denied'|'prompt')} state State to set permission to.
+   * @param {("granted"|"denied"|"prompt")} state State to set permission to.
    * @returns {!Promise<Object>} A promise that will be resolved when the
    *     command has finished.
    * @see <https://w3c.github.io/permissions/#permission-registry> for valid

package/common/driverFinder.js

@@ -21,16 +21,19 @@
  *  Utility to find if a given file is present and executable.
  */
 
-const { driverLocation } = require('./seleniumManager')
+const path = require('node:path')
+const { binaryPaths } = require('./seleniumManager')
 
 /**
  * Determines the path of the correct Selenium Manager binary
+ * @param {Capabilities} capabilities browser options to fetch the driver
  * @returns {{browserPath: string, driverPath: string}} path of the driver
  * and browser location
  */
-function getPath(capabilities) {
+function getBinaryPaths(capabilities) {
   try {
-    return driverLocation(capabilities)
+    const args = getArgs(capabilities)
+    return binaryPaths(args)
   } catch (e) {
     throw Error(
       `Unable to obtain browser driver.
@@ -40,5 +43,34 @@ function getPath(capabilities) {
   }
 }
 
+function getArgs(options) {
+  let args = ['--browser', options.getBrowserName(), '--language-binding', 'javascript', '--output', 'json']
+
+  if (options.getBrowserVersion() && options.getBrowserVersion() !== '') {
+    args.push('--browser-version', options.getBrowserVersion())
+  }
+
+  const vendorOptions =
+    options.get('goog:chromeOptions') || options.get('ms:edgeOptions') || options.get('moz:firefoxOptions')
+  if (vendorOptions && vendorOptions.binary && vendorOptions.binary !== '') {
+    args.push('--browser-path', path.resolve(vendorOptions.binary))
+  }
+
+  const proxyOptions = options.getProxy()
+
+  // Check if proxyOptions exists and has properties
+  if (proxyOptions && Object.keys(proxyOptions).length > 0) {
+    const httpProxy = proxyOptions['httpProxy']
+    const sslProxy = proxyOptions['sslProxy']
+
+    if (httpProxy !== undefined) {
+      args.push('--proxy', httpProxy)
+    } else if (sslProxy !== undefined) {
+      args.push('--proxy', sslProxy)
+    }
+  }
+  return args
+}
+
 // PUBLIC API
-module.exports = { getPath }
+module.exports = { getBinaryPaths }

package/common/seleniumManager.js

@@ -21,11 +21,10 @@
  *  Wrapper for getting information from the Selenium Manager binaries
  */
 
-const { platform } = require('process')
-const path = require('path')
-const fs = require('fs')
-const spawnSync = require('child_process').spawnSync
-const { Capability } = require('../lib/capabilities')
+const { platform } = require('node:process')
+const path = require('node:path')
+const fs = require('node:fs')
+const spawnSync = require('node:child_process').spawnSync
 const logging = require('../lib/logging')
 
 const log_ = logging.getLogger(logging.Type.DRIVER)
@@ -63,38 +62,12 @@ function getBinary() {
 
 /**
  * Determines the path of the correct driver
- * @param {Capabilities} options browser options to fetch the driver
+ * @param {string[]} args arguments to invoke Selenium Manager
  * @returns {{browserPath: string, driverPath: string}} path of the driver and
  * browser location
  */
 
-function driverLocation(options) {
-  let args = ['--browser', options.getBrowserName(), '--language-binding', 'javascript', '--output', 'json']
-
-  if (options.getBrowserVersion() && options.getBrowserVersion() !== '') {
-    args.push('--browser-version', options.getBrowserVersion())
-  }
-
-  const vendorOptions =
-    options.get('goog:chromeOptions') || options.get('ms:edgeOptions') || options.get('moz:firefoxOptions')
-  if (vendorOptions && vendorOptions.binary && vendorOptions.binary !== '') {
-    args.push('--browser-path', path.resolve(vendorOptions.binary))
-  }
-
-  const proxyOptions = options.getProxy()
-
-  // Check if proxyOptions exists and has properties
-  if (proxyOptions && Object.keys(proxyOptions).length > 0) {
-    const httpProxy = proxyOptions['httpProxy']
-    const sslProxy = proxyOptions['sslProxy']
-
-    if (httpProxy !== undefined) {
-      args.push('--proxy', httpProxy)
-    } else if (sslProxy !== undefined) {
-      args.push('--proxy', sslProxy)
-    }
-  }
-
+function binaryPaths(args) {
   const smBinary = getBinary()
   const spawnResult = spawnSync(smBinary, args)
   let output
@@ -120,11 +93,6 @@ function driverLocation(options) {
     throw new Error(`Error executing command for ${smBinary} with ${args}: ${e.toString()}`)
   }
 
-  // Once driverPath is available, delete browserVersion from payload
-  if (output.result.driver_path) {
-    options.delete(Capability.BROWSER_VERSION)
-  }
-
   logOutput(output)
   return {
     driverPath: output.result.driver_path,
@@ -144,4 +112,4 @@ function logOutput(output) {
 }
 
 // PUBLIC API
-module.exports = { driverLocation }
+module.exports = { binaryPaths }

package/devtools/CDPConnection.js

@@ -18,6 +18,7 @@
 const logging = require('../lib/logging')
 
 const RESPONSE_TIMEOUT = 1000 * 30
+
 class CDPConnection {
   constructor(wsConnection) {
     this._wsConnection = wsConnection

package/devtools/networkinterceptor.js

@@ -85,4 +85,5 @@ class HttpResponse {
     return this.returnMethod
   }
 }
+
 exports.HttpResponse = HttpResponse

package/eslint.config.js

@@ -0,0 +1,107 @@
+// 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.
+
+const globals = require('globals')
+const noOnlyTests = require('eslint-plugin-no-only-tests')
+const js = require('@eslint/js')
+const eslintPluginPrettierRecommended = require('eslint-plugin-prettier/recommended')
+const mochaPlugin = require('eslint-plugin-mocha')
+const nodePlugin = require('eslint-plugin-n')
+
+module.exports = [
+  js.configs.recommended,
+  eslintPluginPrettierRecommended,
+  mochaPlugin.configs.flat.recommended,
+  nodePlugin.configs['flat/recommended-script'],
+  {
+    languageOptions: {
+      globals: {
+        mocha: true,
+        es6: true,
+        ...globals.node,
+      },
+      parserOptions: {
+        ecmaVersion: 2022,
+      },
+    },
+    files: ['**/*.js', 'lib/http.js'],
+    ignores: ['node_modules/*', 'generator/*', 'devtools/generator/'],
+    plugins: {
+      'no-only-tests': noOnlyTests,
+    },
+    rules: {
+      'no-const-assign': 'error',
+      'no-this-before-super': 'error',
+      'no-undef': 'error',
+      'no-unreachable': 'error',
+      'no-unused-vars': [
+        'error',
+        {
+          varsIgnorePattern: '^_',
+          args: 'all',
+          argsIgnorePattern: '^_',
+        },
+      ],
+      'constructor-super': 'error',
+      'valid-typeof': 'error',
+      'no-only-tests/no-only-tests': 'error',
+      'n/no-deprecated-api': ['error'],
+      'n/no-missing-import': ['error'],
+      'n/no-missing-require': ['error'],
+      'n/no-mixed-requires': ['error'],
+      'n/no-new-require': ['error'],
+      'n/no-unpublished-import': ['error'],
+      'n/no-unpublished-require': [
+        'error',
+        {
+          allowModules: [
+            'globals',
+            '@eslint/js',
+            'eslint-plugin-mocha',
+            'eslint-plugin-prettier',
+            'eslint-plugin-n',
+            'eslint-plugin-no-only-tests',
+          ],
+          tryExtensions: ['.js'],
+        },
+      ],
+      'n/prefer-node-protocol': ['error'],
+      'mocha/no-skipped-tests': ['off'],
+      'mocha/no-mocha-arrows': ['off'],
+      'mocha/no-setup-in-describe': ['off'],
+      'mocha/no-top-level-hooks': ['off'],
+      'mocha/no-sibling-hooks': ['off'],
+      'mocha/no-exports': ['off'],
+      'mocha/no-empty-description': ['off'],
+      'mocha/max-top-level-suites': ['off'],
+      'mocha/consistent-spacing-between-blocks': ['off'],
+      'mocha/no-nested-tests': ['off'],
+      'mocha/no-pending-tests': ['off'],
+      'mocha/no-identical-title': ['off'],
+      'prettier/prettier': [
+        'error',
+        {
+          endOfLine: 'lf',
+          printWidth: 120,
+          semi: false,
+          singleQuote: true,
+          trailingComma: 'all',
+        },
+      ],
+    },
+  },
+]

package/firefox.js

@@ -107,8 +107,8 @@
 
 'use strict'
 
-const fs = require('fs')
-const path = require('path')
+const fs = require('node:fs')
+const path = require('node:path')
 const Symbols = require('./lib/symbols')
 const command = require('./lib/command')
 const http = require('./http')
@@ -116,9 +116,9 @@ const io = require('./io')
 const remote = require('./remote')
 const webdriver = require('./lib/webdriver')
 const zip = require('./io/zip')
-const { Browser, Capabilities } = require('./lib/capabilities')
+const { Browser, Capabilities, Capability } = require('./lib/capabilities')
 const { Zip } = require('./io/zip')
-const { getPath } = require('./common/driverFinder')
+const { getBinaryPaths } = require('./common/driverFinder')
 const FIREFOX_CAPABILITY_KEY = 'moz:firefoxOptions'
 
 /**
@@ -444,6 +444,7 @@ const ExtensionCommand = {
   SET_CONTEXT: 'setContext',
   INSTALL_ADDON: 'install addon',
   UNINSTALL_ADDON: 'uninstall addon',
+  FULL_PAGE_SCREENSHOT: 'fullPage screenshot',
 }
 
 /**
@@ -470,6 +471,8 @@ function configureExecutor(executor) {
   executor.defineCommand(ExtensionCommand.INSTALL_ADDON, 'POST', '/session/:sessionId/moz/addon/install')
 
   executor.defineCommand(ExtensionCommand.UNINSTALL_ADDON, 'POST', '/session/:sessionId/moz/addon/uninstall')
+
+  executor.defineCommand(ExtensionCommand.FULL_PAGE_SCREENSHOT, 'GET', '/session/:sessionId/moz/screenshot/full')
 }
 
 /**
@@ -538,7 +541,7 @@ class Driver extends webdriver.WebDriver {
       configureExecutor(executor)
     } else if (opt_executor instanceof remote.DriverService) {
       if (!opt_executor.getExecutable()) {
-        const { driverPath, browserPath } = getPath(caps)
+        const { driverPath, browserPath } = getBinaryPaths(caps)
         opt_executor.setExecutable(driverPath)
         firefoxBrowserPath = browserPath
       }
@@ -547,7 +550,7 @@ class Driver extends webdriver.WebDriver {
     } else {
       let service = new ServiceBuilder().build()
       if (!service.getExecutable()) {
-        const { driverPath, browserPath } = getPath(caps)
+        const { driverPath, browserPath } = getBinaryPaths(caps)
         service.setExecutable(driverPath)
         firefoxBrowserPath = browserPath
       }
@@ -563,6 +566,7 @@ class Driver extends webdriver.WebDriver {
       } else {
         caps.set(FIREFOX_CAPABILITY_KEY, { binary: firefoxBrowserPath })
       }
+      caps.delete(Capability.BROWSER_VERSION)
     }
 
     return /** @type {!Driver} */ (super.createSession(executor, caps, onQuit))
@@ -645,6 +649,16 @@ class Driver extends webdriver.WebDriver {
     id = await Promise.resolve(id)
     return this.execute(new command.Command(ExtensionCommand.UNINSTALL_ADDON).setParameter('id', id))
   }
+
+  /**
+   * Take full page screenshot of the visible region
+   *
+   * @return {!Promise<string>} A promise that will be
+   *     resolved to the screenshot as a base-64 encoded PNG.
+   */
+  takeFullPageScreenshot() {
+    return this.execute(new command.Command(ExtensionCommand.FULL_PAGE_SCREENSHOT))
+  }
 }
 
 /**