[js] Add JS comments for BiDi related files (#13763)

Author: pujagani

javascript/node/selenium-webdriver/bidi/addInterceptParameters.js

@@ -29,6 +29,13 @@ class AddInterceptParameters {
     }
   }
 
+  /**
+   * Adds a URL pattern to intercept.
+   *
+   * @param {UrlPattern} pattern - The URL pattern to add.
+   * @returns {AddInterceptParameters} - Returns the current instance of the class AddInterceptParameters for chaining.
+   * @throws {Error} - Throws an error if the pattern is not an instance of UrlPattern.
+   */
   urlPattern(pattern) {
     if (!(pattern instanceof UrlPattern)) {
       throw new Error(`Pattern must be an instance of UrlPattern. Received: '${pattern})'`)
@@ -37,6 +44,13 @@ class AddInterceptParameters {
     return this
   }
 
+  /**
+   * Adds array of URL patterns to intercept.
+   *
+   * @param {UrlPattern[]} patterns - An array of UrlPattern instances representing the URL patterns to intercept.
+   * @returns {AddInterceptParameters} - Returns the instance of AddInterceptParameters for chaining.
+   * @throws {Error} - Throws an error if the pattern is not an instance of UrlPattern.
+   */
   urlPatterns(patterns) {
     patterns.forEach((pattern) => {
       if (!(pattern instanceof UrlPattern)) {
@@ -47,6 +61,13 @@ class AddInterceptParameters {
     return this
   }
 
+  /**
+   * Adds string URL to intercept.
+   *
+   * @param {string} pattern - The URL pattern to be added.
+   * @returns {AddInterceptParameters} - Returns the instance of AddInterceptParameters for chaining..
+   * @throws {Error} - If the pattern is not an instance of String.
+   */
   urlStringPattern(pattern) {
     if (!(pattern instanceof String)) {
       throw new Error(`Pattern must be an instance of String. Received:'${pattern}'`)
@@ -56,6 +77,11 @@ class AddInterceptParameters {
     return this
   }
 
+  /**
+   * Adds array of string URLs to intercept.
+   * @param {string[]} patterns - An array of URL string patterns.
+   * @returns {this} - Returns the instance of AddInterceptParameters for chaining.
+   */
   urlStringPatterns(patterns) {
     patterns.forEach((pattern) => {
       if (!(pattern instanceof String)) {

javascript/node/selenium-webdriver/bidi/browser.js

@@ -15,6 +15,10 @@
 // specific language governing permissions and limitations
 // under the License.
 
+/**
+ * Represents the commands and events under Browser Module.
+ * Described in https://w3c.github.io/webdriver-bidi/#module-browser
+ */
 class Browser {
   constructor(driver) {
     this._driver = driver
@@ -28,6 +32,10 @@ class Browser {
     this.bidi = await this._driver.getBidi()
   }
 
+  /**
+   * Creates a new user context.
+   * @returns {Promise<string>} A promise that resolves to the user context id.
+   */
   async createUserContext() {
     const command = {
       method: 'browser.createUserContext',
@@ -39,6 +47,10 @@ class Browser {
     return response.result.userContext
   }
 
+  /**
+   * Gets the list of all user contexts.
+   * @returns {Promise<string[]>} A promise that resolves to an array of user context ids.
+   */
   async getUserContexts() {
     const command = {
       method: 'browser.getUserContexts',
@@ -58,6 +70,11 @@ class Browser {
     return userContexts
   }
 
+  /**
+   * Removes a user context.
+   * @param {string} userContext The user context id to be removed.
+   * @returns {Promise<void>}
+   */
   async removeUserContext(userContext) {
     const command = {
       method: 'browser.removeUserContext',

javascript/node/selenium-webdriver/bidi/browsingContext.js

@@ -21,6 +21,10 @@ const { SerializationOptions, ReferenceValue, RemoteValue } = require('./protoco
 const { WebElement } = require('../lib/webdriver')
 const { CaptureScreenshotParameters } = require('./captureScreenshotParameters')
 
+/**
+ * Represents the locator to locate nodes in the browsing context.
+ * Described in https://w3c.github.io/webdriver-bidi/#type-browsingContext-Locator.
+ */
 class Locator {
   static Type = Object.freeze({
     CSS: 'css',
@@ -42,14 +46,35 @@ class Locator {
     this.#maxDepth = maxDepth
   }
 
+  /**
+   * Creates a new Locator object with CSS selector type.
+   *
+   * @param {string} value - The CSS selector value.
+   * @returns {Locator} A new Locator object with CSS selector type.
+   */
   static css(value) {
     return new Locator(Locator.Type.CSS, value)
   }
 
+  /**
+   * Creates a new Locator object with the given XPath value.
+   *
+   * @param {string} value - The XPath value.
+   * @returns {Locator} A new Locator object.
+   */
   static xpath(value) {
     return new Locator(Locator.Type.XPATH, value)
   }
 
+  /**
+   * Creates a new Locator object with the specified inner text value.
+   *
+   * @param {string} value - The inner text value to locate.
+   * @param {boolean|undefined} [ignoreCase] - Whether to ignore the case when matching the inner text value.
+   * @param {string|undefined} [matchType] - The type of matching to perform (full or partial).
+   * @param {number|undefined} [maxDepth] - The maximum depth to search for the inner text value.
+   * @returns {Locator} A new Locator object with the specified inner text value.
+   */
   static innerText(value, ignoreCase = undefined, matchType = undefined, maxDepth = undefined) {
     return new Locator(Locator.Type.INNER_TEXT, value, ignoreCase, matchType, maxDepth)
   }
@@ -67,6 +92,12 @@ class Locator {
   }
 }
 
+/**
+ * Represents the contains under BrowsingContext module commands.
+ * Described in https://w3c.github.io/webdriver-bidi/#module-browsingContext
+ * Each browsing context command requires a browsing context id.
+ * Hence, this class represent browsing context lifecycle.
+ */
 class BrowsingContext {
   constructor(driver) {
     this._driver = driver
@@ -225,6 +256,13 @@ class BrowsingContext {
     return new PrintResult(response.result.data)
   }
 
+  /**
+   * Captures a screenshot of the browsing context.
+   *
+   * @param {CaptureScreenshotParameters|undefined} [captureScreenshotParameters] - Optional parameters for capturing the screenshot.
+   * @returns {Promise<string>} - A promise that resolves to the base64-encoded string representation of the captured screenshot.
+   * @throws {InvalidArgumentError} - If the provided captureScreenshotParameters is not an instance of CaptureScreenshotParameters.
+   */
   async captureScreenshot(captureScreenshotParameters = undefined) {
     if (
       captureScreenshotParameters !== undefined &&
@@ -273,6 +311,12 @@ class BrowsingContext {
     return response['result']['data']
   }
 
+  /**
+   * Captures a screenshot of a specific element within the browsing context.
+   * @param {string} sharedId - The shared ID of the element to capture.
+   * @param {string} [handle] - The handle of the element to capture (optional).
+   * @returns {Promise<string>} A promise that resolves to the base64-encoded screenshot data.
+   */
   async captureElementScreenshot(sharedId, handle = undefined) {
     let params = {
       method: 'browsingContext.captureScreenshot',
@@ -307,6 +351,11 @@ class BrowsingContext {
     }
   }
 
+  /**
+   * Activates and focuses the top-level browsing context.
+   * @returns {Promise<void>} A promise that resolves when the browsing context is activated.
+   * @throws {Error} If there is an error while activating the browsing context.
+   */
   async activate() {
     const params = {
       method: 'browsingContext.activate',
@@ -321,6 +370,13 @@ class BrowsingContext {
     }
   }
 
+  /**
+   * Handles a user prompt in the browsing context.
+   *
+   * @param {boolean} [accept] - Optional. Indicates whether to accept or dismiss the prompt.
+   * @param {string} [userText] - Optional. The text to enter.
+   * @throws {Error} If an error occurs while handling the user prompt.
+   */
   async handleUserPrompt(accept = undefined, userText = undefined) {
     const params = {
       method: 'browsingContext.handleUserPrompt',
@@ -337,6 +393,15 @@ class BrowsingContext {
     }
   }
 
+  /**
+   * Reloads the current browsing context.
+   *
+   * @param {boolean} [ignoreCache] - Whether to ignore the cache when reloading.
+   * @param {string} [readinessState] - The readiness state to wait for before returning.
+   *        Valid readiness states are 'none', 'interactive', and 'complete'.
+   * @returns {Promise<NavigateResult>} - A promise that resolves to the result of the reload operation.
+   * @throws {Error} - If an invalid readiness state is provided.
+   */
   async reload(ignoreCache = undefined, readinessState = undefined) {
     if (readinessState !== undefined && !['none', 'interactive', 'complete'].includes(readinessState)) {
       throw Error(`Valid readiness states are 'none', 'interactive' & 'complete'. Received: ${readinessState}`)
@@ -355,6 +420,13 @@ class BrowsingContext {
     return new NavigateResult(navigateResult['url'], navigateResult['navigation'])
   }
 
+  /**
+   * Sets the viewport size and device pixel ratio for the browsing context.
+   * @param {number} width - The width of the viewport.
+   * @param {number} height - The height of the viewport.
+   * @param {number} [devicePixelRatio] - The device pixel ratio (optional)
+   * @throws {Error} If an error occurs while setting the viewport.
+   */
   async setViewport(width, height, devicePixelRatio = undefined) {
     const params = {
       method: 'browsingContext.setViewport',
@@ -370,6 +442,12 @@ class BrowsingContext {
     }
   }
 
+  /**
+   * Traverses the browsing context history by a given delta.
+   *
+   * @param {number} delta - The delta value to traverse the history. A positive value moves forward, while a negative value moves backward.
+   * @returns {Promise<void>} - A promise that resolves when the history traversal is complete.
+   */
   async traverseHistory(delta) {
     const params = {
       method: 'browsingContext.traverseHistory',
@@ -381,14 +459,38 @@ class BrowsingContext {
     await this.bidi.send(params)
   }
 
+  /**
+   * Moves the browsing context forward by one step in the history.
+   * @returns {Promise<void>} A promise that resolves when the browsing context has moved forward.
+   */
   async forward() {
     await this.traverseHistory(1)
   }
 
+  /**
+   * Navigates the browsing context to the previous page in the history.
+   * @returns {Promise<void>} A promise that resolves when the navigation is complete.
+   */
   async back() {
     await this.traverseHistory(-1)
   }
 
+  /**
+   * Locates nodes in the browsing context.
+   *
+   * @param {Locator} locator - The locator object used to locate the nodes.
+   * @param {number} [maxNodeCount] - The maximum number of nodes to locate (optional).
+   * @param {string} [ownership] - The ownership type of the nodes (optional).
+   * @param {string} [sandbox] - The sandbox name for locating nodes (optional).
+   * @param {SerializationOptions} [serializationOptions] - The serialization options for locating nodes (optional).
+   * @param {ReferenceValue[]} [startNodes] - The array of start nodes for locating nodes (optional).
+   * @returns {Promise<RemoteValue[]>} - A promise that resolves to the arrays of located nodes.
+   * @throws {Error} - If the locator is not an instance of Locator.
+   * @throws {Error} - If the serializationOptions is provided but not an instance of SerializationOptions.
+   * @throws {Error} - If the ownership is provided but not 'root' or 'none'.
+   * @throws {Error} - If the startNodes is provided but not an array of ReferenceValue objects.
+   * @throws {Error} - If any of the startNodes is not an instance of ReferenceValue.
+   */
   async locateNodes(
     locator,
     maxNodeCount = undefined,
@@ -448,6 +550,16 @@ class BrowsingContext {
     return remoteValues
   }
 
+  /**
+   * Locates a single node in the browsing context.
+   *
+   * @param {Locator} locator - The locator used to find the node.
+   * @param {string} [ownership] - The ownership of the node (optional).
+   * @param {string} [sandbox] - The sandbox of the node (optional).
+   * @param {SerializationOptions} [serializationOptions] - The serialization options for the node (optional).
+   * @param {Array} [startNodes] - The starting nodes for the search (optional).
+   * @returns {Promise<RemoteValue>} - A promise that resolves to the located node.
+   */
   async locateNode(
     locator,
     ownership = undefined,
@@ -475,26 +587,44 @@ class BrowsingContext {
   }
 }
 
+/**
+ * Represents the result of a navigation operation.
+ */
 class NavigateResult {
   constructor(url, navigationId) {
     this._url = url
     this._navigationId = navigationId
   }
 
+  /**
+   * Gets the URL of the navigated page.
+   * @returns {string} The URL of the navigated page.
+   */
   get url() {
     return this._url
   }
 
+  /**
+   * Gets the ID of the navigation operation.
+   * @returns {number} The ID of the navigation operation.
+   */
   get navigationId() {
     return this._navigationId
   }
 }
 
+/**
+ * Represents a print result.
+ */
 class PrintResult {
   constructor(data) {
     this._data = data
   }
 
+  /**
+   * Gets the data associated with the print result.
+   * @returns {any} The data associated with the print result.
+   */
   get data() {
     return this._data
   }
@@ -514,9 +644,5 @@ async function getBrowsingContextInstance(driver, { browsingContextId, type, ref
   return instance
 }
 
-/**
- * API
- * @type {function(*, {*,*,*}): Promise<BrowsingContext>}
- */
 module.exports = getBrowsingContextInstance
 module.exports.Locator = Locator