selenium-webdriver 4.18.1 → 4.20.0

package/bidi/provideResponseParameters.js

@@ -0,0 +1,123 @@
+// 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 { BytesValue, Header } = require('./networkTypes')
+
+/**
+ * Represents parameters for providingResponse command.
+ * Described in https://w3c.github.io/webdriver-bidi/#command-network-provideResponse.
+ * @class
+ */
+class ProvideResponseParameters {
+  #map = new Map()
+
+  constructor(request) {
+    this.#map.set('request', request)
+  }
+
+  /**
+   * Sets the body value for the response parameters.
+   *
+   * @param {BytesValue} value - The value to set as the body. Must be an instance of BytesValue.
+   * @returns {ProvideResponseParameters} - Returns the ProvideResponseParameters object for chaining.
+   * @throws {Error} - Throws an error if the value is not an instance of BytesValue.
+   */
+  body(value) {
+    if (!(value instanceof BytesValue)) {
+      throw new Error(`Value must be an instance of BytesValue. Received: ${typeof value} with value: ${value}`)
+    }
+    this.#map.set('body', Object.fromEntries(value.asMap()))
+    return this
+  }
+
+  /**
+   * Sets the cookie headers for the response.
+   *
+   * @param {Header[]} cookieHeaders - An array of cookie headers.
+   * @returns {ProvideResponseParameters} - Returns the ProvideResponseParameters object for chaining.
+   * @throws {Error} - Throws an error if a cookie header is not an instance of Header.
+   */
+  cookies(cookieHeaders) {
+    const cookies = []
+    cookieHeaders.forEach((header) => {
+      if (!(header instanceof Header)) {
+        throw new Error(`CookieHeader must be an instance of Header. Received:'${header}'`)
+      }
+      cookies.push(Object.fromEntries(header.asMap()))
+    })
+
+    this.#map.set('cookies', cookies)
+    return this
+  }
+
+  /**
+   * Sets the headers for the response.
+   *
+   * @param {Header[]} headers - The headers to be set.
+   * @returns {ProvideResponseParameters} - Returns the ProvideResponseParameters object for chaining.
+   * @throws {Error} - If the provided header is not an instance of Header.
+   */
+  headers(headers) {
+    const headerList = []
+    headers.forEach((header) => {
+      if (!(header instanceof Header)) {
+        throw new Error(`Header must be an instance of Header. Received:'${header}'`)
+      }
+      headerList.push(Object.fromEntries(header.asMap()))
+    })
+
+    this.#map.set('headers', headerList)
+    return this
+  }
+
+  /**
+   * Sets the reason phrase for the response.
+   *
+   * @param {string} reasonPhrase - The reason phrase to set.
+   * @returns {ProvideResponseParameters} - Returns the ProvideResponseParameters object for chaining.
+   * @throws {Error} - If the reason phrase is not a string.
+   */
+  reasonPhrase(reasonPhrase) {
+    if (typeof reasonPhrase !== 'string') {
+      throw new Error(`Reason phrase must be a string. Received: '${reasonPhrase})'`)
+    }
+    this.#map.set('reasonPhrase', reasonPhrase)
+    return this
+  }
+
+  /**
+   * Sets the status code for the response.
+   *
+   * @param {number} statusCode - The status code to set.
+   * @returns {ProvideResponseParameters} - Returns the ProvideResponseParameters object for chaining.
+   * @throws {Error} - If the status code is not an integer.
+   */
+  statusCode(statusCode) {
+    if (!Number.isInteger(statusCode)) {
+      throw new Error(`Status must be an integer. Received:'${statusCode}'`)
+    }
+
+    this.#map.set('statusCode', statusCode)
+    return this
+  }
+
+  asMap() {
+    return this.#map
+  }
+}
+
+module.exports = { ProvideResponseParameters }

package/bidi/realmInfo.js

@@ -15,6 +15,11 @@
 // specific language governing permissions and limitations
 // under the License.
 
+/**
+ * Represents the types of realms.
+ * Described in https://w3c.github.io/webdriver-bidi/#type-script-RealmType.
+ * @enum
+ */
 const RealmType = {
   AUDIO_WORKLET: 'audio-worklet',
   DEDICATED_WORKER: 'dedicated-worker',
@@ -34,7 +39,17 @@ const RealmType = {
   },
 }
 
+/**
+ * Represents information about a realm.
+ * Described in https://w3c.github.io/webdriver-bidi/#type-script-RealmInfo.
+ */
 class RealmInfo {
+  /**
+   * Constructs a new RealmInfo object.
+   * @param {string} realmId - The ID of the realm.
+   * @param {string} origin - The origin of the realm.
+   * @param {string} realmType - The type of the realm.
+   */
   constructor(realmId, origin, realmType) {
     this.realmId = realmId
     this.origin = origin
@@ -77,7 +92,19 @@ class RealmInfo {
   }
 }
 
+/**
+ * Represents information about a window realm.
+ * @extends RealmInfo
+ */
 class WindowRealmInfo extends RealmInfo {
+  /**
+   * Constructs a new instance of the WindowRealmInfo class.
+   * @param {string} realmId - The ID of the realm.
+   * @param {string} origin - The origin of the realm.
+   * @param {string} realmType - The type of the realm.
+   * @param {string} browsingContext - The browsing context of the realm.
+   * @param {string|null} sandbox - The sandbox of the realm (optional).
+   */
   constructor(realmId, origin, realmType, browsingContext, sandbox = null) {
     super(realmId, origin, realmType)
     this.browsingContext = browsingContext

package/bidi/resultOwnership.js

@@ -15,6 +15,10 @@
 // specific language governing permissions and limitations
 // under the License.
 
+/**
+ * Enum representing the ownership types.
+ * @enum {string}
+ */
 const ResultOwnership = {
   ROOT: 'root',
   NONE: 'none',

package/bidi/scriptManager.js

@@ -27,20 +27,32 @@ 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
   }
 
-  async init(browsingContextId) {
+  async init(browsingContextIds) {
     if (!(await this._driver.getCapabilities()).get('webSocketUrl')) {
       throw Error('WebDriver instance must support BiDi protocol')
     }
 
     this.bidi = await this._driver.getBidi()
-    this._browsingContextId = browsingContextId
+    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,30 @@ 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) {
+      params.contexts = this._browsingContextIds
+    }
+
+    if (typeof this._browsingContextIds === 'string') {
+      params.contexts = new Array(this._browsingContextIds)
     }
 
     const command = {
@@ -182,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 = {
@@ -282,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',
@@ -291,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',
@@ -300,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',
@@ -309,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',
@@ -318,21 +426,39 @@ 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)
   }
 
   async subscribeAndHandleEvent(eventType, callback) {
-    if (this._browsingContextIds != null) {
-      await this.bidi.subscribe(eventType, this._browsingContextIds)
+    if (this.browsingContextIds != null) {
+      await this.bidi.subscribe(eventType, this.browsingContextIds)
     } else {
       await this.bidi.subscribe(eventType)
     }

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
   }