selenium-webdriver 4.19.0 → 4.21.0

package/bidi/input.js

@@ -20,6 +20,10 @@
 const { WebElement } = require('../lib/webdriver')
 const { RemoteReferenceType, ReferenceValue } = require('./protocolValue')
 
+/**
+ * Represents commands and events related to the Input module (simulated user input).
+ * Described in https://w3c.github.io/webdriver-bidi/#module-input.
+ */
 class Input {
   constructor(driver) {
     this._driver = driver
@@ -33,6 +37,13 @@ class Input {
     this.bidi = await this._driver.getBidi()
   }
 
+  /**
+   * Performs the specified actions on the given browsing context.
+   *
+   * @param {string} browsingContextId - The ID of the browsing context.
+   * @param {Array} actions - The actions to be performed.
+   * @returns {Promise} A promise that resolves with the response from the server.
+   */
   async perform(browsingContextId, actions) {
     const _actions = await updateActions(actions)
 
@@ -44,11 +55,15 @@ class Input {
       },
     }
 
-    let response = await this.bidi.send(command)
-
-    return response
+    return await this.bidi.send(command)
   }
 
+  /**
+   * Resets the input state in the specified browsing context.
+   *
+   * @param {string} browsingContextId - The ID of the browsing context.
+   * @returns {Promise} A promise that resolves when the release actions are sent.
+   */
   async release(browsingContextId) {
     const command = {
       method: 'input.releaseActions',
@@ -59,6 +74,15 @@ class Input {
     return await this.bidi.send(command)
   }
 
+  /**
+   * Sets the files property of a given input element.
+   *
+   * @param {string} browsingContextId - The ID of the browsing context.
+   * @param {string | ReferenceValue} element - The ID of the element or a ReferenceValue object representing the element.
+   * @param {string | string[]} files - The file path or an array of file paths to be set.
+   * @throws {Error} If the element is not a string or a ReferenceValue.
+   * @returns {Promise<void>} A promise that resolves when the files are set.
+   */
   async setFiles(browsingContextId, element, files) {
     if (typeof element !== 'string' && !(element instanceof ReferenceValue)) {
       throw Error(`Pass in a WebElement id as a string or a ReferenceValue. Received: ${element}`)

package/bidi/interceptPhase.js

@@ -15,6 +15,10 @@
 // specific language governing permissions and limitations
 // under the License.
 
+/**
+ * Represents the different phases of intercepting network requests and responses.
+ * @enum {string}
+ */
 const InterceptPhase = {
   BEFORE_REQUEST_SENT: 'beforeRequestSent',
   RESPONSE_STARTED: 'responseStarted',

package/bidi/logEntries.js

@@ -17,7 +17,18 @@
 
 'use strict'
 
+/**
+ * Represents a base log entry.
+ * Desribed in https://w3c.github.io/webdriver-bidi/#types-log-logentry.
+ */
 class BaseLogEntry {
+  /**
+   * Creates a new instance of BaseLogEntry.
+   * @param {string} level - The log level.
+   * @param {string} text - The log text.
+   * @param {number} timeStamp - The log timestamp.
+   * @param {string} stackTrace - The log stack trace.
+   */
   constructor(level, text, timeStamp, stackTrace) {
     this._level = level
     this._text = text
@@ -25,34 +36,72 @@ class BaseLogEntry {
     this._stackTrace = stackTrace
   }
 
+  /**
+   * Gets the log level.
+   * @returns {string} The log level.
+   */
   get level() {
     return this._level
   }
 
+  /**
+   * Gets the log text.
+   * @returns {string} The log text.
+   */
   get text() {
     return this._text
   }
 
+  /**
+   * Gets the log timestamp.
+   * @returns {number} The log timestamp.
+   */
   get timeStamp() {
     return this._timeStamp
   }
 
+  /**
+   * Gets the log stack trace.
+   * @returns {string} The log stack trace.
+   */
   get stackTrace() {
     return this._stackTrace
   }
 }
 
+/**
+ * Represents a generic log entry.
+ * @class
+ * @extends BaseLogEntry
+ */
 class GenericLogEntry extends BaseLogEntry {
+  /**
+   * Creates an instance of GenericLogEntry.
+   * @param {string} level - The log level.
+   * @param {string} text - The log text.
+   * @param {Date} timeStamp - The log timestamp.
+   * @param {string} type - The log type.
+   * @param {string} stackTrace - The log stack trace.
+   */
   constructor(level, text, timeStamp, type, stackTrace) {
     super(level, text, timeStamp, stackTrace)
     this._type = type
   }
 
+  /**
+   * Gets the log type.
+   * @returns {string} The log type.
+   */
   get type() {
     return this._type
   }
 }
 
+/**
+ * Represents a log entry for console logs.
+ * @class
+ * @extends GenericLogEntry
+ */
 class ConsoleLogEntry extends GenericLogEntry {
   constructor(level, text, timeStamp, type, method, realm, args, stackTrace) {
     super(level, text, timeStamp, type, stackTrace)
@@ -61,19 +110,36 @@ class ConsoleLogEntry extends GenericLogEntry {
     this._args = args
   }
 
+  /**
+   * Gets the method associated with the log entry.
+   * @returns {string} The method associated with the log entry.
+   */
   get method() {
     return this._method
   }
 
+  /**
+   * Gets the realm associated with the log entry.
+   * @returns {string} The realm associated with the log entry.
+   */
   get realm() {
     return this._realm
   }
 
+  /**
+   * Gets the arguments associated with the log entry.
+   * @returns {Array} The arguments associated with the log entry.
+   */
   get args() {
     return this._args
   }
 }
 
+/**
+ * Represents a log entry for JavaScript logs.
+ * @class
+ * @extends GenericLogEntry
+ */
 class JavascriptLogEntry extends GenericLogEntry {
   constructor(level, text, timeStamp, type, stackTrace) {
     super(level, text, timeStamp, type, stackTrace)

package/bidi/network.js

@@ -21,7 +21,17 @@ const { ContinueResponseParameters } = require('./continueResponseParameters')
 const { ContinueRequestParameters } = require('./continueRequestParameters')
 const { ProvideResponseParameters } = require('./provideResponseParameters')
 
+/**
+ * Represents all commands and events of Network module.
+ * Described in https://w3c.github.io/webdriver-bidi/#module-network.
+ */
 class Network {
+  /**
+   * Represents a Network object.
+   * @constructor
+   * @param {Driver} driver - The driver to fetch the BiDi connection.
+   * @param {Array} browsingContextIds - An array of browsing context IDs that the network events will be subscribed to.
+   */
   constructor(driver, browsingContextIds) {
     this._driver = driver
     this._browsingContextIds = browsingContextIds
@@ -31,22 +41,52 @@ class Network {
     this.bidi = await this._driver.getBidi()
   }
 
+  /**
+   * Subscribes to the 'network.beforeRequestSent' event and handles it with the provided callback.
+   *
+   * @param {Function} callback - The callback function to handle the event.
+   * @returns {Promise<void>} - A promise that resolves when the subscription is successful.
+   */
   async beforeRequestSent(callback) {
     await this.subscribeAndHandleEvent('network.beforeRequestSent', callback)
   }
 
+  /**
+   * Subscribes to the 'network.responseStarted' event and handles it with the provided callback.
+   *
+   * @param {Function} callback - The callback function to handle the event.
+   * @returns {Promise<void>} - A promise that resolves when the subscription is successful.
+   */
   async responseStarted(callback) {
     await this.subscribeAndHandleEvent('network.responseStarted', callback)
   }
 
+  /**
+   * Subscribes to the 'network.responseCompleted' event and handles it with the provided callback.
+   *
+   * @param {Function} callback - The callback function to handle the event.
+   * @returns {Promise<void>} - A promise that resolves when the subscription is successful.
+   */
   async responseCompleted(callback) {
     await this.subscribeAndHandleEvent('network.responseCompleted', callback)
   }
 
+  /**
+   * Subscribes to the 'network.authRequired' event and handles it with the provided callback.
+   *
+   * @param {Function} callback - The callback function to handle the event.
+   * @returns {Promise<void>} - A promise that resolves when the subscription is successful.
+   */
   async authRequired(callback) {
     await this.subscribeAndHandleEvent('network.authRequired', callback)
   }
 
+  /**
+   * Subscribes to the 'network.fetchError' event and handles it with the provided callback.
+   *
+   * @param {Function} callback - The callback function to handle the event.
+   * @returns {Promise<void>} - A promise that resolves when the subscription is successful.
+   */
   async fetchError(callback) {
     await this.subscribeAndHandleEvent('network.fetchError', callback)
   }
@@ -99,6 +139,13 @@ class Network {
     })
   }
 
+  /**
+   * Adds a network intercept.
+   *
+   * @param {AddInterceptParameters} params - The parameters for the network intercept.
+   * @returns {Promise<string>} - A promise that resolves to the added intercept's id.
+   * @throws {Error} - If params is not an instance of AddInterceptParameters.
+   */
   async addIntercept(params) {
     if (!(params instanceof AddInterceptParameters)) {
       throw new Error(`Params must be an instance of AddInterceptParameters. Received:'${params}'`)
@@ -114,6 +161,12 @@ class Network {
     return response.result.intercept
   }
 
+  /**
+   * Removes an intercept.
+   *
+   * @param {string} interceptId - The ID of the intercept to be removed.
+   * @returns {Promise<void>} - A promise that resolves when the intercept is successfully removed.
+   */
   async removeIntercept(interceptId) {
     const command = {
       method: 'network.removeIntercept',
@@ -123,6 +176,13 @@ class Network {
     await this.bidi.send(command)
   }
 
+  /**
+   * Continues the network request with authentication credentials.
+   * @param {string} requestId - The ID of the request to continue.
+   * @param {string} username - The username for authentication.
+   * @param {string} password - The password for authentication.
+   * @returns {Promise<void>} - A promise that resolves when the command is sent.
+   */
   async continueWithAuth(requestId, username, password) {
     const command = {
       method: 'network.continueWithAuth',
@@ -139,6 +199,12 @@ class Network {
     await this.bidi.send(command)
   }
 
+  /**
+   * Fails a network request.
+   *
+   * @param {number} requestId - The ID of the request to fail.
+   * @returns {Promise<void>} - A promise that resolves when the command is sent.
+   */
   async failRequest(requestId) {
     const command = {
       method: 'network.failRequest',
@@ -149,6 +215,11 @@ class Network {
     await this.bidi.send(command)
   }
 
+  /**
+   * Continues the network request with authentication but without providing credentials.
+   * @param {string} requestId - The ID of the request to continue with authentication.
+   * @returns {Promise<void>} - A promise that resolves when the command is sent.
+   */
   async continueWithAuthNoCredentials(requestId) {
     const command = {
       method: 'network.continueWithAuth',
@@ -160,6 +231,12 @@ class Network {
     await this.bidi.send(command)
   }
 
+  /**
+   * Cancels the authentication for a specific request.
+   *
+   * @param {string} requestId - The ID of the request to cancel authentication for.
+   * @returns {Promise<void>} - A promise that resolves when the command is sent.
+   */
   async cancelAuth(requestId) {
     const command = {
       method: 'network.continueWithAuth',
@@ -171,6 +248,13 @@ class Network {
     await this.bidi.send(command)
   }
 
+  /**
+   * Continues the network request with the provided parameters.
+   *
+   * @param {ContinueRequestParameters} params - The parameters for continuing the request.
+   * @throws {Error} If params is not an instance of ContinueRequestParameters.
+   * @returns {Promise<void>} A promise that resolves when the command is sent.
+   */
   async continueRequest(params) {
     if (!(params instanceof ContinueRequestParameters)) {
       throw new Error(`Params must be an instance of ContinueRequestParameters. Received:'${params}'`)
@@ -184,6 +268,13 @@ class Network {
     await this.bidi.send(command)
   }
 
+  /**
+   * Continues the network response with the given parameters.
+   *
+   * @param {ContinueResponseParameters} params - The parameters for continuing the response.
+   * @throws {Error} If params is not an instance of ContinueResponseParameters.
+   * @returns {Promise<void>} A promise that resolves when the command is sent.
+   */
   async continueResponse(params) {
     if (!(params instanceof ContinueResponseParameters)) {
       throw new Error(`Params must be an instance of ContinueResponseParameters. Received:'${params}'`)
@@ -197,6 +288,13 @@ class Network {
     await this.bidi.send(command)
   }
 
+  /**
+   * Provides a response for the network.
+   *
+   * @param {ProvideResponseParameters} params - The parameters for providing the response.
+   * @throws {Error} If params is not an instance of ProvideResponseParameters.
+   * @returns {Promise<void>} A promise that resolves when the command is sent.
+   */
   async provideResponse(params) {
     if (!(params instanceof ProvideResponseParameters)) {
       throw new Error(`Params must be an instance of ProvideResponseParameters. Received:'${params}'`)
@@ -210,6 +308,10 @@ class Network {
     await this.bidi.send(command)
   }
 
+  /**
+   * Unsubscribes from network events for all browsing contexts.
+   * @returns {Promise<void>} A promise that resolves when the network connection is closed.
+   */
   async close() {
     await this.bidi.unsubscribe(
       'network.beforeRequestSent',