selenium-webdriver 4.47.0 → 4.48.0

package/CHANGES.md

@@ -1,3 +1,12 @@
+## 4.48.0
+
+- Support CDP versions: v150, v151, v152
+- Normalize empty custom locator results (#17851)
+- [build] Automated Browser Version Update (major) with CDP (#17910)
+- Ensure BiDi is not exposed on Driver (#17926)
+- Add serialization and domain layer (#17927)
+- [bidi] Add BiDi connection-level event subscription (#17946)
+
 ## 4.47.0
 
 - Support CDP versions: v149, v150, v151

package/bidi/domain.js

@@ -0,0 +1,87 @@
+// 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 { getBidiConnection } = require('../lib/bidi_connection')
+
+// Gates Domain's constructor so `new Network(someRandomThing)` fails loudly
+// instead of silently producing a broken instance. A Symbol can't be forged
+// or guessed, so this is real runtime enforcement, not just a TS annotation —
+// only a generated `Class.create(driver)` (and this package's own tests) may
+// pass it. It's exported deliberately, not hidden: the point is to stop
+// accidental misuse of the normal `new Network(x)` shape, not to defend
+// against someone who deliberately imports and passes this.
+const DOMAIN_TOKEN = Symbol('Domain internal construction token — obtained only via Class.create(driver)')
+
+/**
+ * Describes one subscribable BiDi event, for use with Domain#addCallback().
+ * @param {string} method
+ * @param {{fromWire(payload: unknown): unknown}} [type] Runtime record/union
+ *   class for the event's params, if the schema declares one. When present,
+ *   addCallback() parses each delivered payload through it before the
+ *   caller's handler runs — inbound wire payloads are validated against
+ *   their resolved type; an event's params is such a payload just as much
+ *   as a command's result is.
+ * @returns {{method: string, type: ({fromWire(payload: unknown): unknown}|undefined)}}
+ *   The event descriptor, ready to pass to Domain#addCallback().
+ */
+function event(method, type) {
+  return { method, type }
+}
+
+/** Shared base for every generated BiDi domain class. See domain.d.ts for the typed surface. */
+class Domain {
+  #bidi
+
+  constructor(bidi, token) {
+    if (token !== DOMAIN_TOKEN) {
+      throw new TypeError(`${new.target.name} must be constructed via ${new.target.name}.create(driver), not \`new\``)
+    }
+    this.#bidi = bidi
+  }
+
+  static async connect(driver) {
+    return getBidiConnection(driver)
+  }
+
+  async send(method, params) {
+    const response = await this.#bidi.send({ method, params })
+    if (response?.error !== undefined) {
+      throw new Error(`${response.error}: ${response.message}`)
+    }
+    return response?.result
+  }
+
+  /**
+   * Subscribes `handler` to a BiDi event. All the actual subscription-lifecycle
+   * work — remote subscribe/unsubscribe, per-subscription bookkeeping — lives on
+   * the connection itself (see Index#addCallback in bidi/index.js); Domain only
+   * adds the one thing the connection can't do on its own: parsing a delivered
+   * payload through the descriptor's type before the caller's handler runs.
+   * @param {{method: string, type: ({fromWire(payload: unknown): unknown}|undefined)}} descriptor
+   *   An event descriptor from event().
+   * @param {function(unknown): void} handler Invoked with the event's params
+   *   (parsed through descriptor.type first, if one was given) each time it fires.
+   * @returns {Promise<{id: string, unsubscribe: function(): Promise<void>}>}
+   *   A handle for this subscription — call `unsubscribe()` to stop receiving the event.
+   */
+  async addCallback(descriptor, handler) {
+    const dispatch = descriptor.type === undefined ? handler : (params) => handler(descriptor.type.fromWire(params))
+    return this.#bidi.addCallback(descriptor.method, dispatch)
+  }
+}
+
+module.exports = { Domain, event, DOMAIN_TOKEN }

package/bidi/index.js

@@ -36,6 +36,10 @@ class Index extends EventEmitter {
     this._closed = false
     this._pending = new Map()
     this._connectWaiters = new Set()
+    // removeCallback(id) only receives the subscriptionId — off() needs the event
+    // name and the exact handler function too, so this holds what it needs to
+    // detach the right listener without the caller having to keep them around.
+    this._callbacks = new Map()
     this._ws = new WebSocket(_webSocketUrl)
     this._ws.on('open', () => {
       // The handshake can complete after close()/_failPending() has already
@@ -71,12 +75,7 @@ class Index extends EventEmitter {
       } 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')
-        }
+        this._emitOrWarn(new Error(`Failed to parse BiDi message: ${err.message}`), 'BiDiProtocolWarning')
         return
       }
       // Messages without a numeric id are BiDi events, not command responses.
@@ -94,14 +93,31 @@ class Index extends EventEmitter {
           // 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')
-            }
+            this._emitOrWarn(
+              new Error(`BiDi protocol error event: ${JSON.stringify(payload.params)}`),
+              'BiDiProtocolWarning',
+            )
           } else {
-            this.emit(payload.method, payload.params)
+            // A listener can throw synchronously — most notably a typed
+            // addCallback() dispatcher's fromWire() rejecting a corrupted
+            // payload, which is meant to error rather than warn. Dispatched
+            // one listener at a time (not via a single this.emit() call) so a
+            // throwing listener doesn't prevent a sibling listener registered
+            // for the same event from still receiving this delivery — emit()
+            // itself aborts the rest of its iteration once one listener throws.
+            // rawListeners(), not listeners(): listeners() unwraps a once()
+            // registration to the caller's original function, so invoking it
+            // here directly (bypassing emit()) would skip the internal wrapper
+            // that removes it after one call — rawListeners() returns that
+            // wrapper itself, preserving once()'s self-removal.
+            for (const listener of this.rawListeners(payload.method)) {
+              try {
+                listener(payload.params)
+              } catch (err) {
+                const wrapped = err instanceof Error ? err : new Error(String(err))
+                this._emitOrWarn(wrapped, 'BiDiEventHandlerWarning')
+              }
+            }
           }
         }
         return
@@ -147,6 +163,38 @@ class Index extends EventEmitter {
       reject(error)
     }
     this._connectWaiters.clear()
+    // Detach every addCallback() listener too. Once closed, removeCallback()
+    // can no longer reach the remote end (send() would just throw), so nothing
+    // else will ever detach these listeners. Drop them here instead of leaving
+    // them attached to an EventEmitter nothing will ever emit on again.
+    for (const { method, handler } of this._callbacks.values()) {
+      this.off(method, handler)
+    }
+    this._callbacks.clear()
+  }
+
+  /**
+   * Emits `err` as an 'error' event if anything is listening for one,
+   * otherwise reports it as a process warning under `warningType` — never
+   * emits 'error' with no listener attached, which would itself throw and
+   * crash the process. Also guards against the 'error' listener itself
+   * throwing, so a broken listener can't cause the exact kind of crash this
+   * helper exists to prevent, just one level removed.
+   * @param {Error} err
+   * @param {string} warningType
+   * @private
+   */
+  _emitOrWarn(err, warningType) {
+    if (this.listenerCount('error') === 0) {
+      process.emitWarning(err.message, warningType)
+      return
+    }
+    try {
+      this.emit('error', err)
+    } catch (listenerErr) {
+      const wrapped = listenerErr instanceof Error ? listenerErr : new Error(String(listenerErr))
+      process.emitWarning(`BiDi 'error' listener threw: ${wrapped.message}`, warningType)
+    }
   }
 
   /**
@@ -229,7 +277,17 @@ class Index extends EventEmitter {
   }
 
   /**
-   * Subscribe to events
+   * Subscribe to events.
+   *
+   * Not the correct implementation — this is not tied to a subscription id, so
+   * {@link unsubscribe} below cancels by event/context name and can affect a
+   * subscription made elsewhere (including via {@link addCallback}) for the
+   * same event. Kept as-is only because the existing hand-written bidi/*.js
+   * modules already depend on this exact shape; new code should use
+   * {@link addCallback} instead, which is properly scoped by subscription id
+   * (mirroring Java's BiDi#addListener/removeListener — see BiDi.java). Once
+   * those hand-written modules are replaced by generated code built on
+   * addCallback/removeCallback, this method (and unsubscribe) can be removed.
    * @param events
    * @param browsingContexts
    * @returns {Promise<void>}
@@ -273,7 +331,10 @@ class Index extends EventEmitter {
   }
 
   /**
-   * Unsubscribe to events
+   * Unsubscribe to events. See the note on {@link subscribe} above — this
+   * cancels by event/context name, not by subscription id, so it can affect a
+   * subscription this same connection made elsewhere. New code should call
+   * the returned handle's `unsubscribe()` from {@link addCallback} instead.
    * @param events
    * @param browsingContexts
    * @returns {Promise<void>}
@@ -311,6 +372,117 @@ class Index extends EventEmitter {
     await this.send(params)
   }
 
+  /**
+   * Registers `handler` to be called on every delivered `method` event,
+   * globally (no context/user-context scoping). This is the correct mechanism
+   * — see the note on {@link subscribe}/{@link unsubscribe} above, which is a
+   * separate, imprecise, event-name-scoped mechanism kept only for the
+   * existing hand-written bidi/*.js modules until they're replaced by
+   * generated code built on this method instead.
+   *
+   * Keyed by the server-assigned `subscription` id from `session.subscribe`'s
+   * response, which the spec mints fresh on every call — so multiple
+   * independent subscriptions to the same event coexist safely, and the
+   * returned handle's `unsubscribe()` never affects another callback
+   * registered for the same method. No client-side ref-counting is needed:
+   * the protocol's own per-subscription id already gives each caller its own
+   * independent, individually-cancellable registration.
+   *
+   * The local listener is attached before `session.subscribe` is awaited, not
+   * after — so an event the browser starts sending as soon as it processes
+   * the subscription can't arrive in a gap where nothing is listening yet.
+   * If the subscribe call then fails (or returns no usable id), the listener
+   * is removed again before the error propagates, so a failed subscription
+   * doesn't leak one.
+   * @param {string} method
+   * @param {function(unknown): void} handler
+   * @returns {Promise<{id: string, unsubscribe: function(): Promise<void>}>}
+   */
+  async addCallback(method, handler) {
+    this.on(method, handler)
+
+    try {
+      const response = await this.send({
+        method: 'session.subscribe',
+        params: { events: [method] },
+      })
+      // send() resolves with the raw reply on any response, including a
+      // wire-level error — check for one explicitly and surface it plainly,
+      // rather than letting it fall through to the generic "no subscription
+      // id" message below (matching how Domain#send() reports the same shape).
+      if (response?.error !== undefined) {
+        throw new Error(`${response.error}: ${response.message}`)
+      }
+      const subscriptionId = response?.result?.subscription
+      if (typeof subscriptionId !== 'string' || subscriptionId === '') {
+        throw new Error(`session.subscribe did not return a valid subscription id: ${JSON.stringify(response)}`)
+      }
+
+      this._callbacks.set(subscriptionId, { method, handler })
+
+      return {
+        id: subscriptionId,
+        unsubscribe: () => this.removeCallback(subscriptionId),
+      }
+    } catch (err) {
+      this.off(method, handler)
+      throw err
+    }
+  }
+
+  /**
+   * Removes exactly the callback registered under `subscriptionId` (as
+   * returned by {@link addCallback}). A no-op if already removed — including
+   * once the connection is closed, since _failPending() has already cleaned
+   * up local state at that point (and there is no remote end left to reach:
+   * entry is only ever defined here while _closed is still false, since
+   * _failPending() clears every entry in the same synchronous call that sets
+   * _closed). Never affects any other callback, including another one
+   * registered for the same method.
+   *
+   * Local state is only cleaned up once the remote end has confirmed the
+   * subscription is actually gone — not before sending session.unsubscribe,
+   * and not on a wire-level error response. Cleaning up first would leave a
+   * phantom "removed" subscription if the send failed or was rejected: local
+   * delivery would stop while the browser kept sending it, and a retry would
+   * silently no-op since this method's own early return above would find no
+   * entry left to act on.
+   *
+   * Concurrent calls for the same subscriptionId share one in-flight removal
+   * instead of each sending their own session.unsubscribe — a second, racing
+   * call would otherwise find the subscription already gone (removed by the
+   * first) and get a wire-level error for what was a perfectly valid call.
+   * The in-flight marker is cleared once the attempt settles, either way, so
+   * a later retry after a failure starts a fresh attempt rather than reusing
+   * a rejected one.
+   * @param {string} subscriptionId
+   * @returns {Promise<void>}
+   */
+  async removeCallback(subscriptionId) {
+    const entry = this._callbacks.get(subscriptionId)
+    if (entry === undefined) {
+      return
+    }
+
+    if (entry.removing === undefined) {
+      entry.removing = (async () => {
+        const response = await this.send({
+          method: 'session.unsubscribe',
+          params: { subscriptions: [subscriptionId] },
+        })
+        if (response?.error !== undefined) {
+          throw new Error(`${response.error}: ${response.message}`)
+        }
+        this._callbacks.delete(subscriptionId)
+        this.off(entry.method, entry.handler)
+      })().finally(() => {
+        entry.removing = undefined
+      })
+    }
+
+    return entry.removing
+  }
+
   /**
    * Close ws connection.
    * @returns {Promise<unknown>}

package/bidi/serialization/enum.js

@@ -0,0 +1,35 @@
+// 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 { register } = require('./registry')
+
+/**
+ * Registers a schema `enum` — a closed set of string values a field may hold.
+ * @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}}
+ *   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.
+ */
+function defineEnum(name, values) {
+  const allowed = new Set(values)
+  const entry = { kind: 'enum', values, includes: (value) => allowed.has(value) }
+  register(name, entry)
+  return entry
+}
+
+module.exports = { defineEnum }