selenium-webdriver 4.18.1 → 4.20.0

package/bidi/partialCookie.js

@@ -0,0 +1,115 @@
+// 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 } = require('./networkTypes')
+
+/**
+ * Represents a partial cookie used to set cookies.
+ * Described in https://w3c.github.io/webdriver-bidi/#command-storage-setCookie.
+ * @class
+ */
+class PartialCookie {
+  #map = new Map()
+
+  /**
+   * Represents a partial cookie.
+   * @class
+   * @param {string} name - The name of the cookie.
+   * @param {BytesValue} value - The value of the cookie as an instance of BytesValue.
+   * @param {string} domain - The domain of the cookie.
+   */
+  constructor(name, value, domain) {
+    this.#map.set('name', name)
+    if (!(value instanceof BytesValue)) {
+      throw new Error(`Value must be an instance of BytesValue. Received:'${value}'`)
+    }
+    this.#map.set('value', Object.fromEntries(value.asMap()))
+    this.#map.set('domain', domain)
+  }
+
+  /**
+   * Sets the path for the cookie.
+   *
+   * @param {string} path - The path for the cookie.
+   * @returns {PartialCookie} - The updated PartialCookie instance for chaining.
+   */
+  path(path) {
+    this.#map.set('path', path)
+    return this
+  }
+
+  /**
+   * Sets the size of the cookie.
+   *
+   * @param {number} size - The size of the cookie.
+   * @returns {PartialCookie} - The updated PartialCookie instance for chaining.
+   */
+  size(size) {
+    this.#map.set('size', size)
+    return this
+  }
+
+  /**
+   * Sets the `httpOnly` flag for the cookie.
+   *
+   * @param {boolean} httpOnly - The value to set for the `httpOnly` flag.
+   * @returns {PartialCookie} - The updated PartialCookie instance for chaining.
+   */
+  httpOnly(httpOnly) {
+    this.#map.set('httpOnly', httpOnly)
+    return this
+  }
+
+  /**
+   * Sets the secure flag for the cookie.
+   *
+   * @param {boolean} secure - Indicates whether the cookie should only be sent over secure connections.
+   * @returns {PartialCookie} - The updated PartialCookie instance for chaining.
+   */
+  secure(secure) {
+    this.#map.set('secure', secure)
+    return this
+  }
+
+  /**
+   * Sets the SameSite attribute for the cookie.
+   *
+   * @param {SameSite} sameSite - The SameSite attribute value for the cookie.
+   * @returns {PartialCookie} - The updated PartialCookie instance for chaining.
+   */
+  sameSite(sameSite) {
+    this.#map.set('sameSite', sameSite)
+    return this
+  }
+
+  /**
+   * Sets the expiry for the cookie.
+   *
+   * @param {number} expiry - The expiry time of the cookie.
+   * @returns {PartialCookie} - The updated PartialCookie instance for chaining.
+   */
+  expiry(expiry) {
+    this.#map.set('expiry', expiry)
+    return this
+  }
+
+  asMap() {
+    return this.#map
+  }
+}
+
+module.exports = { PartialCookie }

package/bidi/partitionDescriptor.js

@@ -0,0 +1,102 @@
+// 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 the types of partition descriptors.
+ * @enum {string}
+ * Described in https://w3c.github.io/webdriver-bidi/#command-storage-getCookies.
+ */
+const Type = {
+  CONTEXT: 'context',
+  STORAGE_KEY: 'storageKey',
+}
+
+/**
+ * Represents a partition descriptor.
+ * Described in https://w3c.github.io/webdriver-bidi/#command-storage-getCookies.
+ */
+class PartitionDescriptor {
+  /*eslint no-unused-private-class-members: "off"*/
+  #type
+
+  /**
+   * Constructs a new PartitionDescriptor instance.
+   * @param {Type} type - The type of the partition.
+   */
+  constructor(type) {
+    this.#type = type
+  }
+}
+
+/**
+ * Represents a partition descriptor for a browsing context.
+ * @extends PartitionDescriptor
+ */
+class BrowsingContextPartitionDescriptor extends PartitionDescriptor {
+  #context = null
+
+  constructor(context) {
+    super(Type.CONTEXT)
+    this.#context = context
+  }
+
+  asMap() {
+    const map = new Map()
+    map.set('type', Type.CONTEXT)
+    map.set('context', this.#context)
+    return map
+  }
+}
+
+/**
+ * Represents a partition descriptor for storage key.
+ * @extends PartitionDescriptor
+ */
+class StorageKeyPartitionDescriptor extends PartitionDescriptor {
+  #map = new Map()
+
+  constructor() {
+    super(Type.STORAGE_KEY)
+  }
+
+  /**
+   * Sets the user context for the partition descriptor.
+   * @param {any} userContext - The user context to set.
+   * @returns {PartitionDescriptor} - The updated partition descriptor instance for chaining.
+   */
+  userContext(userContext) {
+    this.#map.set('userContext', userContext)
+    return this
+  }
+
+  /**
+   * Sets the source origin for the partition descriptor.
+   *
+   * @param {string} sourceOrigin - The source origin to set.
+   * @returns {PartitionDescriptor} - The updated PartitionDescriptor instance for chaining.
+   */
+  sourceOrigin(sourceOrigin) {
+    this.#map.set('sourceOrigin', sourceOrigin)
+    return this
+  }
+
+  asMap() {
+    return this.#map
+  }
+}
+
+module.exports = { BrowsingContextPartitionDescriptor, StorageKeyPartitionDescriptor }

package/bidi/partitionKey.js

@@ -0,0 +1,53 @@
+// 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 partition key of cookie storage.
+ * Described in https://w3c.github.io/webdriver-bidi/#type-storage-PartitionKey.
+ */
+class PartitionKey {
+  #userContext
+  #sourceOrigin
+
+  /**
+   * Constructs a new PartitionKey object.
+   * @param {string} userContext - The user context.
+   * @param {string} sourceOrigin - The source origin.
+   */
+  constructor(userContext, sourceOrigin) {
+    this.#userContext = userContext
+    this.#sourceOrigin = sourceOrigin
+  }
+
+  /**
+   * Gets the user context.
+   * @returns {string} The user context.
+   */
+  get userContext() {
+    return this.#userContext
+  }
+
+  /**
+   * Gets the source origin.
+   * @returns {string} The source origin.
+   */
+  get sourceOrigin() {
+    return this.#sourceOrigin
+  }
+}
+
+module.exports = { PartitionKey }

package/bidi/protocolType.js

@@ -15,6 +15,11 @@
 // specific language governing permissions and limitations
 // under the License.
 
+/**
+ * Represents a primitive type.
+ * @enum
+ * Described in https://w3c.github.io/webdriver-bidi/#type-script-PrimitiveProtocolValue.
+ */
 const PrimitiveType = {
   UNDEFINED: 'undefined',
   NULL: 'null',
@@ -33,6 +38,11 @@ const PrimitiveType = {
   },
 }
 
+/**
+ * Represents a non-primitive type.
+ * @enum
+ * Described inhttps://w3c.github.io/webdriver-bidi/#type-script-RemoteValue.
+ */
 const NonPrimitiveType = {
   ARRAY: 'array',
   DATE: 'date',
@@ -51,6 +61,11 @@ const NonPrimitiveType = {
   },
 }
 
+/**
+ * Represents a remote value type.
+ * @enum
+ * Described inhttps://w3c.github.io/webdriver-bidi/#type-script-RemoteValue.
+ */
 const RemoteType = {
   SYMBOL: 'symbol',
   FUNCTION: 'function',
@@ -77,6 +92,11 @@ const RemoteType = {
   },
 }
 
+/**
+ * Represents a speacial number type.
+ * @enum
+ * Described in https://w3c.github.io/webdriver-bidi/#type-script-PrimitiveProtocolValue.
+ */
 const SpecialNumberType = {
   NAN: 'NaN',
   MINUS_ZERO: '-0',

package/bidi/protocolValue.js

@@ -19,11 +19,20 @@ const { PrimitiveType, NonPrimitiveType, RemoteType } = require('./protocolType'
 
 const TYPE_CONSTANT = 'type'
 const VALUE_CONSTANT = 'value'
+/**
+ * Represents the types of remote reference.
+ * @enum {string}
+ */
 const RemoteReferenceType = {
   HANDLE: 'handle',
   SHARED_ID: 'sharedId',
 }
 
+/**
+ * Represents a local value with a specified type and optional value.
+ * @class
+ * Described in https://w3c.github.io/webdriver-bidi/#type-script-LocalValue
+ */
 class LocalValue {
   constructor(type, value = null) {
     if (type === PrimitiveType.UNDEFINED || type === PrimitiveType.NULL) {
@@ -34,42 +43,97 @@ class LocalValue {
     }
   }
 
+  /**
+   * Creates a new LocalValue object with a string value.
+   *
+   * @param {string} value - The string value to be stored in the LocalValue object.
+   * @returns {LocalValue} - The created LocalValue object.
+   */
   static createStringValue(value) {
     return new LocalValue(PrimitiveType.STRING, value)
   }
 
+  /**
+   * Creates a new LocalValue object with a number value.
+   *
+   * @param {number} value - The number value.
+   * @returns {LocalValue} - The created LocalValue object.
+   */
   static createNumberValue(value) {
     return new LocalValue(PrimitiveType.NUMBER, value)
   }
 
+  /**
+   * Creates a new LocalValue object with a special number value.
+   *
+   * @param {number} value - The value of the special number.
+   * @returns {LocalValue} - The created LocalValue object.
+   */
   static createSpecialNumberValue(value) {
     return new LocalValue(PrimitiveType.SPECIAL_NUMBER, value)
   }
 
+  /**
+   * Creates a new LocalValue object with an undefined value.
+   * @returns {LocalValue} - The created LocalValue object.
+   */
   static createUndefinedValue() {
     return new LocalValue(PrimitiveType.UNDEFINED)
   }
 
+  /**
+   * Creates a new LocalValue object with a null value.
+   * @returns {LocalValue} - The created LocalValue object.
+   */
   static createNullValue() {
     return new LocalValue(PrimitiveType.NULL)
   }
 
+  /**
+   * Creates a new LocalValue object with a boolean value.
+   *
+   * @param {boolean} value - The boolean value.
+   * @returns {LocalValue} - The created LocalValue object.
+   */
   static createBooleanValue(value) {
     return new LocalValue(PrimitiveType.BOOLEAN, value)
   }
 
+  /**
+   * Creates a new LocalValue object with a BigInt value.
+   *
+   * @param {BigInt} value - The BigInt value.
+   * @returns {LocalValue} - The created LocalValue object.
+   */
   static createBigIntValue(value) {
     return new LocalValue(PrimitiveType.BIGINT, value)
   }
 
+  /**
+   * Creates a new LocalValue object with an array.
+   *
+   * @param {Array} value - The array.
+   * @returns {LocalValue} - The created LocalValue object.
+   */
   static createArrayValue(value) {
     return new LocalValue(NonPrimitiveType.ARRAY, value)
   }
 
+  /**
+   * Creates a new LocalValue object with date value.
+   *
+   * @param {string} value - The date.
+   * @returns {LocalValue} - The created LocalValue object.
+   */
   static createDateValue(value) {
     return new LocalValue(NonPrimitiveType.DATE, value)
   }
 
+  /**
+   * Creates a new LocalValue object of map value.
+   * @param {Map} map - The map.
+   * @returns {LocalValue} - The created LocalValue object.
+   */
   static createMapValue(map) {
     let value = []
     Object.entries(map).forEach((entry) => {
@@ -78,22 +142,45 @@ class LocalValue {
     return new LocalValue(NonPrimitiveType.MAP, value)
   }
 
-  static createObjectValue(map) {
+  /**
+   * Creates a new LocalValue object from the passed object.
+   *
+   * @param {Object} map - The object.
+   * @returns {LocalValue} - The created LocalValue object.
+   */
+  static createObjectValue(object) {
     let value = []
-    Object.entries(map).forEach((entry) => {
+    Object.entries(object).forEach((entry) => {
       value.push(entry)
     })
     return new LocalValue(NonPrimitiveType.OBJECT, value)
   }
 
+  /**
+   * Creates a new LocalValue object of regular expression value.
+   *
+   * @param {string} value - The value of the regular expression.
+   * @returns {LocalValue} - The created LocalValue object.
+   */
   static createRegularExpressionValue(value) {
     return new LocalValue(NonPrimitiveType.REGULAR_EXPRESSION, value)
   }
 
+  /**
+   * Creates a new LocalValue object with the specified value.
+   * @param {Set} value - The value to be set.
+   * @returns {LocalValue} - The created LocalValue object.
+   */
   static createSetValue(value) {
     return new LocalValue(NonPrimitiveType.SET, value)
   }
 
+  /**
+   * Creates a new LocalValue object with the given channel value
+   *
+   * @param {ChannelValue} value - The channel value.
+   * @returns {LocalValue} - The created LocalValue object.
+   */
   static createChannelValue(value) {
     return new LocalValue(NonPrimitiveType.CHANNEL, value)
   }
@@ -109,6 +196,11 @@ class LocalValue {
   }
 }
 
+/**
+ * Represents a remote value.
+ * Described in https://w3c.github.io/webdriver-bidi/#type-script-RemoteValue.
+ * @class
+ */
 class RemoteValue {
   constructor(remoteValue) {
     this.type = null
@@ -159,38 +251,72 @@ class RemoteValue {
   }
 }
 
+/**
+ * Represents a reference value in the protocol.
+ * Described in https://w3c.github.io/webdriver-bidi/#type-script-RemoteReference.
+ */
 class ReferenceValue {
+  #handle
+  #sharedId
+
+  /**
+   * Constructs a new ReferenceValue object.
+   * @param {string} handle - The handle value.
+   * @param {string} sharedId - The shared ID value.
+   */
   constructor(handle, sharedId) {
     if (handle === RemoteReferenceType.HANDLE) {
-      this.handle = sharedId
+      this.#handle = sharedId
+    } else if (handle === RemoteReferenceType.SHARED_ID) {
+      this.#sharedId = sharedId
     } else {
-      this.handle = handle
-      this.sharedId = sharedId
+      this.#handle = handle
+      this.#sharedId = sharedId
     }
   }
 
   asMap() {
     const toReturn = {}
-    if (this.handle != null) {
-      toReturn[RemoteReferenceType.HANDLE] = this.handle
+    if (this.#handle != null) {
+      toReturn[RemoteReferenceType.HANDLE] = this.#handle
     }
 
-    if (this.sharedId != null) {
-      toReturn[RemoteReferenceType.SHARED_ID] = this.sharedId
+    if (this.#sharedId != null) {
+      toReturn[RemoteReferenceType.SHARED_ID] = this.#sharedId
     }
 
     return toReturn
   }
 }
 
+/**
+ * Represents a regular expression value.
+ * Described in https://w3c.github.io/webdriver-bidi/#type-script-LocalValue.
+ */
 class RegExpValue {
+  /**
+   * Constructs a new RegExpValue object.
+   * @param {string} pattern - The pattern of the regular expression.
+   * @param {string|null} [flags=null] - The flags of the regular expression.
+   */
   constructor(pattern, flags = null) {
     this.pattern = pattern
     this.flags = flags
   }
 }
 
+/**
+ * Represents serialization options.
+ * Described in https://w3c.github.io/webdriver-bidi/#type-script-SerializationOptions.
+ */
 class SerializationOptions {
+  /**
+   * Constructs a new instance of SerializationOptions.
+   * @param {number} [maxDomDepth=0] - The maximum depth to serialize the DOM.
+   * @param {number|null} [maxObjectDepth=null] - The maximum depth to serialize objects.
+   * @param {'none'|'open'|'all'} [includeShadowTree='none'] - The inclusion level of the shadow tree.
+   * @throws {Error} If the `includeShadowTree` value is not one of 'none', 'open', or 'all'.
+   */
   constructor(maxDomDepth = 0, maxObjectDepth = null, includeShadowTree = 'none') {
     this._maxDomDepth = maxDomDepth
     this._maxObjectDepth = maxObjectDepth
@@ -202,6 +328,11 @@ class SerializationOptions {
   }
 }
 
+/**
+ * Represents a channel value.
+ * Described in https://w3c.github.io/webdriver-bidi/#type-script-ChannelValue.
+ * @class
+ */
 class ChannelValue {
   constructor(channel, options = undefined, resultOwnership = undefined) {
     this.channel = channel