selenium-webdriver 4.18.1 → 4.20.0

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

@@ -0,0 +1,122 @@
+// 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 the parameters for a continue request command.
+ * Described in https://w3c.github.io/webdriver-bidi/#command-network-continueRequest.
+ */
+class ContinueRequestParameters {
+  #map = new Map()
+
+  constructor(request) {
+    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})'`)
+    }
+    this.#map.set('body', Object.fromEntries(value.asMap()))
+    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) => {
+      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 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) => {
+      if (!(header instanceof Header)) {
+        throw new Error(`Header value must be an instance of Header. Received:'${header}'`)
+      }
+      headerList.push(Object.fromEntries(header.asMap()))
+    })
+
+    this.#map.set('headers', headerList)
+    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})'`)
+    }
+    this.#map.set('method', method)
+    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}'`)
+    }
+
+    this.#map.set('url', url)
+    return this
+  }
+
+  asMap() {
+    return this.#map
+  }
+}
+
+module.exports = { ContinueRequestParameters }

package/bidi/continueResponseParameters.js

@@ -0,0 +1,129 @@
+// 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 { 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()
+
+  constructor(request) {
+    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) => {
+      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 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}'`)
+    }
+
+    if (typeof password !== 'string') {
+      throw new Error(`Password must be a string. Received:'${password}'`)
+    }
+
+    this.#map.set('credentials', { type: 'password', username: username, password: password })
+
+    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) => {
+      if (!(header instanceof Header)) {
+        throw new Error(`Header value 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 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})'`)
+    }
+    this.#map.set('reasonPhrase', reasonPhrase)
+    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}'`)
+    }
+
+    this.#map.set('statusCode', statusCode)
+    return this
+  }
+
+  asMap() {
+    return this.#map
+  }
+}
+
+module.exports = { ContinueResponseParameters }

package/bidi/cookieFilter.js

@@ -0,0 +1,139 @@
+// 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 { 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}'`)
+    }
+    this.#map.set('value', Object.fromEntries(value.asMap()))
+    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}'`)
+    }
+    this.#map.set('sameSite', sameSite)
+    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
+  }
+
+  asMap() {
+    return this.#map
+  }
+}
+
+module.exports = { CookieFilter }

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