selenium-webdriver 4.19.0 → 4.21.0

package/bidi/scriptManager.js

@@ -27,6 +27,11 @@ const { RemoteValue } = require('./protocolValue')
 const { Source } = require('./scriptTypes')
 const { WebDriverError } = require('../lib/error')
 
+/**
+ * Represents class to run events and commands of Script module.
+ * Described in https://w3c.github.io/webdriver-bidi/#module-script.
+ * @class
+ */
 class ScriptManager {
   constructor(driver) {
     this._driver = driver
@@ -41,6 +46,13 @@ class ScriptManager {
     this._browsingContextIds = browsingContextIds
   }
 
+  /**
+   * Disowns the handles in the specified realm.
+   *
+   * @param {string} realmId - The ID of the realm.
+   * @param {string[]} handles - The handles to disown to allow garbage collection.
+   * @returns {Promise<void>} - A promise that resolves when the command is sent.
+   */
   async disownRealmScript(realmId, handles) {
     const params = {
       method: 'script.disown',
@@ -55,6 +67,13 @@ class ScriptManager {
     await this.bidi.send(params)
   }
 
+  /**
+   * Disowns the handles in the specified browsing context.
+   * @param {string} browsingContextId - The ID of the browsing context.
+   * @param {string[]} handles - The handles to disown to allow garbage collection.
+   * @param {String|null} [sandbox=null] - The sandbox name.
+   * @returns {Promise<void>} - A promise that resolves when the command is sent.
+   */
   async disownBrowsingContextScript(browsingContextId, handles, sandbox = null) {
     const params = {
       method: 'script.disown',
@@ -73,6 +92,17 @@ class ScriptManager {
     await this.bidi.send(params)
   }
 
+  /**
+   * Calls a function in the specified realm.
+   *
+   * @param {string} realmId - The ID of the realm.
+   * @param {string} functionDeclaration - The function to call.
+   * @param {boolean} awaitPromise - Whether to await the promise returned by the function.
+   * @param {LocalValue[]} [argumentValueList|null] - The list of argument values to pass to the function.
+   * @param {Object} [thisParameter|null] - The value of 'this' parameter for the function.
+   * @param {ResultOwnership} [resultOwnership|null] - The ownership of the result.
+   * @returns {Promise<EvaluateResultSuccess|EvaluateResultException>} - A promise that resolves to the evaluation result or exception.
+   */
   async callFunctionInRealm(
     realmId,
     functionDeclaration,
@@ -101,6 +131,17 @@ class ScriptManager {
     return this.createEvaluateResult(response)
   }
 
+  /**
+   * Calls a function in the specified browsing context.
+   *
+   * @param {string} realmId - The ID of the browsing context.
+   * @param {string} functionDeclaration - The function to call.
+   * @param {boolean} awaitPromise - Whether to await the promise returned by the function.
+   * @param {LocalValue[]} [argumentValueList|null] - The list of argument values to pass to the function.
+   * @param {Object} [thisParameter|null] - The value of 'this' parameter for the function.
+   * @param {ResultOwnership} [resultOwnership|null] - The ownership of the result.
+   * @returns {Promise<EvaluateResultSuccess|EvaluateResultException>} - A promise that resolves to the evaluation result or exception.
+   */
   async callFunctionInBrowsingContext(
     browsingContextId,
     functionDeclaration,
@@ -129,6 +170,15 @@ class ScriptManager {
     return this.createEvaluateResult(response)
   }
 
+  /**
+   * Evaluates a function in the specified realm.
+   *
+   * @param {string} realmId - The ID of the realm.
+   * @param {string} expression - The expression to function to evaluate.
+   * @param {boolean} awaitPromise - Whether to await the promise.
+   * @param {ResultOwnership|null} resultOwnership - The ownership of the result.
+   * @returns {Promise<EvaluateResultSuccess|EvaluateResultException>} - A promise that resolves to the evaluation result or exception.
+   */
   async evaluateFunctionInRealm(realmId, expression, awaitPromise, resultOwnership = null) {
     const params = this.getEvaluateParams('realm', realmId, null, expression, awaitPromise, resultOwnership)
 
@@ -141,6 +191,15 @@ class ScriptManager {
     return this.createEvaluateResult(response)
   }
 
+  /**
+   * Evaluates a function in the browsing context.
+   *
+   * @param {string} realmId - The ID of the browsing context.
+   * @param {string} expression - The expression to function to evaluate.
+   * @param {boolean} awaitPromise - Whether to await the promise.
+   * @param {ResultOwnership|null} resultOwnership - The ownership of the result.
+   * @returns {Promise<EvaluateResultSuccess|EvaluateResultException>} - A promise that resolves to the evaluation result or exception.
+   */
   async evaluateFunctionInBrowsingContext(
     browsingContextId,
     expression,
@@ -166,11 +225,22 @@ class ScriptManager {
     return this.createEvaluateResult(response)
   }
 
+  /**
+   * Adds a preload script.
+   *
+   * @param {string} functionDeclaration - The declaration of the function to be added as a preload script.
+   * @param {LocalValue[]} [argumentValueList=[]] - The list of argument values to be passed to the preload script function.
+   * @param {string} [sandbox|null] - The sandbox object to be used for the preload script.
+   * @returns {Promise<number>} - A promise that resolves to the added preload script ID.
+   */
   async addPreloadScript(functionDeclaration, argumentValueList = [], sandbox = null) {
     const params = {
       functionDeclaration: functionDeclaration,
       arguments: argumentValueList,
-      sandbox: sandbox,
+    }
+
+    if (sandbox !== null) {
+      params.sandbox = sandbox
     }
 
     if (Array.isArray(this._browsingContextIds) && this._browsingContextIds.length > 0) {
@@ -190,6 +260,13 @@ class ScriptManager {
     return response.result.script
   }
 
+  /**
+   * Removes a preload script.
+   *
+   * @param {string} script - The ID for the script to be removed.
+   * @returns {Promise<any>} - A promise that resolves with the result of the removal.
+   * @throws {WebDriverError} - If an error occurs during the removal process.
+   */
   async removePreloadScript(script) {
     const params = { script: script }
     const command = {
@@ -290,6 +367,10 @@ class ScriptManager {
     return realmsList
   }
 
+  /**
+   * Retrieves all realms.
+   * @returns {Promise<RealmInfo[]>} - A promise that resolves to an array of RealmInfo objects.
+   */
   async getAllRealms() {
     const command = {
       method: 'script.getRealms',
@@ -299,6 +380,12 @@ class ScriptManager {
     return this.realmInfoMapper(response.result.realms)
   }
 
+  /**
+   * Retrieves the realms by type.
+   *
+   * @param {Type} type - The type of realms to retrieve.
+   * @returns {Promise<RealmInfo[]>} - A promise that resolves to an array of RealmInfo objects.
+   */
   async getRealmsByType(type) {
     const command = {
       method: 'script.getRealms',
@@ -308,6 +395,12 @@ class ScriptManager {
     return this.realmInfoMapper(response.result.realms)
   }
 
+  /**
+   * Retrieves the realms in the specified browsing context.
+   *
+   * @param {string} browsingContext - The browsing context ID.
+   * @returns {Promise<RealmInfo[]>} - A promise that resolves to an array of RealmInfo objects.
+   */
   async getRealmsInBrowsingContext(browsingContext) {
     const command = {
       method: 'script.getRealms',
@@ -317,6 +410,13 @@ class ScriptManager {
     return this.realmInfoMapper(response.result.realms)
   }
 
+  /**
+   * Retrieves the realms in a browsing context based on the specified type.
+   *
+   * @param {string} browsingContext - The browsing context ID.
+   * @param {string} type - The type of realms to retrieve.
+   * @returns {Promise<RealmInfo[]>} - A promise that resolves to an array of RealmInfo objects.
+   */
   async getRealmsInBrowsingContextByType(browsingContext, type) {
     const command = {
       method: 'script.getRealms',
@@ -326,14 +426,32 @@ class ScriptManager {
     return this.realmInfoMapper(response.result.realms)
   }
 
+  /**
+   * Subscribes to the 'script.message' event and handles the callback function when a message is received.
+   *
+   * @param {Function} callback - The callback function to be executed when a message is received.
+   * @returns {Promise<void>} - A promise that resolves when the subscription is successful.
+   */
   async onMessage(callback) {
     await this.subscribeAndHandleEvent('script.message', callback)
   }
 
+  /**
+   * Subscribes to the 'script.realmCreated' event and handles it with the provided callback.
+   *
+   * @param {Function} callback - The callback function to handle the 'script.realmCreated' event.
+   * @returns {Promise<void>} - A promise that resolves when the subscription is successful.
+   */
   async onRealmCreated(callback) {
     await this.subscribeAndHandleEvent('script.realmCreated', callback)
   }
 
+  /**
+   * Subscribes to the 'script.realmDestroyed' event and handles it with the provided callback function.
+   *
+   * @param {Function} callback - The callback function to be executed when the 'script.realmDestroyed' event occurs.
+   * @returns {Promise<void>} - A promise that resolves when the subscription is successful.
+   */
   async onRealmDestroyed(callback) {
     await this.subscribeAndHandleEvent('script.realmDestroyed', callback)
   }

package/bidi/scriptTypes.js

@@ -15,26 +15,54 @@
 // specific language governing permissions and limitations
 // under the License.
 
+/**
+ * Represents a message received through a channel.
+ * Described in https://w3c.github.io/webdriver-bidi/#event-script-message.
+ * @class
+ */
 class Message {
+  /**
+   * Creates a new Message instance.
+   * @param {string} channel - The channel through which the message is received.
+   * @param {RemoteValue} data - The data contained in the message.
+   * @param {Source} source - The source of the message.
+   */
   constructor(channel, data, source) {
     this._channel = channel
     this._data = data
     this._source = source
   }
 
+  /**
+   * Gets the channel through which the message is received.
+   * @returns {string} The channel.
+   */
   get channel() {
     return this._channel
   }
 
+  /**
+   * Gets the data contained in the message.
+   * @returns {RemoteValue} The data.
+   */
   get data() {
     return this._data
   }
 
+  /**
+   * Gets the source of the message.
+   * @returns {Source} The source.
+   */
   get source() {
     return this._source
   }
 }
 
+/**
+ * Represents a source object.
+ * Described in https://w3c.github.io/webdriver-bidi/#type-script-Source.
+ * @class
+ */
 class Source {
   constructor(source) {
     this._browsingContextId = null
@@ -46,10 +74,18 @@ class Source {
     }
   }
 
+  /**
+   * Get the browsing context ID.
+   * @returns {string|null} The browsing context ID.
+   */
   get browsingContextId() {
     return this._browsingContextId
   }
 
+  /**
+   * Get the realm ID.
+   * @returns {string} The realm ID.
+   */
   get realmId() {
     return this._realmId
   }

package/bidi/storage.js

@@ -21,6 +21,11 @@ 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
@@ -34,6 +39,15 @@ class Storage {
     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}'`)
@@ -89,6 +103,14 @@ class Storage {
     }
   }
 
+  /**
+   * 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}'`)
@@ -125,6 +147,14 @@ class Storage {
     }
   }
 
+  /**
+   * 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}'`)

package/bidi/urlPattern.js

@@ -15,19 +15,42 @@
 // specific language governing permissions and limitations
 // under the License.
 
+/**
+ * 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())
@@ -37,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

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.
@@ -622,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()
@@ -743,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 }