selenium-webdriver 4.43.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

@@ -33,10 +33,120 @@ class Index extends EventEmitter {
   constructor(_webSocketUrl) {
     super()
     this.connected = false
+    this._closed = false
+    this._pending = new Map()
+    this._connectWaiters = new Set()
     this._ws = new WebSocket(_webSocketUrl)
     this._ws.on('open', () => {
+      // The handshake can complete after close()/_failPending() has already
+      // marked the connection closed. Don't flip connected back to true and
+      // proactively close the now-orphan socket so it does not leak.
+      if (this._closed) {
+        try {
+          this._ws.close()
+        } catch {
+          /* socket already closing */
+        }
+        return
+      }
       this.connected = true
+      for (const { resolve } of this._connectWaiters) {
+        resolve()
+      }
+      this._connectWaiters.clear()
+    })
+    // Single shared response dispatcher. Avoids attaching a new 'message'
+    // listener for every in-flight send(), which previously caused
+    // MaxListenersExceededWarning under concurrent BiDi traffic
+    // (e.g. network interception during a page navigation).
+    this._ws.on('message', (data) => {
+      // Frames can arrive after close() has cleared _pending; ignore them
+      // rather than re-emitting parse errors or dispatching to nothing.
+      if (this._closed) {
+        return
+      }
+      let payload
+      try {
+        payload = JSON.parse(data.toString())
+      } catch (err) {
+        // Surface protocol parse failures rather than silently dropping —
+        // otherwise callers see misleading send() timeouts.
+        const wrapped = new Error(`Failed to parse BiDi message: ${err.message}`)
+        if (this.listenerCount('error') > 0) {
+          this.emit('error', wrapped)
+        } else {
+          process.emitWarning(wrapped.message, 'BiDiProtocolWarning')
+        }
+        return
+      }
+      // 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)
+      if (entry === undefined) {
+        return
+      }
+      clearTimeout(entry.timeoutId)
+      this._pending.delete(payload.id)
+      entry.resolve(payload)
+    })
+    // Fail any in-flight send() calls promptly when the peer disconnects
+    // or the socket errors, instead of waiting for RESPONSE_TIMEOUT.
+    this._ws.on('close', () => {
+      this._failPending(new Error('BiDi connection closed unexpectedly'))
     })
+    this._ws.on('error', (err) => {
+      this._failPending(new Error(`BiDi connection error: ${err.message}`))
+    })
+  }
+
+  /**
+   * Reject any in-flight sends and mark the connection failed. Idempotent so
+   * that close() and the underlying 'close'/'error' events do not double-reject.
+   * @param {Error} error
+   * @private
+   */
+  _failPending(error) {
+    if (this._closed) {
+      return
+    }
+    this._closed = true
+    this.connected = false
+    for (const { reject, timeoutId } of this._pending.values()) {
+      clearTimeout(timeoutId)
+      reject(error)
+    }
+    this._pending.clear()
+    // Reject any callers parked in waitForConnection() so close() (or an
+    // unexpected disconnect) cannot leave them hanging forever.
+    for (const { reject } of this._connectWaiters) {
+      reject(error)
+    }
+    this._connectWaiters.clear()
   }
 
   /**
@@ -69,14 +179,19 @@ class Index extends EventEmitter {
    * @returns {Promise<unknown>}
    */
   async waitForConnection() {
-    return new Promise((resolve) => {
+    return new Promise((resolve, reject) => {
+      if (this._closed) {
+        reject(new Error('BiDi connection is closed'))
+        return
+      }
       if (this.connected) {
         resolve()
-      } else {
-        this._ws.once('open', () => {
-          resolve()
-        })
+        return
       }
+      // Park the waiter in a Set so the constructor's 'open' handler can
+      // resolve it and _failPending() can reject it. Avoids attaching socket
+      // listeners that close()'s removeAllListeners('close') would strip.
+      this._connectWaiters.add({ resolve, reject })
     })
   }
 
@@ -86,9 +201,18 @@ class Index extends EventEmitter {
    * @returns {Promise<unknown>}
    */
   async send(params) {
+    if (this._closed) {
+      throw new Error('BiDi connection is closed')
+    }
     if (!this.connected) {
       await this.waitForConnection()
     }
+    // Defense in depth: even after waitForConnection() resolves, the socket
+    // may have transitioned to CLOSING/CLOSED (e.g. caller closed the raw
+    // socket). Refuse rather than throwing from inside ws.send().
+    if (this._ws.readyState !== WebSocket.OPEN) {
+      throw new Error('BiDi connection is not open')
+    }
 
     const id = ++this.id
 
@@ -96,25 +220,11 @@ class Index extends EventEmitter {
 
     return new Promise((resolve, reject) => {
       const timeoutId = setTimeout(() => {
+        this._pending.delete(id)
         reject(new Error(`Request with id ${id} timed out`))
-        handler.off('message', listener)
       }, RESPONSE_TIMEOUT)
 
-      const listener = (data) => {
-        try {
-          const payload = JSON.parse(data.toString())
-          if (payload.id === id) {
-            clearTimeout(timeoutId)
-            handler.off('message', listener)
-            resolve(payload)
-          }
-        } catch (err) {
-          // eslint-disable-next-line no-undef
-          log.error(`Failed parse message: ${err.message}`)
-        }
-      }
-
-      const handler = this._ws.on('message', listener)
+      this._pending.set(id, { resolve, reject, timeoutId })
     })
   }
 
@@ -206,6 +316,8 @@ class Index extends EventEmitter {
    * @returns {Promise<unknown>}
    */
   close() {
+    this._failPending(new Error('BiDi connection closed before response was received'))
+
     const closeWebSocket = (callback) => {
       // don't close if it's already closed
       if (this._ws.readyState === 3) {