selenium-webdriver 4.19.0 → 4.20.0

package/bidi/captureScreenshotParameters.js

@@ -0,0 +1,96 @@
+// 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 { BoxClipRectangle, ElementClipRectangle } = require('./clipRectangle')
+
+/**
+ * Defines the reference point from which to compute offsets for capturing screenshot.
+ *
+ * @enum {string}
+ */
+const Origin = {
+  VIEWPORT: 'viewport',
+  DOCUMENT: 'document',
+}
+
+/**
+ * Represents the optional parameters for capturing a screenshot.
+ * Described in https://w3c.github.io/webdriver-bidi/#command-browsingContext-captureScreenshot.
+ */
+class CaptureScreenshotParameters {
+  #map = new Map()
+
+  /**
+   * Sets the origin for capturing the screenshot.
+   *
+   * @param {Origin} origin - The origin for capturing the screenshot. Must be one of `Origin.VIEWPORT` or `Origin.DOCUMENT`.
+   * @returns {CaptureScreenshotParameters} - The current instance of the CaptureScreenshotParameters for chaining.
+   * @throws {Error} - If the provided origin is not valid.
+   */
+  origin(origin) {
+    if (origin !== Origin.VIEWPORT && origin !== Origin.DOCUMENT) {
+      throw new Error(`Origin must be one of ${Object.values(Origin)}. Received:'${origin}'`)
+    }
+    this.#map.set('origin', origin)
+    return this
+  }
+
+  /**
+   * Sets the image format and quality for capturing a screenshot.
+   *
+   * @param {string} type - The image format type.
+   * @param {number} [quality] - The image quality (optional).
+   * @throws {Error} If the type is not a string or if the quality is not a number.
+   * @returns {CaptureScreenshotParameters} - The current instance of the CaptureScreenshotParameters for chaining.
+   */
+  imageFormat(type, quality = undefined) {
+    if (typeof type !== 'string') {
+      throw new Error(`Type must be an instance of String. Received:'${type}'`)
+    }
+
+    this.#map.set('type', type)
+
+    if (quality !== undefined) {
+      if (typeof quality !== 'number') {
+        throw new Error(`Quality must be a number. Received:'${quality}'`)
+      }
+      this.#map.set('quality', quality)
+    }
+    return this
+  }
+
+  /**
+   * Sets the clip rectangle for capturing a screenshot.
+   *
+   * @param {BoxClipRectangle|ElementClipRectangle} clipRectangle - The clip rectangle to set.
+   * @throws {Error} If the clipRectangle is not an instance of ClipRectangle.
+   * @returns {CaptureScreenshotParameters} - The current instance of the CaptureScreenshotParameters for chaining.
+   */
+  clipRectangle(clipRectangle) {
+    if (!(clipRectangle instanceof BoxClipRectangle || clipRectangle instanceof ElementClipRectangle)) {
+      throw new Error(`ClipRectangle must be an instance of ClipRectangle. Received:'${clipRectangle}'`)
+    }
+    this.#map.set('clip', Object.fromEntries(clipRectangle.asMap()))
+    return this
+  }
+
+  asMap() {
+    return this.#map
+  }
+}
+
+module.exports = { CaptureScreenshotParameters, Origin }

package/bidi/clipRectangle.js

@@ -0,0 +1,127 @@
+// 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.
+
+/**
+ * Represents a clip rectangle.
+ * Described in https://w3c.github.io/webdriver-bidi/#command-browsingContext-captureScreenshot.
+ */
+class ClipRectangle {
+  clipType
+
+  /**
+   * Constructs a new ClipRectangle object.
+   * @param {string} type - The type of the clip rectangle.
+   */
+  constructor(type) {
+    this.clipType = type
+  }
+
+  /**
+   * Gets the type of the clip rectangle.
+   * @returns {string} The type of the clip rectangle.
+   */
+  get type() {
+    return this.clipType
+  }
+
+  asMap() {}
+}
+
+/**
+ * Represents a clip rectangle for an element.
+ * @extends ClipRectangle
+ */
+class ElementClipRectangle extends ClipRectangle {
+  #sharedId
+  #handleId
+
+  /**
+   * Constructs a new ElementClipRectangle instance.
+   * @param {string} sharedId - The shared ID of the element.
+   * @param {string} [handleId] - The handle ID of the element (optional).
+   */
+  constructor(sharedId, handleId = undefined) {
+    super('element')
+    this.#sharedId = sharedId
+
+    if (handleId !== undefined) {
+      this.#handleId = handleId
+    }
+  }
+
+  /**
+   * Converts the ElementClipRectangle instance to a map.
+   * @returns {Map} - The converted map.
+   */
+  asMap() {
+    const map = new Map()
+    map.set('type', super.type)
+
+    const sharedReference = new Map()
+    sharedReference.set('sharedId', this.#sharedId)
+    if (this.#handleId !== undefined) {
+      sharedReference.set('handleId', this.#handleId)
+    }
+
+    map.set('element', Object.fromEntries(sharedReference))
+
+    return map
+  }
+}
+
+/**
+ * Represents a box-shaped clip rectangle.
+ * @extends ClipRectangle
+ */
+class BoxClipRectangle extends ClipRectangle {
+  #x
+  #y
+  #width
+  #height
+
+  /**
+   * Constructs a new BoxClipRectangle object.
+   * @param {number} x - The x-coordinate of the top-left corner of the rectangle.
+   * @param {number} y - The y-coordinate of the top-left corner of the rectangle.
+   * @param {number} width - The width of the rectangle.
+   * @param {number} height - The height of the rectangle.
+   */
+  constructor(x, y, width, height) {
+    super('box')
+    this.#x = x
+    this.#y = y
+    this.#width = width
+    this.#height = height
+  }
+
+  /**
+   * Converts the BoxClipRectangle object to a Map.
+   * @returns {Map<string, any>} - The Map representation of the BoxClipRectangle object.
+   */
+  asMap() {
+    const map = new Map()
+    map.set('type', super.type)
+    map.set('x', this.#x)
+    map.set('y', this.#y)
+    map.set('width', this.#width)
+    map.set('height', this.#height)
+
+    return map
+  }
+}
+
+module.exports = { BoxClipRectangle, ElementClipRectangle }

package/bidi/continueRequestParameters.js

@@ -17,6 +17,10 @@
 
 const { BytesValue, Header } = require('./networkTypes')
 
+/**
+ * Represents the parameters for a continue request command.
+ * Described in https://w3c.github.io/webdriver-bidi/#command-network-continueRequest.
+ */
 class ContinueRequestParameters {
   #map = new Map()
 
@@ -24,6 +28,13 @@ class ContinueRequestParameters {
     this.#map.set('request', request)
   }
 
+  /**
+   * Sets the body value for the request.
+   *
+   * @param {BytesValue} value - The value to set as the body. Must be an instance of BytesValue.
+   * @returns {ContinueRequestParameters} - The current instance of the ContinueRequestParameters for chaining.
+   * @throws {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: '${value})'`)
@@ -32,6 +43,13 @@ class ContinueRequestParameters {
     return this
   }
 
+  /**
+   * Sets the cookies for the request.
+   *
+   * @param {Header[]} cookieHeaders - An array of cookie headers.
+   * @returns {continueRequestParameters} - The current instance of the ContinueRequestParameters for chaining.
+   * @throws {Error} - If a cookie header is not an instance of Header.
+   */
   cookies(cookieHeaders) {
     const cookies = []
     cookieHeaders.forEach((header) => {
@@ -45,6 +63,13 @@ class ContinueRequestParameters {
     return this
   }
 
+  /**
+   * Sets the headers for the request.
+   *
+   * @param {Header[]} headers - An array of Header objects.
+   * @returns {ContinueRequestParameters} - The current instance of the ContinueRequestParameters for chaining.
+   * @throws {Error} - If the header value is not an instance of Header.
+   */
   headers(headers) {
     const headerList = []
     headers.forEach((header) => {
@@ -58,6 +83,13 @@ class ContinueRequestParameters {
     return this
   }
 
+  /**
+   * Sets the HTTP method for the request.
+   *
+   * @param {string} method - The HTTP method to be set.
+   * @returns {ContinueRequestParameters} - The updated `continueRequestParameters` object.
+   * @throws {Error} - If the method parameter is not a string.
+   */
   method(method) {
     if (typeof method !== 'string') {
       throw new Error(`Http method must be a string. Received: '${method})'`)
@@ -66,6 +98,13 @@ class ContinueRequestParameters {
     return this
   }
 
+  /**
+   * Sets the URL for the request.
+   *
+   * @param {string} url - The URL to set for the request.
+   * @returns {ContinueRequestParameters} - The current instance of the ContinueRequestParameters for chaining.
+   * @throws {Error} - If the url parameter is not a string.
+   */
   url(url) {
     if (typeof url !== 'string') {
       throw new Error(`Url must be a string. Received:'${url}'`)

package/bidi/continueResponseParameters.js

@@ -17,6 +17,10 @@
 
 const { Header } = require('./networkTypes')
 
+/**
+ * Represents the parameters for a continue response.
+ * Described in https://w3c.github.io/webdriver-bidi/#command-network-continueResponse.
+ */
 class ContinueResponseParameters {
   #map = new Map()
 
@@ -24,6 +28,13 @@ class ContinueResponseParameters {
     this.#map.set('request', request)
   }
 
+  /**
+   * Sets the cookies for the response.
+   *
+   * @param {Header[]} cookieHeaders - The array of cookie headers.
+   * @returns {ContinueResponseParameters} - The current instance of the ContinueResponseParameters for chaining.
+   * @throws {Error} - If the cookieHeader is not an instance of Header.
+   */
   cookies(cookieHeaders) {
     const cookies = []
     cookieHeaders.forEach((header) => {
@@ -37,6 +48,14 @@ class ContinueResponseParameters {
     return this
   }
 
+  /**
+   * Sets the credentials for authentication.
+   *
+   * @param {string} username - The username for authentication.
+   * @param {string} password - The password for authentication.
+   * @returns {ContinueResponseParameters} The current instance of the ContinueResponseParameters for chaining.
+   * @throws {Error} If username or password is not a string.
+   */
   credentials(username, password) {
     if (typeof username !== 'string') {
       throw new Error(`Username must be a string. Received:'${username}'`)
@@ -51,6 +70,13 @@ class ContinueResponseParameters {
     return this
   }
 
+  /**
+   * Sets the headers for the response.
+   *
+   * @param {Header[]} headers - An array of Header objects representing the headers.
+   * @returns {ContinueResponseParameters} - The current instance of the ContinueResponseParameters for chaining.
+   * @throws {Error} - If the header value is not an instance of Header.
+   */
   headers(headers) {
     const headerList = []
     headers.forEach((header) => {
@@ -64,6 +90,13 @@ class ContinueResponseParameters {
     return this
   }
 
+  /**
+   * Sets the reason phrase for the response.
+   *
+   * @param {string} reasonPhrase - The reason phrase for the response.
+   * @returns {ContinueResponseParameters} - The current instance of the ContinueResponseParameters 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})'`)
@@ -72,6 +105,13 @@ class ContinueResponseParameters {
     return this
   }
 
+  /**
+   * Sets the status code for the response.
+   *
+   * @param {number} statusCode - The status code to set.
+   * @returns {ContinueResponseParameters} - The current instance of the ContinueResponseParameters for chaining.
+   * @throws {Error} - If the `statusCode` parameter is not an integer.
+   */
   statusCode(statusCode) {
     if (!Number.isInteger(statusCode)) {
       throw new Error(`Status must be an integer. Received:'${statusCode}'`)

package/bidi/cookieFilter.js

@@ -17,14 +17,31 @@
 
 const { SameSite, BytesValue } = require('./networkTypes')
 
+/**
+ * Represents a filter for fetching cookies.
+ * Described in https://w3c.github.io/webdriver-bidi/#command-storage-getCookies
+ */
 class CookieFilter {
   #map = new Map()
 
+  /**
+   * Sets the name of the cookie.
+   *
+   * @param {string} name - The name of the cookie.
+   * @returns {CookieFilter} - The updated CookieFilter instance for chaining.
+   */
   name(name) {
     this.#map.set('name', name)
     return this
   }
 
+  /**
+   * Sets the value of the cookie.
+   *
+   * @param {BytesValue} value - The value to be set. Must be an instance of BytesValue.
+   * @returns {CookieFilter} - The updated CookieFilter instance for chaining.
+   * @throws {Error} - If the value is not an instance of BytesValue.
+   */
   value(value) {
     if (!(value instanceof BytesValue)) {
       throw new Error(`Value must be an instance of BytesValue. Received:'${value}'`)
@@ -33,31 +50,68 @@ class CookieFilter {
     return this
   }
 
+  /**
+   * Sets the domain for the cookie.
+   *
+   * @param {string} domain - The domain to set.
+   * @returns {CookieFilter} - The updated CookieFilter instance for chaining.
+   */
   domain(domain) {
     this.#map.set('domain', domain)
     return this
   }
 
+  /**
+   * Sets the url path for the cookie to be fetched.
+   *
+   * @param {string} path - The url path for the cookie to be fetched.
+   * @returns {CookieFilter} - The updated CookieFilter instance for chaining.
+   */
   path(path) {
     this.#map.set('path', path)
     return this
   }
 
+  /**
+   * Sets the size of the cookie to be fetched.
+   *
+   * @param {number} size - The size of the cookie.
+   * @returns {CookieFilter} - The updated CookieFilter instance for chaining.
+   */
   size(size) {
     this.#map.set('size', size)
     return this
   }
 
+  /**
+   * Sets the `httpOnly` flag for the cookie filter.
+   *
+   * @param {boolean} httpOnly - The value to set for the `httpOnly` flag.
+   * @returns {CookieFilter} - The updated CookieFilter instance for chaining.
+   */
   httpOnly(httpOnly) {
     this.#map.set('httpOnly', httpOnly)
     return this
   }
 
+  /**
+   * Sets the flag to fetch secure cookies.
+   *
+   * @param {boolean} secure - Whether the cookie fetched should be secure only or not.
+   * @returns {CookieFilter} - The updated CookieFilter instance for chaining.
+   */
   secure(secure) {
     this.#map.set('secure', secure)
     return this
   }
 
+  /**
+   * Sets the SameSite attribute for the cookie.
+   *
+   * @param {SameSite} sameSite - The SameSite value to be set for the cookie.
+   * @returns {CookieFilter} - The updated CookieFilter instance for chaining.
+   * @throws {Error} - If the provided sameSite value is not an instance of SameSite.
+   */
   sameSite(sameSite) {
     if (!(sameSite instanceof SameSite)) {
       throw new Error(`Params must be a value in SameSite. Received:'${sameSite}'`)
@@ -66,6 +120,12 @@ class CookieFilter {
     return this
   }
 
+  /**
+   * Sets the expiry value.
+   *
+   * @param {number} expiry - The expiry value.
+   * @returns {CookieFilter} - The updated CookieFilter instance for chaining.
+   */
   expiry(expiry) {
     this.#map.set('expiry', expiry)
     return this

package/bidi/createContextParameters.js

@@ -0,0 +1,73 @@
+// 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.
+
+/**
+ * Represents a set of parameters for creating a context.
+ * Described in https://w3c.github.io/webdriver-bidi/#command-browsingContext-create.
+ */
+class CreateContextParameters {
+  #map = new Map()
+
+  /**
+   * Sets the reference context.
+   * @param {string} id - The ID of the reference context.
+   * @returns {CreateContextParameters} - The updated instance of CreateContextParameters for chaining.
+   * @throws {Error} - If the provided ID is not a string.
+   */
+  referenceContext(id) {
+    if (typeof id !== 'string') {
+      throw new Error(`ReferenceContext must be string. Received:'${id}'`)
+    }
+    this.#map.set('referenceContext', id)
+    return this
+  }
+
+  /**
+   * Sets the background parameter.
+   *
+   * @param {boolean} background - The background value to set.
+   * @returns {CreateContextParameters} - The updated instance of CreateContextParameters for chaining.
+   * @throws {Error} - If the background parameter is not a boolean.
+   */
+  background(background) {
+    if (typeof background !== 'boolean') {
+      throw new Error(`Background must be boolean. Received:'${background}'`)
+    }
+    this.#map.set('background', background)
+    return this
+  }
+
+  /**
+   * Sets the user context.
+   * @param {string} userContext - The user context to set.
+   * @returns {CreateContextParameters} - The updated instance of CreateContextParameters for chaining.
+   * @throws {Error} - If the userContext parameter is not a string.
+   */
+  userContext(userContext) {
+    if (typeof userContext !== 'string') {
+      throw new Error(`UserContext must be string. Received:'${userContext}'`)
+    }
+    this.#map.set('userContext', userContext)
+    return this
+  }
+
+  asMap() {
+    return this.#map
+  }
+}
+
+module.exports = { CreateContextParameters }

package/bidi/evaluateResult.js

@@ -15,11 +15,20 @@
 // specific language governing permissions and limitations
 // under the License.
 
+/**
+ * Represents the type of script evaluation result.
+ * Described in https://w3c.github.io/webdriver-bidi/#type-script-EvaluateResult.
+ * @enum {string}
+ */
 const EvaluateResultType = {
   SUCCESS: 'success',
   EXCEPTION: 'exception',
 }
 
+/**
+ * Represents a successful evaluation result.
+ * @class
+ */
 class EvaluateResultSuccess {
   constructor(realmId, value) {
     this.resultType = EvaluateResultType.SUCCESS
@@ -28,6 +37,10 @@ class EvaluateResultSuccess {
   }
 }
 
+/**
+ * Represents an exception that occurred during evaluation of a result.
+ * @class
+ */
 class EvaluateResultException {
   constructor(realmId, exceptionDetails) {
     this.resultType = EvaluateResultType.EXCEPTION
@@ -36,6 +49,10 @@ class EvaluateResultException {
   }
 }
 
+/**
+ * Represents details of an exception.
+ * @class
+ */
 class ExceptionDetails {
   constructor(exceptionDetails) {
     this.columnNumber = 'columnNumber' in exceptionDetails ? exceptionDetails['columnNumber'] : null

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')
 

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',