selenium-webdriver 4.48.0 → 4.50.0

package/bidi/generated/webextension.d.ts

@@ -1,11 +1,14 @@
-import type { EmptyResult, Extensible } from './common.js';
-export type WebExtensionCommand = WebExtensionInstall | WebExtensionUninstall;
-export type WebExtensionResult = WebExtensionInstallResult | WebExtensionUninstallResult;
+import type { EmptyResult } from './common.js';
+import './common.js';
+import { Domain } from '../domain.js';
 export type WebExtensionExtension = string;
 export interface WebExtensionInstall {
     method: "webExtension.install";
     params: WebExtensionInstallParameters;
 }
+export interface WebExtensionInstallParameters {
+    extensionData: WebExtensionExtensionData;
+}
 export type WebExtensionExtensionData = WebExtensionExtensionArchivePath | WebExtensionExtensionBase64Encoded | WebExtensionExtensionPath;
 export interface WebExtensionExtensionPath {
     type: "path";
@@ -30,14 +33,25 @@ export interface WebExtensionUninstallParameters {
     extension: WebExtensionExtension;
 }
 export type WebExtensionUninstallResult = EmptyResult;
-export type WebExtensionInstallParameters = WebExtensionInstallParametersExtension & {
-    extensionData: WebExtensionExtensionData;
-};
-export type WebExtensionInstallParametersExtension = Extensible;
-export declare class WebExtension {
-    private readonly bidi;
-    private constructor();
+/**
+ * This is an unsupported API. No compatibility guarantees are provided.
+ * It tracks the W3C WebDriver BiDi specification directly. As the specification
+ * evolves, this API will change or be removed without prior notice.
+ */
+export declare class WebExtension extends Domain {
     static create(driver: unknown): Promise<WebExtension>;
+    /**
+     * @param {WebExtensionInstallParameters} params
+     * @param {WebExtensionExtensionData} params.extensionData
+     * @returns {Promise<WebExtensionInstallResult>}
+     * @see https://w3c.github.io/webdriver-bidi/#command-webExtension-install
+     */
     install(params: WebExtensionInstallParameters): Promise<WebExtensionInstallResult>;
+    /**
+     * @param {WebExtensionUninstallParameters} params
+     * @param {WebExtensionExtension} params.extension
+     * @returns {Promise<void>}
+     * @see https://w3c.github.io/webdriver-bidi/#command-webExtension-uninstall
+     */
     uninstall(params: WebExtensionUninstallParameters): Promise<void>;
 }

package/bidi/generated/webextension.js

@@ -17,37 +17,51 @@
 // under the License.
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.WebExtension = void 0;
+require("./common.js");
+const record_js_1 = require("../serialization/record.js");
+const union_js_1 = require("../serialization/union.js");
+const domain_js_1 = require("../domain.js");
+(0, record_js_1.defineAlias)('webExtension.Extension', { "primitive": "string" });
+const WebExtensionInstall = (0, record_js_1.defineRecord)('webExtension.Install', [{ "name": "method", "wire": "method", "required": true, "type": { "const": "webExtension.install" } }, { "name": "params", "wire": "params", "required": true, "type": { "ref": "webExtension.InstallParameters" } }]);
+const WebExtensionInstallParameters = (0, record_js_1.defineRecord)('webExtension.InstallParameters', [{ "name": "extensionData", "wire": "extensionData", "required": true, "type": { "ref": "webExtension.ExtensionData" } }]);
+const WebExtensionExtensionDataUnion = (0, union_js_1.defineUnion)('webExtension.ExtensionData', { "by": "type", "variants": [{ "value": "archivePath", "ref": "webExtension.ExtensionArchivePath" }, { "value": "base64", "ref": "webExtension.ExtensionBase64Encoded" }, { "value": "path", "ref": "webExtension.ExtensionPath" }] }, { "objectOnly": true });
+const WebExtensionExtensionPath = (0, record_js_1.defineRecord)('webExtension.ExtensionPath', [{ "name": "type", "wire": "type", "required": true, "type": { "const": "path" } }, { "name": "path", "wire": "path", "required": true, "type": { "primitive": "string" } }]);
+const WebExtensionExtensionArchivePath = (0, record_js_1.defineRecord)('webExtension.ExtensionArchivePath', [{ "name": "type", "wire": "type", "required": true, "type": { "const": "archivePath" } }, { "name": "path", "wire": "path", "required": true, "type": { "primitive": "string" } }]);
+const WebExtensionExtensionBase64Encoded = (0, record_js_1.defineRecord)('webExtension.ExtensionBase64Encoded', [{ "name": "type", "wire": "type", "required": true, "type": { "const": "base64" } }, { "name": "value", "wire": "value", "required": true, "type": { "primitive": "string" } }]);
+const WebExtensionInstallResult = (0, record_js_1.defineRecord)('webExtension.InstallResult', [{ "name": "extension", "wire": "extension", "required": true, "type": { "ref": "webExtension.Extension" } }]);
+const WebExtensionUninstall = (0, record_js_1.defineRecord)('webExtension.Uninstall', [{ "name": "method", "wire": "method", "required": true, "type": { "const": "webExtension.uninstall" } }, { "name": "params", "wire": "params", "required": true, "type": { "ref": "webExtension.UninstallParameters" } }]);
+const WebExtensionUninstallParameters = (0, record_js_1.defineRecord)('webExtension.UninstallParameters', [{ "name": "extension", "wire": "extension", "required": true, "type": { "ref": "webExtension.Extension" } }]);
+(0, record_js_1.defineAlias)('webExtension.UninstallResult', { "ref": "EmptyResult" });
 // --- Implementation ---
-class WebExtension {
-    constructor(bidi) {
-        this.bidi = bidi;
-    }
+/**
+ * This is an unsupported API. No compatibility guarantees are provided.
+ * It tracks the W3C WebDriver BiDi specification directly. As the specification
+ * evolves, this API will change or be removed without prior notice.
+ */
+class WebExtension extends domain_js_1.Domain {
     static async create(driver) {
-        const caps = await driver.getCapabilities();
-        if (!caps.get('webSocketUrl')) {
-            throw new Error('WebDriver instance must support BiDi protocol');
-        }
-        const bidi = await driver.getBidi();
-        return new WebExtension(bidi);
+        return new WebExtension(await domain_js_1.Domain.connect(driver), domain_js_1.DOMAIN_TOKEN);
     }
+    /**
+     * @param {WebExtensionInstallParameters} params
+     * @param {WebExtensionExtensionData} params.extensionData
+     * @returns {Promise<WebExtensionInstallResult>}
+     * @see https://w3c.github.io/webdriver-bidi/#command-webExtension-install
+     */
     async install(params) {
-        const response = await this.bidi.send({
-            method: 'webExtension.install',
-            params: params,
-        });
-        if (response['type'] === 'error') {
-            throw new Error(`${response['error']}: ${response['message']}`);
-        }
-        return response.result;
+        const validatedParams = new WebExtensionInstallParameters(params);
+        const result = await this.send('webExtension.install', validatedParams);
+        return WebExtensionInstallResult.fromWire(result);
     }
+    /**
+     * @param {WebExtensionUninstallParameters} params
+     * @param {WebExtensionExtension} params.extension
+     * @returns {Promise<void>}
+     * @see https://w3c.github.io/webdriver-bidi/#command-webExtension-uninstall
+     */
     async uninstall(params) {
-        const response = await this.bidi.send({
-            method: 'webExtension.uninstall',
-            params: params,
-        });
-        if (response['type'] === 'error') {
-            throw new Error(`${response['error']}: ${response['message']}`);
-        }
+        const validatedParams = new WebExtensionUninstallParameters(params);
+        await this.send('webExtension.uninstall', validatedParams);
     }
 }
 exports.WebExtension = WebExtension;

package/bidi/serialization/enum.js

@@ -18,10 +18,13 @@
 const { register } = require('./registry')
 
 /**
- * Registers a schema `enum` — a closed set of string values a field may hold.
+ * Registers a schema `enum` — a closed set of string, number, or boolean values a
+ * field may hold (e.g. emulation.MediaFeaturesGrid, CSS's `grid` media feature, is
+ * spec'd as the integer 0 or 1, not a string; the schema projector's literalPrimitive()
+ * recognizes a boolean-literal choice the same way).
  * @param {string} name Schema type name, e.g. 'network.InterceptPhase'.
- * @param {string[]} values The enum's valid values.
- * @returns {{kind: 'enum', values: string[], includes: function(unknown): boolean}}
+ * @param {Array<string|number|boolean>} values The enum's valid values.
+ * @returns {{kind: 'enum', values: Array<string|number|boolean>, includes: function(unknown): boolean}}
  *   The registered entry, used by validateValue() to check a ref'd value's
  *   membership; also returned so a generator can build a discoverable constant from it.
  */

package/bidi/serialization/record.js

@@ -20,14 +20,14 @@ const { register, resolve } = require('./registry')
 class ValidationError extends Error {}
 
 // Validates a *present* value against a resolved type node, and returns the value to
-// assign for it — usually the same value, but for a nested ref-to-record/union parsed
-// inbound (fromWire()/build() results, not the raw wire object) and for list/map/inline
-// record values (a fresh, deeply-frozen copy, so validity can't be corrupted after the
-// fact by mutating an array or object a caller still holds a reference to).
-// Outbound nested refs deliberately keep the caller's own value instead of the
-// newly-constructed instance — the nested `new referenced.RecordClass(value)` /
-// `referenced.build(value)` call below exists only to validate, matching the
-// constructor's existing outbound behavior of trusting the caller's own object shape.
+// assign for it — usually the same value, but for a nested ref-to-record/union (the
+// freshly constructed/parsed instance — fromWire()/build() inbound, `new RecordClass(value)`/
+// build() outbound, not the caller's raw value) and for list/map/inline record values (a
+// fresh, deeply-frozen copy, so validity can't be corrupted after the fact by mutating an
+// array or object a caller still holds a reference to). Outbound needs the constructed
+// instance, symmetric with inbound, so a typed parent's toJSON() cascades into a nested
+// record's own toJSON() — converting *its* fields to their declared wire names too, not
+// just the parent's own fields — when the whole instance is serialized for the wire.
 // `direction` only affects how a nested ref-to-record/union is itself validated/parsed.
 function validateValue(typeNode, value, path, direction) {
   if (value === null) {
@@ -125,23 +125,24 @@ function validateValue(typeNode, value, path, direction) {
         throw new ValidationError(`${path}: expected an object, got ${typeof value}`)
       }
       // Recurse through the same-direction path so a nested field gets the same
-      // tolerance (inbound) or strictness (outbound) as its parent. Inbound returns
-      // the parsed instance itself, so a typed parent record ends up with a typed
-      // nested value instead of the raw wire object; outbound only validates this
-      // way (the caller's own value is what gets kept, see the note above).
+      // tolerance (inbound) or strictness (outbound) as its parent, and — both
+      // directions alike — ends up holding the typed instance, not the raw value:
+      // inbound so a typed parent record has a typed nested value instead of the
+      // raw wire object; outbound so the parent's own toJSON() cascades into this
+      // nested instance's toJSON() too, converting its fields to their wire names.
       if (direction === 'inbound') {
         return referenced.RecordClass.fromWire(value)
       }
-      new referenced.RecordClass(value)
-      return value
+      return new referenced.RecordClass(value)
     }
 
     if (referenced.kind === 'union') {
+      // build()/fromWire() already return the resolved variant's own instance —
+      // same reasoning as the record branch above applies to it symmetrically.
       if (direction === 'inbound') {
         return referenced.fromWire(value)
       }
-      referenced.build(value)
-      return value
+      return referenced.build(value)
     }
 
     if (referenced.kind === 'alias') {
@@ -220,33 +221,37 @@ function defineRecord(name, fields, options = {}) {
 
   class Record {
     // Outbound: strict. Any value that doesn't match its declared shape is an error here.
+    // Reads `data` by JS-facing field name (field.name), not the wire key (field.wire) —
+    // a caller builds params using the same property names the generated TS interface
+    // declares (e.g. `prefersColorScheme`), never the raw spec key (`prefers-color-scheme`);
+    // toJSON() below is what maps back to field.wire for the actual wire send.
     constructor(data) {
       if (typeof data !== 'object' || data === null || Array.isArray(data)) {
         throw new ValidationError(`${name}: expected an object`)
       }
 
       for (const field of fields) {
-        if (!Object.hasOwn(data, field.wire)) {
+        if (!Object.hasOwn(data, field.name)) {
           if (field.required) {
-            throw new ValidationError(`${name}.${field.wire}: required field is missing`)
+            throw new ValidationError(`${name}.${field.name}: required field is missing`)
           }
           continue
         }
-        const value = data[field.wire]
-        this[field.name] = validateValue(field.type, value, `${name}.${field.wire}`, 'outbound')
+        const value = data[field.name]
+        this[field.name] = validateValue(field.type, value, `${name}.${field.name}`, 'outbound')
       }
 
-      for (const wireKey of Object.keys(data)) {
-        if (byWire.has(wireKey)) continue
+      for (const key of Object.keys(data)) {
+        if (byName.has(key)) continue
         if (!extensible) {
-          throw new ValidationError(`${name}: unknown property "${wireKey}"`)
+          throw new ValidationError(`${name}: unknown property "${key}"`)
         }
-        // Object.defineProperty, not `this[wireKey] = ...`: wireKey is caller-supplied
-        // and a literal "__proto__" key assigned via bracket notation hijacks this
-        // instance's actual prototype instead of becoming a field (CWE-1321).
-        // defineProperty always creates a genuine own data property, regardless of name.
-        Object.defineProperty(this, wireKey, {
-          value: data[wireKey], // vendor extras reach the wire on an extensible type
+        // Object.defineProperty, not `this[key] = ...`: key is caller-supplied and a
+        // literal "__proto__" key assigned via bracket notation hijacks this instance's
+        // actual prototype instead of becoming a field (CWE-1321). defineProperty always
+        // creates a genuine own data property, regardless of name.
+        Object.defineProperty(this, key, {
+          value: data[key], // vendor extras have no separate wire name — this key is both
           enumerable: true,
           writable: true,
           configurable: true,