selenium-webdriver 4.44.0 → 4.45.0

package/bidi/generated/session.js

@@ -0,0 +1,82 @@
+"use strict";
+// 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.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Session = void 0;
+// --- Implementation ---
+class Session {
+    constructor(bidi) {
+        this.bidi = bidi;
+    }
+    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 Session(bidi);
+    }
+    async end() {
+        const response = await this.bidi.send({
+            method: 'session.end',
+            params: {},
+        });
+        if (response['type'] === 'error') {
+            throw new Error(`${response['error']}: ${response['message']}`);
+        }
+    }
+    async new(params) {
+        const response = await this.bidi.send({
+            method: 'session.new',
+            params: params,
+        });
+        if (response['type'] === 'error') {
+            throw new Error(`${response['error']}: ${response['message']}`);
+        }
+        return response.result;
+    }
+    async status() {
+        const response = await this.bidi.send({
+            method: 'session.status',
+            params: {},
+        });
+        if (response['type'] === 'error') {
+            throw new Error(`${response['error']}: ${response['message']}`);
+        }
+        return response.result;
+    }
+    async subscribe(params) {
+        const response = await this.bidi.send({
+            method: 'session.subscribe',
+            params: params,
+        });
+        if (response['type'] === 'error') {
+            throw new Error(`${response['error']}: ${response['message']}`);
+        }
+        return response.result;
+    }
+    async unsubscribe(params) {
+        const response = await this.bidi.send({
+            method: 'session.unsubscribe',
+            params: params,
+        });
+        if (response['type'] === 'error') {
+            throw new Error(`${response['error']}: ${response['message']}`);
+        }
+    }
+}
+exports.Session = Session;

package/bidi/generated/speculation.d.ts

@@ -0,0 +1,17 @@
+export type SpeculationPreloadingStatus = "pending" | "ready" | "success" | "failure";
+export type SpeculationEvent = SpeculationPrefetchStatusUpdated;
+export interface SpeculationPrefetchStatusUpdated {
+    method: "speculation.prefetchStatusUpdated";
+    params: SpeculationPrefetchStatusUpdatedParameters;
+}
+export interface SpeculationPrefetchStatusUpdatedParameters {
+    context: string;
+    url: string;
+    status: SpeculationPreloadingStatus;
+}
+export declare class Speculation {
+    private readonly bidi;
+    private constructor();
+    static create(driver: unknown): Promise<Speculation>;
+    onPrefetchStatusUpdated(callback: (params: SpeculationPrefetchStatusUpdatedParameters) => void): Promise<void>;
+}

package/bidi/generated/speculation.js

@@ -0,0 +1,40 @@
+"use strict";
+// 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.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Speculation = void 0;
+// --- Implementation ---
+class Speculation {
+    constructor(bidi) {
+        this.bidi = bidi;
+    }
+    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 Speculation(bidi);
+    }
+    async onPrefetchStatusUpdated(callback) {
+        await this.bidi.subscribe('speculation.prefetchStatusUpdated');
+        this.bidi.on('speculation.prefetchStatusUpdated', (params) => {
+            callback(params);
+        });
+    }
+}
+exports.Speculation = Speculation;

package/bidi/generated/storage.d.ts

@@ -0,0 +1,84 @@
+import type { BrowsingContextBrowsingContext } from './browsing_context.js';
+import type { Extensible, JsUint } from './common.js';
+import type { NetworkBytesValue, NetworkCookie, NetworkSameSite } from './network.js';
+export type StorageCommand = StorageDeleteCookies | StorageGetCookies | StorageSetCookie;
+export type StorageResult = StorageDeleteCookiesResult | StorageGetCookiesResult | StorageSetCookieResult;
+export type StoragePartitionKey = Extensible & {
+    userContext?: string;
+    sourceOrigin?: string;
+};
+export interface StorageGetCookies {
+    method: "storage.getCookies";
+    params: StorageGetCookiesParameters;
+}
+export type StorageCookieFilter = Extensible & {
+    name?: string;
+    value?: NetworkBytesValue;
+    domain?: string;
+    path?: string;
+    size?: JsUint;
+    httpOnly?: boolean;
+    secure?: boolean;
+    sameSite?: NetworkSameSite;
+    expiry?: JsUint;
+};
+export interface StorageBrowsingContextPartitionDescriptor {
+    type: "context";
+    context: BrowsingContextBrowsingContext;
+}
+export type StorageStorageKeyPartitionDescriptor = Extensible & {
+    type: "storageKey";
+    userContext?: string;
+    sourceOrigin?: string;
+};
+export type StoragePartitionDescriptor = StorageBrowsingContextPartitionDescriptor | StorageStorageKeyPartitionDescriptor;
+export interface StorageGetCookiesParameters {
+    filter?: StorageCookieFilter;
+    partition?: StoragePartitionDescriptor;
+}
+export interface StorageGetCookiesResult {
+    cookies: NetworkCookie[];
+    partitionKey: StoragePartitionKey;
+}
+export interface StorageSetCookie {
+    method: "storage.setCookie";
+    params: StorageSetCookieParameters;
+}
+export type StoragePartialCookie = Extensible & {
+    name: string;
+    value: NetworkBytesValue;
+    domain: string;
+    path?: string;
+    httpOnly?: boolean;
+    secure?: boolean;
+    sameSite?: NetworkSameSite;
+    expiry?: JsUint;
+};
+export interface StorageSetCookieParameters {
+    cookie: StoragePartialCookie;
+    partition?: StoragePartitionDescriptor;
+}
+export interface StorageSetCookieResult {
+    partitionKey: StoragePartitionKey;
+}
+export interface StorageDeleteCookies {
+    method: "storage.deleteCookies";
+    params: StorageDeleteCookiesParameters;
+}
+export interface StorageDeleteCookiesParameters {
+    filter?: StorageCookieFilter;
+    partition?: StoragePartitionDescriptor;
+}
+export interface StorageDeleteCookiesResult {
+    partitionKey: StoragePartitionKey;
+}
+/** @deprecated Use {@link Storage.create} instead — will be removed in a future major version. */
+export declare function getStorageInstance(driver: unknown): Promise<Storage>;
+export declare class Storage {
+    private readonly bidi;
+    private constructor();
+    static create(driver: unknown): Promise<Storage>;
+    deleteCookies(params: StorageDeleteCookiesParameters): Promise<StorageDeleteCookiesResult>;
+    getCookies(params: StorageGetCookiesParameters): Promise<StorageGetCookiesResult>;
+    setCookie(params: StorageSetCookieParameters): Promise<StorageSetCookieResult>;
+}

package/bidi/generated/storage.js

@@ -0,0 +1,70 @@
+"use strict";
+// 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.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Storage = exports.getStorageInstance = void 0;
+// --- Additional Types ---
+/** @deprecated Use {@link Storage.create} instead — will be removed in a future major version. */
+async function getStorageInstance(driver) {
+    return Storage.create(driver);
+}
+exports.getStorageInstance = getStorageInstance;
+// --- Implementation ---
+class Storage {
+    constructor(bidi) {
+        this.bidi = bidi;
+    }
+    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 Storage(bidi);
+    }
+    async deleteCookies(params) {
+        const response = await this.bidi.send({
+            method: 'storage.deleteCookies',
+            params: params,
+        });
+        if (response['type'] === 'error') {
+            throw new Error(`${response['error']}: ${response['message']}`);
+        }
+        return response.result;
+    }
+    async getCookies(params) {
+        const response = await this.bidi.send({
+            method: 'storage.getCookies',
+            params: params,
+        });
+        if (response['type'] === 'error') {
+            throw new Error(`${response['error']}: ${response['message']}`);
+        }
+        return response.result;
+    }
+    async setCookie(params) {
+        const response = await this.bidi.send({
+            method: 'storage.setCookie',
+            params: params,
+        });
+        if (response['type'] === 'error') {
+            throw new Error(`${response['error']}: ${response['message']}`);
+        }
+        return response.result;
+    }
+}
+exports.Storage = Storage;

package/bidi/generated/user_agent_client_hints.d.ts

@@ -0,0 +1,33 @@
+export type UserAgentClientHintsCommand = UserAgentClientHintsSetClientHintsOverrideCommand;
+export interface UserAgentClientHintsSetClientHintsOverrideCommand {
+    method: "userAgentClientHints.setClientHintsOverride";
+    params: {
+        clientHints: UserAgentClientHintsClientHintsMetadata | null;
+        contexts?: string[];
+        userContexts?: string[];
+    };
+}
+export interface UserAgentClientHintsClientHintsMetadata {
+    brands?: UserAgentClientHintsBrandVersion[];
+    fullVersionList?: UserAgentClientHintsBrandVersion[];
+    platform?: string;
+    platformVersion?: string;
+    architecture?: string;
+    model?: string;
+    mobile?: boolean;
+    bitness?: string;
+    wow64?: boolean;
+    formFactors?: string[];
+}
+export interface UserAgentClientHintsBrandVersion {
+    brand: string;
+    version: string;
+}
+export interface UserAgentClientHintsSetClientHintsOverrideResult {
+}
+export declare class UserAgentClientHints {
+    private readonly bidi;
+    private constructor();
+    static create(driver: unknown): Promise<UserAgentClientHints>;
+    setClientHintsOverride(): Promise<void>;
+}

package/bidi/generated/user_agent_client_hints.js

@@ -0,0 +1,43 @@
+"use strict";
+// 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.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.UserAgentClientHints = void 0;
+// --- Implementation ---
+class UserAgentClientHints {
+    constructor(bidi) {
+        this.bidi = bidi;
+    }
+    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 UserAgentClientHints(bidi);
+    }
+    async setClientHintsOverride() {
+        const response = await this.bidi.send({
+            method: 'userAgentClientHints.setClientHintsOverride',
+            params: {},
+        });
+        if (response['type'] === 'error') {
+            throw new Error(`${response['error']}: ${response['message']}`);
+        }
+    }
+}
+exports.UserAgentClientHints = UserAgentClientHints;

package/bidi/generated/webextension.d.ts

@@ -0,0 +1,42 @@
+import type { EmptyResult } from './common.js';
+export type WebExtensionCommand = WebExtensionInstall | WebExtensionUninstall;
+export type WebExtensionResult = WebExtensionInstallResult | WebExtensionUninstallResult;
+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";
+    path: string;
+}
+export interface WebExtensionExtensionArchivePath {
+    type: "archivePath";
+    path: string;
+}
+export interface WebExtensionExtensionBase64Encoded {
+    type: "base64";
+    value: string;
+}
+export interface WebExtensionInstallResult {
+    extension: WebExtensionExtension;
+}
+export interface WebExtensionUninstall {
+    method: "webExtension.uninstall";
+    params: WebExtensionUninstallParameters;
+}
+export interface WebExtensionUninstallParameters {
+    extension: WebExtensionExtension;
+}
+export type WebExtensionUninstallResult = EmptyResult;
+export declare class WebExtension {
+    private readonly bidi;
+    private constructor();
+    static create(driver: unknown): Promise<WebExtension>;
+    install(params: WebExtensionInstallParameters): Promise<WebExtensionInstallResult>;
+    uninstall(params: WebExtensionUninstallParameters): Promise<void>;
+}

package/bidi/generated/webextension.js

@@ -0,0 +1,53 @@
+"use strict";
+// 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.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.WebExtension = void 0;
+// --- Implementation ---
+class WebExtension {
+    constructor(bidi) {
+        this.bidi = bidi;
+    }
+    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);
+    }
+    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;
+    }
+    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']}`);
+        }
+    }
+}
+exports.WebExtension = WebExtension;

package/bidi/index.js

@@ -79,10 +79,31 @@ class Index extends EventEmitter {
         }
         return
       }
-      // Messages without a numeric id are BiDi events, not command
-      // responses; they are routed via subscribe/EventEmitter elsewhere
-      // and intentionally ignored by this dispatcher.
+      // Messages without a numeric id are BiDi events, not command responses.
+      // Re-emit them on this EventEmitter by method name (e.g.
+      // 'browsingContext.contextCreated') so that generated domain classes can
+      // subscribe via bidi.on(methodName, callback) instead of each attaching
+      // a new raw ws.on('message', ...) listener.  The existing hand-written
+      // modules (logInspector, network, etc.) continue to use their own
+      // ws.on('message', ...) listeners unchanged — this emission is purely
+      // additive and does not affect those code paths.
       if (payload == null || typeof payload.id !== 'number') {
+        if (payload != null && typeof payload.method === 'string') {
+          // 'error' is a reserved EventEmitter event — emitting it without a
+          // listener throws and crashes the process. Route any peer-supplied
+          // method named 'error' through the same guarded path used for JSON
+          // parse failures rather than forwarding it directly.
+          if (payload.method === 'error') {
+            const err = new Error(`BiDi protocol error event: ${JSON.stringify(payload.params)}`)
+            if (this.listenerCount('error') > 0) {
+              this.emit('error', err)
+            } else {
+              process.emitWarning(err.message, 'BiDiProtocolWarning')
+            }
+          } else {
+            this.emit(payload.method, payload.params)
+          }
+        }
         return
       }
       const entry = this._pending.get(payload.id)

package/common/driverFinder.js

@@ -35,10 +35,11 @@ function getBinaryPaths(capabilities) {
     const args = getArgs(capabilities)
     return binaryPaths(args)
   } catch (e) {
-    throw Error(
+    throw new Error(
       `Unable to obtain browser driver.
         For more information on how to install drivers see
         https://www.selenium.dev/documentation/webdriver/troubleshooting/errors/driver_location/. ${e}`,
+      { cause: e },
     )
   }
 }

package/common/seleniumManager.js

@@ -90,7 +90,7 @@ function binaryPaths(args) {
   try {
     output = JSON.parse(spawnResult.stdout.toString())
   } catch (e) {
-    throw new Error(`Error executing command for ${smBinary} with ${args}: ${e.toString()}`)
+    throw new Error(`Error executing command for ${smBinary} with ${args}: ${e.toString()}`, { cause: e })
   }
 
   logOutput(output)

package/eslint.config.js

@@ -19,13 +19,13 @@ const globals = require('globals')
 const noOnlyTests = require('eslint-plugin-no-only-tests')
 const js = require('@eslint/js')
 const eslintPluginPrettierRecommended = require('eslint-plugin-prettier/recommended')
-const mochaPlugin = require('eslint-plugin-mocha')
-const nodePlugin = require('eslint-plugin-n')
+const mochaPlugin = require('eslint-plugin-mocha').default
+const nodePlugin = require('eslint-plugin-n').default
 
 module.exports = [
   js.configs.recommended,
   eslintPluginPrettierRecommended,
-  mochaPlugin.configs.flat.recommended,
+  mochaPlugin.configs.recommended,
   nodePlugin.configs['flat/recommended-script'],
   {
     languageOptions: {
@@ -80,18 +80,18 @@ module.exports = [
         },
       ],
       'n/prefer-node-protocol': ['error'],
-      'mocha/no-skipped-tests': ['off'],
       'mocha/no-mocha-arrows': ['off'],
       'mocha/no-setup-in-describe': ['off'],
       'mocha/no-top-level-hooks': ['off'],
       'mocha/no-sibling-hooks': ['off'],
       'mocha/no-exports': ['off'],
-      'mocha/no-empty-description': ['off'],
+      'mocha/no-empty-title': ['off'],
       'mocha/max-top-level-suites': ['off'],
       'mocha/consistent-spacing-between-blocks': ['off'],
       'mocha/no-nested-tests': ['off'],
       'mocha/no-pending-tests': ['off'],
       'mocha/no-identical-title': ['off'],
+      'mocha/no-async-suite': ['off'],
       'prettier/prettier': [
         'error',
         {

package/io/zip.js

@@ -19,7 +19,7 @@
 
 const jszip = require('jszip')
 const path = require('node:path')
-const fs = require('fs/promises')
+const fs = require('node:fs/promises')
 const io = require('./index')
 const { InvalidArgumentError } = require('../lib/error')