selenium-webdriver 4.18.1 → 4.20.0

package/bidi/index.js

@@ -15,7 +15,6 @@
 // specific language governing permissions and limitations
 // under the License.
 
-// eslint-disable-next-line node/no-missing-require
 const { EventEmitter } = require('node:events')
 const WebSocket = require('ws')
 
@@ -40,6 +39,31 @@ class Index extends EventEmitter {
     })
   }
 
+  /**
+   * @returns {WebSocket}
+   */
+  get socket() {
+    return this._ws
+  }
+
+  /**
+   * @returns {boolean|*}
+   */
+  get isConnected() {
+    return this.connected
+  }
+
+  /**
+   * Get Bidi Status
+   * @returns {Promise<*>}
+   */
+  get status() {
+    return this.send({
+      method: 'session.status',
+      params: {},
+    })
+  }
+
   /**
    * Resolve connection
    * @returns {Promise<unknown>}
@@ -56,20 +80,6 @@ class Index extends EventEmitter {
     })
   }
 
-  /**
-   * @returns {WebSocket}
-   */
-  get socket() {
-    return this._ws
-  }
-
-  /**
-   * @returns {boolean|*}
-   */
-  get isConnected() {
-    return this.connected
-  }
-
   /**
    * Sends a bidi request
    * @param params
@@ -183,17 +193,6 @@ class Index extends EventEmitter {
     await this.send(params)
   }
 
-  /**
-   * Get Bidi Status
-   * @returns {Promise<*>}
-   */
-  get status() {
-    return this.send({
-      method: 'session.status',
-      params: {},
-    })
-  }
-
   /**
    * Close ws connection.
    * @returns {Promise<unknown>}

package/bidi/input.js

@@ -18,7 +18,12 @@
 // type: module added to package.json
 // import { WebElement } from '../lib/webdriver'
 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
@@ -32,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)
 
@@ -43,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',
@@ -57,6 +73,34 @@ 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}`)
+    }
+
+    const command = {
+      method: 'input.setFiles',
+      params: {
+        context: browsingContextId,
+        element:
+          typeof element === 'string'
+            ? new ReferenceValue(RemoteReferenceType.SHARED_ID, element).asMap()
+            : element.asMap(),
+        files: typeof files === 'string' ? [files] : files,
+      },
+    }
+    await this.bidi.send(command)
+  }
 }
 
 async function updateActions(actions) {

package/bidi/interceptPhase.js

@@ -15,10 +15,14 @@
 // 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',
   AUTH_REQUIRED: 'authRequired',
 }
 
-module.exports = {InterceptPhase}
+module.exports = { InterceptPhase }

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

@@ -15,10 +15,23 @@
 // specific language governing permissions and limitations
 // under the License.
 
-const { BeforeRequestSent, ResponseStarted, FetchError} = require('./networkTypes')
-const {AddInterceptParameters} = require("./addInterceptParameters");
+const { BeforeRequestSent, ResponseStarted, FetchError } = require('./networkTypes')
+const { AddInterceptParameters } = require('./addInterceptParameters')
+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
@@ -28,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)
   }
@@ -92,19 +135,25 @@ class Network {
           )
         }
         callback(response)
-        }
+      }
     })
   }
 
+  /**
+   * 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 AddInterceptParamenters. Received:'${params}'`)
+    if (!(params instanceof AddInterceptParameters)) {
+      throw new Error(`Params must be an instance of AddInterceptParameters. Received:'${params}'`)
     }
 
     const command = {
       method: 'network.addIntercept',
-      params: Object.fromEntries(params.asMap())
+      params: Object.fromEntries(params.asMap()),
     }
 
     let response = await this.bidi.send(command)
@@ -112,61 +161,165 @@ 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',
-      params: {intercept: interceptId},
+      params: { intercept: interceptId },
     }
 
     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',
-            params: {
-              request: requestId.toString(),
-              action: 'provideCredentials',
-              credentials: {
-                type: 'password',
-                username: username,
-                password: password
-              },
-            },
-          }
+      method: 'network.continueWithAuth',
+      params: {
+        request: requestId.toString(),
+        action: 'provideCredentials',
+        credentials: {
+          type: 'password',
+          username: username,
+          password: password,
+        },
+      },
+    }
+    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',
+      params: {
+        request: requestId.toString(),
+      },
+    }
     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',
       params: {
         request: requestId.toString(),
-        action: 'default'
+        action: 'default',
       },
     }
     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',
       params: {
         request: requestId.toString(),
-        action: 'cancel'
+        action: 'cancel',
       },
     }
     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}'`)
+    }
+
+    const command = {
+      method: 'network.continueRequest',
+      params: Object.fromEntries(params.asMap()),
+    }
+
+    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}'`)
+    }
+
+    const command = {
+      method: 'network.continueResponse',
+      params: Object.fromEntries(params.asMap()),
+    }
+
+    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}'`)
+    }
+
+    const command = {
+      method: 'network.provideResponse',
+      params: Object.fromEntries(params.asMap()),
+    }
+
+    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',
       'network.responseStarted',
       'network.responseCompleted',
-      'network.authRequired')
+      'network.authRequired',
+    )
   }
-
 }
 
 async function getNetworkInstance(driver, browsingContextIds = null) {