selenium-webdriver 4.21.0 → 4.23.0

package/CHANGES.md

@@ -1,3 +1,23 @@
+## 4.23.0
+
+- Expose pnpm as a tool we can use
+- [bidi] Fix the event unsubscribe method. Update modules to have close methods. (#14192)
+- Run Node browser tests on the RBE (#14194)
+- [bidi] Add methods to add/remove handlers in Script module (#14230)
+- [bidi] Add source type to log entry (#14244)
+- [bidi] Add dom mutation handlers (#14238)
+- [bidi] Add high-level script pinning APIs (#14250)
+- [bidi] Deprecate argument value wrapper class (#14251)
+- Add CDP for Chrome 127 and remove 124
+
+## 4.22.0
+
+- [bidi] Add types for user prompt related events (#14097)
+- Add preference to enable CDP in Firefox by default (#14091)
+- [bidi] Add callback handlers for logging APIs (#14120)
+- [bidi] Add high-level logging API (#14135)
+- Add CDP for Chrome 126 and remove 123
+
 ## 4.21.0
 
 - Add CDP for Chrome 125 and remove 122

package/README.md

@@ -217,7 +217,7 @@ under the License.
 
 [LTS]: https://github.com/nodejs/LTS
 [PATH]: http://en.wikipedia.org/wiki/PATH_%28variable%29
-[api]: http://seleniumhq.github.io/selenium/docs/api/javascript/module/selenium-webdriver/
+[api]: https://www.selenium.dev/selenium/docs/api/javascript/
 [chrome]: https://googlechromelabs.github.io/chrome-for-testing/#stable
 [gh]: https://github.com/SeleniumHQ/selenium/
 [issues]: https://github.com/SeleniumHQ/selenium/issues

package/bidi/argumentValue.js

@@ -17,6 +17,11 @@
 
 const { LocalValue } = require('./protocolValue')
 
+/**
+ * @deprecated
+ * in favor of LocalValue methods for all argument values.
+ * This extra wrapper is not required.
+ */
 class ArgumentValue {
   constructor(value) {
     this.value = value
@@ -24,7 +29,7 @@ class ArgumentValue {
 
   asMap() {
     if (this.value instanceof LocalValue) {
-      return this.value.toJson()
+      return this.value.asMap()
     } else {
       // ReferenceValue
       return this.value.asMap()

package/bidi/browsingContextInspector.js

@@ -15,7 +15,7 @@
 // specific language governing permissions and limitations
 // under the License.
 
-const { BrowsingContextInfo, NavigationInfo } = require('./browsingContextTypes')
+const { BrowsingContextInfo, NavigationInfo, UserPromptOpened, UserPromptClosed } = require('./browsingContextTypes')
 
 /**
  * Represents a browsing context related events.
@@ -127,8 +127,10 @@ class BrowsingContextInspector {
         let response = null
         if ('navigation' in params) {
           response = new NavigationInfo(params.context, params.navigation, params.timestamp, params.url)
+        } else if ('type' in params) {
+          response = new UserPromptOpened(params.context, params.type, params.message)
         } else if ('accepted' in params) {
-          /* Needs to be updated when browsers implement other events */
+          response = new UserPromptClosed(params.context, params.accepted, params.userText)
         } else {
           response = new BrowsingContextInfo(params.context, params.url, params.children, params.parent)
         }
@@ -136,6 +138,29 @@ class BrowsingContextInspector {
       }
     })
   }
+
+  async close() {
+    if (
+      this._browsingContextIds !== null &&
+      this._browsingContextIds !== undefined &&
+      this._browsingContextIds.length > 0
+    ) {
+      await this.bidi.unsubscribe(
+        'browsingContext.contextCreated',
+        'browsingContext.contextDestroyed',
+        'browsingContext.fragmentNavigated',
+        'browsingContext.userPromptClosed',
+        this._browsingContextIds,
+      )
+    } else {
+      await this.bidi.unsubscribe(
+        'browsingContext.contextCreated',
+        'browsingContext.contextDestroyed',
+        'browsingContext.fragmentNavigated',
+        'browsingContext.userPromptClosed',
+      )
+    }
+  }
 }
 
 async function getBrowsingContextInstance(driver, browsingContextIds = null) {

package/bidi/browsingContextTypes.js

@@ -80,4 +80,20 @@ class NavigationInfo {
   }
 }
 
-module.exports = { BrowsingContextInfo, NavigationInfo }
+class UserPromptOpened {
+  constructor(browsingContextId, type, message) {
+    this.browsingContextId = browsingContextId
+    this.type = type
+    this.message = message
+  }
+}
+
+class UserPromptClosed {
+  constructor(browsingContextId, accepted, userText = undefined) {
+    this.browsingContextId = browsingContextId
+    this.accepted = accepted
+    this.userText = userText
+  }
+}
+
+module.exports = { BrowsingContextInfo, NavigationInfo, UserPromptOpened, UserPromptClosed }

package/bidi/index.js

@@ -157,6 +157,8 @@ class Index extends EventEmitter {
       params.params.contexts = contextsArray
     }
 
+    this.events.push(...eventsArray)
+
     await this.send(params)
   }
 
@@ -167,11 +169,14 @@ class Index extends EventEmitter {
    * @returns {Promise<void>}
    */
   async unsubscribe(events, browsingContexts) {
-    if (typeof events === 'string') {
-      this.events = this.events.filter((event) => event !== events)
-    } else if (Array.isArray(events)) {
-      this.events = this.events.filter((event) => !events.includes(event))
-    }
+    const eventsToRemove = typeof events === 'string' ? [events] : events
+
+    // Check if the eventsToRemove are in the subscribed events array
+    // Filter out events that are not in this.events before filtering
+    const existingEvents = eventsToRemove.filter((event) => this.events.includes(event))
+
+    // Remove the events from the subscribed events array
+    this.events = this.events.filter((event) => !existingEvents.includes(event))
 
     if (typeof browsingContexts === 'string') {
       this.browsingContexts.pop()
@@ -179,10 +184,13 @@ class Index extends EventEmitter {
       this.browsingContexts = this.browsingContexts.filter((id) => !browsingContexts.includes(id))
     }
 
+    if (existingEvents.length === 0) {
+      return
+    }
     const params = {
       method: 'session.unsubscribe',
       params: {
-        events: this.events,
+        events: existingEvents,
       },
     }
 

package/bidi/logEntries.js

@@ -17,6 +17,8 @@
 
 'use strict'
 
+const { Source } = require('./scriptTypes')
+
 /**
  * Represents a base log entry.
  * Desribed in https://w3c.github.io/webdriver-bidi/#types-log-logentry.
@@ -25,12 +27,14 @@ class BaseLogEntry {
   /**
    * Creates a new instance of BaseLogEntry.
    * @param {string} level - The log level.
+   * @param {string} text - The log source.
    * @param {string} text - The log text.
    * @param {number} timeStamp - The log timestamp.
    * @param {string} stackTrace - The log stack trace.
    */
-  constructor(level, text, timeStamp, stackTrace) {
+  constructor(level, source, text, timeStamp, stackTrace) {
     this._level = level
+    this._source = new Source(source)
     this._text = text
     this._timeStamp = timeStamp
     this._stackTrace = stackTrace
@@ -67,6 +71,10 @@ class BaseLogEntry {
   get stackTrace() {
     return this._stackTrace
   }
+
+  get source() {
+    return this._source
+  }
 }
 
 /**
@@ -83,8 +91,8 @@ class GenericLogEntry extends BaseLogEntry {
    * @param {string} type - The log type.
    * @param {string} stackTrace - The log stack trace.
    */
-  constructor(level, text, timeStamp, type, stackTrace) {
-    super(level, text, timeStamp, stackTrace)
+  constructor(level, source, text, timeStamp, type, stackTrace) {
+    super(level, source, text, timeStamp, stackTrace)
     this._type = type
   }
 
@@ -103,10 +111,9 @@ class GenericLogEntry extends BaseLogEntry {
  * @extends GenericLogEntry
  */
 class ConsoleLogEntry extends GenericLogEntry {
-  constructor(level, text, timeStamp, type, method, realm, args, stackTrace) {
-    super(level, text, timeStamp, type, stackTrace)
+  constructor(level, source, text, timeStamp, type, method, args, stackTrace) {
+    super(level, source, text, timeStamp, type, stackTrace)
     this._method = method
-    this._realm = realm
     this._args = args
   }
 
@@ -117,15 +124,6 @@ class ConsoleLogEntry extends GenericLogEntry {
   get method() {
     return this._method
   }
-
-  /**
-   * Gets the realm associated with the log entry.
-   * @returns {string} The realm associated with the log entry.
-   */
-  get realm() {
-    return this._realm
-  }
-
   /**
    * Gets the arguments associated with the log entry.
    * @returns {Array} The arguments associated with the log entry.
@@ -141,8 +139,8 @@ class ConsoleLogEntry extends GenericLogEntry {
  * @extends GenericLogEntry
  */
 class JavascriptLogEntry extends GenericLogEntry {
-  constructor(level, text, timeStamp, type, stackTrace) {
-    super(level, text, timeStamp, type, stackTrace)
+  constructor(level, source, text, timeStamp, type, stackTrace) {
+    super(level, source, text, timeStamp, type, stackTrace)
   }
 }
 

package/bidi/logInspector.js

@@ -21,16 +21,31 @@ const { ConsoleLogEntry, JavascriptLogEntry, GenericLogEntry } = require('./logE
 const LOG = {
   TYPE_CONSOLE: 'console',
   TYPE_JS_LOGS: 'javascript',
+  TYPE_JS_EXCEPTION: 'javascriptException',
+  TYPE_LOGS: 'logs',
+  TYPE_CONSOLE_FILTER: 'console_filter',
+  TYPE_JS_LOGS_FILTER: 'javascript_filter',
+  TYPE_JS_EXCEPTION_FILTER: 'javascriptException_filter',
+  TYPE_LOGS_FILTER: 'logs_filter',
 }
 
 class LogInspector {
   bidi
   ws
+  #callbackId = 0
 
   constructor(driver, browsingContextIds) {
     this._driver = driver
     this._browsingContextIds = browsingContextIds
-    this.listener = {}
+    this.listener = new Map()
+    this.listener.set(LOG.TYPE_CONSOLE, new Map())
+    this.listener.set(LOG.TYPE_JS_LOGS, new Map())
+    this.listener.set(LOG.TYPE_JS_EXCEPTION, new Map())
+    this.listener.set(LOG.TYPE_LOGS, new Map())
+    this.listener.set(LOG.TYPE_CONSOLE_FILTER, new Map())
+    this.listener.set(LOG.TYPE_JS_LOGS_FILTER, new Map())
+    this.listener.set(LOG.TYPE_JS_EXCEPTION_FILTER, new Map())
+    this.listener.set(LOG.TYPE_LOGS_FILTER, new Map())
   }
 
   /**
@@ -42,12 +57,47 @@ class LogInspector {
     await this.bidi.subscribe('log.entryAdded', this._browsingContextIds)
   }
 
-  /**
-   * @param kind
-   */
-  logListener(kind) {
-    if (!(kind in this.listener)) {
-      this.listener[kind] = []
+  addCallback(eventType, callback) {
+    const id = ++this.#callbackId
+
+    const eventCallbackMap = this.listener.get(eventType)
+    eventCallbackMap.set(id, callback)
+    return id
+  }
+
+  removeCallback(id) {
+    let hasId = false
+    for (const [, callbacks] of this.listener) {
+      if (callbacks.has(id)) {
+        callbacks.delete(id)
+        hasId = true
+      }
+    }
+
+    if (!hasId) {
+      throw Error(`Callback with id ${id} not found`)
+    }
+  }
+
+  invokeCallbacks(eventType, data) {
+    const callbacks = this.listener.get(eventType)
+    if (callbacks) {
+      for (const [, callback] of callbacks) {
+        callback(data)
+      }
+    }
+  }
+
+  invokeCallbacksWithFilter(eventType, data, filterLevel) {
+    const callbacks = this.listener.get(eventType)
+    if (callbacks) {
+      for (const [, value] of callbacks) {
+        const callback = value.callback
+        const filter = value.filter
+        if (filterLevel === filter.getLevel()) {
+          callback(data)
+        }
+      }
     }
   }
 
@@ -55,13 +105,21 @@ class LogInspector {
    * Listen to Console logs
    * @param callback
    * @param filterBy
-   * @returns {Promise<void>}
+   * @returns {Promise<number>}
    */
   async onConsoleEntry(callback, filterBy = undefined) {
     if (filterBy !== undefined && !(filterBy instanceof FilterBy)) {
       throw Error(`Pass valid FilterBy object. Received: ${filterBy}`)
     }
 
+    let id
+
+    if (filterBy !== undefined) {
+      id = this.addCallback(LOG.TYPE_CONSOLE_FILTER, { callback: callback, filter: filterBy })
+    } else {
+      id = this.addCallback(LOG.TYPE_CONSOLE, callback)
+    }
+
     this.ws = await this.bidi.socket
 
     this.ws.on('message', (event) => {
@@ -70,38 +128,48 @@ class LogInspector {
       if (params?.type === LOG.TYPE_CONSOLE) {
         let consoleEntry = new ConsoleLogEntry(
           params.level,
+          params.source,
           params.text,
           params.timestamp,
           params.type,
           params.method,
-          params.realm,
           params.args,
           params.stackTrace,
         )
 
         if (filterBy !== undefined) {
           if (params?.level === filterBy.getLevel()) {
-            callback(consoleEntry)
+            this.invokeCallbacksWithFilter(LOG.TYPE_CONSOLE_FILTER, consoleEntry, filterBy.getLevel())
           }
           return
         }
 
-        callback(consoleEntry)
+        this.invokeCallbacks(LOG.TYPE_CONSOLE, consoleEntry)
       }
     })
+
+    return id
   }
 
   /**
    * Listen to JS logs
    * @param callback
    * @param filterBy
-   * @returns {Promise<void>}
+   * @returns {Promise<number>}
    */
   async onJavascriptLog(callback, filterBy = undefined) {
     if (filterBy !== undefined && !(filterBy instanceof FilterBy)) {
       throw Error(`Pass valid FilterBy object. Received: ${filterBy}`)
     }
 
+    let id
+
+    if (filterBy !== undefined) {
+      id = this.addCallback(LOG.TYPE_JS_LOGS_FILTER, { callback: callback, filter: filterBy })
+    } else {
+      id = this.addCallback(LOG.TYPE_JS_LOGS, callback)
+    }
+
     this.ws = await this.bidi.socket
 
     this.ws.on('message', (event) => {
@@ -110,6 +178,7 @@ class LogInspector {
       if (params?.type === LOG.TYPE_JS_LOGS) {
         let jsEntry = new JavascriptLogEntry(
           params.level,
+          params.source,
           params.text,
           params.timestamp,
           params.type,
@@ -118,59 +187,64 @@ class LogInspector {
 
         if (filterBy !== undefined) {
           if (params?.level === filterBy.getLevel()) {
-            callback(jsEntry)
+            this.invokeCallbacksWithFilter(LOG.TYPE_JS_LOGS_FILTER, jsEntry, filterBy.getLevel())
           }
           return
         }
 
-        callback(jsEntry)
+        this.invokeCallbacks(LOG.TYPE_JS_LOGS, jsEntry)
       }
     })
+
+    return id
   }
 
   /**
    * Listen to JS Exceptions
    * @param callback
-   * @returns {Promise<void>}
+   * @returns {Promise<number>}
    */
   async onJavascriptException(callback) {
+    const id = this.addCallback(LOG.TYPE_JS_EXCEPTION, callback)
     this.ws = await this.bidi.socket
-    let enabled = LOG.TYPE_JS_EXCEPTION in this.listener || this.logListener(LOG.TYPE_JS_EXCEPTION)
-    this.listener[LOG.TYPE_JS_EXCEPTION].push(callback)
-
-    if (enabled) {
-      return
-    }
 
     this.ws.on('message', (event) => {
       const { params } = JSON.parse(Buffer.from(event.toString()))
       if (params?.type === 'javascript' && params?.level === 'error') {
         let jsErrorEntry = new JavascriptLogEntry(
           params.level,
+          params.source,
           params.text,
           params.timestamp,
           params.type,
           params.stackTrace,
         )
 
-        this.listener[LOG.TYPE_JS_EXCEPTION].forEach((listener) => {
-          listener(jsErrorEntry)
-        })
+        this.invokeCallbacks(LOG.TYPE_JS_EXCEPTION, jsErrorEntry)
       }
     })
+
+    return id
   }
 
   /**
    * Listen to any logs
    * @param callback
    * @param filterBy
-   * @returns {Promise<void>}
+   * @returns {Promise<number>}
    */
   async onLog(callback, filterBy = undefined) {
     if (filterBy !== undefined && !(filterBy instanceof FilterBy)) {
       throw Error(`Pass valid FilterBy object. Received: ${filterBy}`)
     }
 
+    let id
+    if (filterBy !== undefined) {
+      id = this.addCallback(LOG.TYPE_LOGS_FILTER, { callback: callback, filter: filterBy })
+    } else {
+      id = this.addCallback(LOG.TYPE_LOGS, callback)
+    }
+
     this.ws = await this.bidi.socket
 
     this.ws.on('message', (event) => {
@@ -178,6 +252,7 @@ class LogInspector {
       if (params?.type === 'javascript') {
         let jsEntry = new JavascriptLogEntry(
           params.level,
+          params.source,
           params.text,
           params.timestamp,
           params.type,
@@ -191,36 +266,46 @@ class LogInspector {
           return
         }
 
-        callback(jsEntry)
+        if (filterBy !== undefined) {
+          if (params?.level === filterBy.getLevel()) {
+            {
+              this.invokeCallbacksWithFilter(LOG.TYPE_LOGS_FILTER, jsEntry, filterBy.getLevel())
+            }
+            return
+          }
+        }
+
+        this.invokeCallbacks(LOG.TYPE_LOGS, jsEntry)
         return
       }
 
       if (params?.type === 'console') {
         let consoleEntry = new ConsoleLogEntry(
           params.level,
+          params.source,
           params.text,
           params.timestamp,
           params.type,
           params.method,
-          params.realm,
           params.args,
           params.stackTrace,
         )
 
         if (filterBy !== undefined) {
           if (params?.level === filterBy.getLevel()) {
-            callback(consoleEntry)
+            this.invokeCallbacksWithFilter(LOG.TYPE_LOGS_FILTER, consoleEntry, filterBy.getLevel())
           }
           return
         }
 
-        callback(consoleEntry)
+        this.invokeCallbacks(LOG.TYPE_LOGS, consoleEntry)
         return
       }
 
       if (params !== undefined && !['console', 'javascript'].includes(params?.type)) {
         let genericEntry = new GenericLogEntry(
           params.level,
+          params.source,
           params.text,
           params.timestamp,
           params.type,
@@ -229,14 +314,19 @@ class LogInspector {
 
         if (filterBy !== undefined) {
           if (params?.level === filterBy.getLevel()) {
-            callback(genericEntry)
+            {
+              this.invokeCallbacksWithFilter(LOG.TYPE_LOGS_FILTER, genericEntry, filterBy.getLevel())
+            }
+            return
           }
-          return
         }
 
-        callback(genericEntry)
+        this.invokeCallbacks(LOG.TYPE_LOGS, genericEntry)
+        return
       }
     })
+
+    return id
   }
 
   /**
@@ -244,7 +334,15 @@ class LogInspector {
    * @returns {Promise<void>}
    */
   async close() {
-    await this.bidi.unsubscribe('log.entryAdded', this._browsingContextIds)
+    if (
+      this._browsingContextIds !== null &&
+      this._browsingContextIds !== undefined &&
+      this._browsingContextIds.length > 0
+    ) {
+      await this.bidi.unsubscribe('log.entryAdded', this._browsingContextIds)
+    } else {
+      await this.bidi.unsubscribe('log.entryAdded')
+    }
   }
 }
 

package/bidi/network.js

@@ -313,12 +313,26 @@ class Network {
    * @returns {Promise<void>} A promise that resolves when the network connection is closed.
    */
   async close() {
-    await this.bidi.unsubscribe(
-      'network.beforeRequestSent',
-      'network.responseStarted',
-      'network.responseCompleted',
-      'network.authRequired',
-    )
+    if (
+      this._browsingContextIds !== null &&
+      this._browsingContextIds !== undefined &&
+      this._browsingContextIds.length > 0
+    ) {
+      await this.bidi.unsubscribe(
+        'network.beforeRequestSent',
+        'network.responseStarted',
+        'network.responseCompleted',
+        'network.authRequired',
+        this._browsingContextIds,
+      )
+    } else {
+      await this.bidi.unsubscribe(
+        'network.beforeRequestSent',
+        'network.responseStarted',
+        'network.responseCompleted',
+        'network.authRequired',
+      )
+    }
   }
 }
 

package/bidi/protocolValue.js

@@ -185,7 +185,11 @@ class LocalValue {
     return new LocalValue(NonPrimitiveType.CHANNEL, value)
   }
 
-  toJson() {
+  static createReferenceValue(handle, sharedId) {
+    return new ReferenceValue(handle, sharedId)
+  }
+
+  asMap() {
     let toReturn = {}
     toReturn[TYPE_CONSTANT] = this.type
 

package/bidi/scriptManager.js

@@ -27,14 +27,58 @@ const { RemoteValue } = require('./protocolValue')
 const { Source } = require('./scriptTypes')
 const { WebDriverError } = require('../lib/error')
 
+const ScriptEvent = {
+  MESSAGE: 'script.message',
+  REALM_CREATED: 'script.realmCreated',
+  REALM_DESTROYED: 'script.realmDestroyed',
+}
+
 /**
  * Represents class to run events and commands of Script module.
  * Described in https://w3c.github.io/webdriver-bidi/#module-script.
  * @class
  */
 class ScriptManager {
+  #callbackId = 0
+  #listener
+
   constructor(driver) {
     this._driver = driver
+    this.#listener = new Map()
+    this.#listener.set(ScriptEvent.MESSAGE, new Map())
+    this.#listener.set(ScriptEvent.REALM_CREATED, new Map())
+    this.#listener.set(ScriptEvent.REALM_DESTROYED, new Map())
+  }
+
+  addCallback(eventType, callback) {
+    const id = ++this.#callbackId
+
+    const eventCallbackMap = this.#listener.get(eventType)
+    eventCallbackMap.set(id, callback)
+    return id
+  }
+
+  removeCallback(id) {
+    let hasId = false
+    for (const [, callbacks] of this.#listener) {
+      if (callbacks.has(id)) {
+        callbacks.delete(id)
+        hasId = true
+      }
+    }
+
+    if (!hasId) {
+      throw Error(`Callback with id ${id} not found`)
+    }
+  }
+
+  invokeCallbacks(eventType, data) {
+    const callbacks = this.#listener.get(eventType)
+    if (callbacks) {
+      for (const [, callback] of callbacks) {
+        callback(data)
+      }
+    }
   }
 
   async init(browsingContextIds) {
@@ -251,6 +295,14 @@ class ScriptManager {
       params.contexts = new Array(this._browsingContextIds)
     }
 
+    if (argumentValueList != null) {
+      let argumentParams = []
+      argumentValueList.forEach((argumentValue) => {
+        argumentParams.push(argumentValue.asMap())
+      })
+      params['arguments'] = argumentParams
+    }
+
     const command = {
       method: 'script.addPreloadScript',
       params,
@@ -433,7 +485,7 @@ class ScriptManager {
    * @returns {Promise<void>} - A promise that resolves when the subscription is successful.
    */
   async onMessage(callback) {
-    await this.subscribeAndHandleEvent('script.message', callback)
+    return await this.subscribeAndHandleEvent(ScriptEvent.MESSAGE, callback)
   }
 
   /**
@@ -443,7 +495,7 @@ class ScriptManager {
    * @returns {Promise<void>} - A promise that resolves when the subscription is successful.
    */
   async onRealmCreated(callback) {
-    await this.subscribeAndHandleEvent('script.realmCreated', callback)
+    return await this.subscribeAndHandleEvent(ScriptEvent.REALM_CREATED, callback)
   }
 
   /**
@@ -453,19 +505,18 @@ class ScriptManager {
    * @returns {Promise<void>} - A promise that resolves when the subscription is successful.
    */
   async onRealmDestroyed(callback) {
-    await this.subscribeAndHandleEvent('script.realmDestroyed', callback)
+    return await this.subscribeAndHandleEvent(ScriptEvent.REALM_DESTROYED, callback)
   }
 
   async subscribeAndHandleEvent(eventType, callback) {
-    if (this.browsingContextIds != null) {
-      await this.bidi.subscribe(eventType, this.browsingContextIds)
+    if (this._browsingContextIds != null) {
+      await this.bidi.subscribe(eventType, this._browsingContextIds)
     } else {
       await this.bidi.subscribe(eventType)
     }
-    await this._on(callback)
-  }
 
-  async _on(callback) {
+    let id = this.addCallback(eventType, callback)
+
     this.ws = await this.bidi.socket
     this.ws.on('message', (event) => {
       const { params } = JSON.parse(Buffer.from(event.toString()))
@@ -482,9 +533,28 @@ class ScriptManager {
             response = params.realm
           }
         }
-        callback(response)
+        this.invokeCallbacks(eventType, response)
       }
     })
+
+    return id
+  }
+
+  async close() {
+    if (
+      this._browsingContextIds !== null &&
+      this._browsingContextIds !== undefined &&
+      this._browsingContextIds.length > 0
+    ) {
+      await this.bidi.unsubscribe(
+        'script.message',
+        'script.realmCreated',
+        'script.realmDestroyed',
+        this._browsingContextIds,
+      )
+    } else {
+      await this.bidi.unsubscribe('script.message', 'script.realmCreated', 'script.realmDestroyed')
+    }
   }
 }
 

package/chrome.js

@@ -118,6 +118,8 @@
  * [PATH]: http://en.wikipedia.org/wiki/PATH_%28variable%29
  * [android]: https://chromedriver.chromium.org/getting-started/getting-started---android
  * [webview]: https://developer.chrome.com/multidevice/webview/overview
+ *
+ * @module selenium-webdriver/chrome
  */
 
 'use strict'

package/chromium.js

@@ -66,6 +66,8 @@
  *     // configure browser options ...
  *
  *     let driver = chrome.Driver.createSession(options, service);
+ *
+ *     @module selenium-webdriver/chromium
  */
 
 'use strict'

package/edge.js

@@ -73,6 +73,8 @@
  * {@link ./builder.Builder selenium-webdriver.Builder}.
  *
  * [WebDriver (Chromium)]: https://docs.microsoft.com/en-us/microsoft-edge/webdriver-chromium
+ *
+ * @module selenium-webdriver/edge
  */
 
 'use strict'

package/firefox.js

@@ -103,6 +103,8 @@
  *
  * [geckodriver release]: https://github.com/mozilla/geckodriver/releases/
  * [PATH]: http://en.wikipedia.org/wiki/PATH_%28variable%29
+ *
+ * @module selenium-webdriver/firefox
  */
 
 'use strict'
@@ -244,6 +246,9 @@ class Options extends Capabilities {
   constructor(other) {
     super(other)
     this.setBrowserName(Browser.FIREFOX)
+    // Firefox 129 onwards the CDP protocol will not be enabled by default. Setting this preference will enable it.
+    // https://fxdx.dev/deprecating-cdp-support-in-firefox-embracing-the-future-with-webdriver-bidi/.
+    this.setPreference('remote.active-protocols', 3)
   }
 
   /**

package/ie.js

@@ -23,6 +23,8 @@
  * [PATH](http://en.wikipedia.org/wiki/PATH_%28variable%29). You must also apply
  * the system configuration outlined on the Selenium project
  * [wiki](https://github.com/SeleniumHQ/selenium/wiki/InternetExplorerDriver)
+ *
+ * @module selenium-webdriver/ie
  */
 
 'use strict'

package/lib/atoms/bidi-mutation-listener.js

@@ -0,0 +1,55 @@
+// 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.
+
+function observeMutations(channel) {
+  const observer = new MutationObserver((mutations) => {
+    for (const mutation of mutations) {
+      switch (mutation.type) {
+        case 'attributes':
+          // Don't report our own attribute has changed.
+          if (mutation.attributeName === 'data-__webdriver_id') {
+            break
+          }
+          const curr = mutation.target.getAttribute(mutation.attributeName)
+          let id = mutation.target.dataset.__webdriver_id
+          if (!id) {
+            id = Math.random().toString(36).substring(2) + Date.now().toString(36)
+            mutation.target.dataset.__webdriver_id = id
+          }
+          const json = JSON.stringify({
+            target: id,
+            name: mutation.attributeName,
+            value: curr,
+            oldValue: mutation.oldValue,
+          })
+          channel(json)
+          break
+        default:
+          break
+      }
+    }
+  })
+
+  observer.observe(document, {
+    attributes: true,
+    attributeOldValue: true,
+    characterData: true,
+    characterDataOldValue: true,
+    childList: true,
+    subtree: true,
+  })
+}

package/lib/pinnedScript.js

@@ -20,6 +20,7 @@ const crypto = require('node:crypto')
 class PinnedScript {
   constructor(script) {
     this.scriptSource_ = script
+    // eslint-disable-next-line
     this.scriptHandle_ = crypto.randomUUID().replace(/-/gi, '')
   }
 

package/lib/script.js

@@ -0,0 +1,126 @@
+// 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 logInspector = require('../bidi/logInspector')
+const scriptManager = require('../bidi//scriptManager')
+const { LocalValue, ChannelValue } = require('../bidi/protocolValue')
+const fs = require('node:fs')
+const path = require('node:path')
+const by = require('./by')
+
+class Script {
+  #driver
+  #logInspector
+  #script
+
+  constructor(driver) {
+    this.#driver = driver
+  }
+
+  // This should be done in the constructor.
+  // But since it needs to call async methods we cannot do that in the constructor.
+  // We can have a separate async method that initialises the Script instance.
+  // However, that pattern does not allow chaining the methods as we would like the user to use it.
+  // Since it involves awaiting to get the instance and then another await to call the method.
+  // Using this allows the user to do this "await driver.script().addJavaScriptErrorHandler(callback)"
+  async #init() {
+    if (this.#logInspector !== undefined) {
+      return
+    }
+    this.#logInspector = await logInspector(this.#driver)
+  }
+
+  async #initScript() {
+    if (this.#script !== undefined) {
+      return
+    }
+    this.#script = await scriptManager([], this.#driver)
+  }
+
+  async addJavaScriptErrorHandler(callback) {
+    await this.#init()
+    return await this.#logInspector.onJavascriptException(callback)
+  }
+
+  async removeJavaScriptErrorHandler(id) {
+    await this.#init()
+    await this.#logInspector.removeCallback(id)
+  }
+
+  async addConsoleMessageHandler(callback) {
+    await this.#init()
+    return this.#logInspector.onConsoleEntry(callback)
+  }
+
+  async removeConsoleMessageHandler(id) {
+    await this.#init()
+
+    await this.#logInspector.removeCallback(id)
+  }
+
+  async addDomMutationHandler(callback) {
+    await this.#initScript()
+
+    let argumentValues = []
+    let value = LocalValue.createChannelValue(new ChannelValue('channel_name'))
+    argumentValues.push(value)
+
+    const filePath = path.join(__dirname, 'atoms', 'bidi-mutation-listener.js')
+
+    let mutationListener = fs.readFileSync(filePath, 'utf-8').toString()
+    await this.#script.addPreloadScript(mutationListener, argumentValues)
+
+    let id = await this.#script.onMessage(async (message) => {
+      let payload = JSON.parse(message['data']['value'])
+      let elements = await this.#driver.findElements({
+        css: '*[data-__webdriver_id=' + by.escapeCss(payload['target']) + ']',
+      })
+
+      if (elements.length === 0) {
+        return
+      }
+
+      let event = {
+        element: elements[0],
+        attribute_name: payload['name'],
+        current_value: payload['value'],
+        old_value: payload['oldValue'],
+      }
+      callback(event)
+    })
+
+    return id
+  }
+
+  async removeDomMutationHandler(id) {
+    await this.#initScript()
+
+    await this.#script.removeCallback(id)
+  }
+
+  async pin(script) {
+    await this.#initScript()
+    return await this.#script.addPreloadScript(script)
+  }
+
+  async unpin(id) {
+    await this.#initScript()
+    await this.#script.removePreloadScript(id)
+  }
+}
+
+module.exports = Script

package/lib/webdriver.js

@@ -43,6 +43,7 @@ const { isObject } = require('./util')
 const BIDI = require('../bidi')
 const { PinnedScript } = require('./pinnedScript')
 const JSZip = require('jszip')
+const Script = require('./script')
 
 // Capability names that are defined in the W3C spec.
 const W3C_CAPABILITY_NAMES = new Set([
@@ -654,6 +655,7 @@ function filterNonW3CCaps(capabilities) {
  * @implements {IWebDriver}
  */
 class WebDriver {
+  #script = undefined
   /**
    * @param {!(./session.Session|IThenable<!./session.Session>)} session Either
    *     a known session or a promise that will be resolved to a session.
@@ -1104,6 +1106,16 @@ class WebDriver {
     return new TargetLocator(this)
   }
 
+  script() {
+    // The Script calls the LogInspector which maintains state of the callbacks.
+    // Returning a new instance of the same driver will not work while removing callbacks.
+    if (this.#script === undefined) {
+      this.#script = new Script(this)
+    }
+
+    return this.#script
+  }
+
   validatePrintPageParams(keys, object) {
     let page = {}
     let margin = {}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "selenium-webdriver",
-  "version": "4.21.0",
+  "version": "4.23.0",
   "description": "The official WebDriver JavaScript bindings from the Selenium project",
   "license": "Apache-2.0",
   "keywords": [
@@ -23,33 +23,37 @@
     "node": ">= 14.21.0"
   },
   "dependencies": {
+    "@bazel/runfiles": "^5.8.1",
     "jszip": "^3.10.1",
     "tmp": "^0.2.3",
-    "ws": ">=8.16.0"
+    "ws": "^8.17.1"
   },
   "devDependencies": {
-    "@bazel/runfiles": "^5.8.1",
-    "@eslint/js": "^9.1.1",
-    "eslint": "^9.1.0",
+    "@eslint/js": "^9.5.0",
+    "clean-jsdoc-theme": "^4.3.0",
+    "eslint": "^9.5.0",
     "eslint-config-prettier": "^9.1.0",
     "eslint-plugin-mocha": "^10.4.3",
-    "eslint-plugin-n": "^17.2.1",
+    "eslint-plugin-n": "^17.9.0",
     "eslint-plugin-no-only-tests": "^3.1.0",
     "eslint-plugin-prettier": "^5.1.3",
     "express": "^4.19.2",
-    "globals": "^15.0.0",
-    "mocha": "^10.4.0",
+    "globals": "^15.6.0",
+    "has-flag": "^4.0.0",
+    "jsdoc": "^4.0.3",
+    "mocha": "^10.5.1",
     "mocha-junit-reporter": "^2.2.1",
-    "multer": "^1.4.5-lts.1",
-    "prettier": "^3.2.5",
+    "multer": "1.4.5-lts.1",
+    "prettier": "^3.3.2",
     "serve-index": "^1.9.1",
-    "sinon": "^17.0.1"
+    "sinon": "^17.0.1",
+    "supports-color": "^9.4.0"
   },
   "scripts": {
     "lint": "eslint .",
     "lint:fix": "eslint . --fix",
-    "test": "npm run lint && mocha -t 600000 --recursive test",
-    "test-jasmine": "bazel test //javascript/node/selenium-webdriver:tests"
+    "test": "bazel test //javascript/node/selenium-webdriver/...",
+    "generate-docs": "jsdoc --configure jsdoc_conf.json --verbose"
   },
   "mocha": {
     "recursive": true,

package/safari.js

@@ -17,6 +17,8 @@
 
 /**
  * @fileoverview Defines a WebDriver client for Safari.
+ *
+ * @module selenium-webdriver/safari
  */
 
 'use strict'

package/testing/index.js

@@ -32,7 +32,10 @@
 
 'use strict'
 
+const fs = require('node:fs')
+const path = require('node:path')
 const { isatty } = require('node:tty')
+const { runfiles } = require('@bazel/runfiles')
 const chrome = require('../chrome')
 const edge = require('../edge')
 const firefox = require('../firefox')
@@ -288,6 +291,37 @@ class Environment {
     const urlOrServer = URL_MAP.get(this)
 
     const builder = new Builder()
+
+    // Sniff the environment variables for paths to use for the common browsers
+    // Chrome
+    if ('SE_CHROMEDRIVER' in process.env) {
+      const found = locate(process.env.SE_CHROMEDRIVER)
+      const service = new chrome.ServiceBuilder(found)
+      builder.setChromeService(service)
+    }
+    if ('SE_CHROME' in process.env) {
+      const binary = locate(process.env.SE_CHROME)
+      const options = new chrome.Options()
+      options.setChromeBinaryPath(binary)
+      options.setAcceptInsecureCerts(true)
+      options.addArguments('disable-infobars', 'disable-breakpad', 'disable-dev-shm-usage', 'no-sandbox')
+      builder.setChromeOptions(options)
+    }
+    // Edge
+    // Firefox
+    if ('SE_GECKODRIVER' in process.env) {
+      const found = locate(process.env.SE_GECKODRIVER)
+      const service = new firefox.ServiceBuilder(found)
+      builder.setFirefoxService(service)
+    }
+    if ('SE_FIREFOX' in process.env) {
+      const binary = locate(process.env.SE_FIREFOX)
+      const options = new firefox.Options()
+      options.enableBidi()
+      options.setBinary(binary)
+      builder.setFirefoxOptions(options)
+    }
+
     builder.disableEnvironmentOverrides()
 
     const realBuild = builder.build
@@ -505,6 +539,59 @@ function getTestHook(name) {
   return fn
 }
 
+function locate(fileLike) {
+  if (fs.existsSync(fileLike)) {
+    return fileLike
+  }
+
+  try {
+    return runfiles.resolve(fileLike)
+  } catch {
+    // Fall through
+  }
+
+  // Is the item in the workspace?
+  try {
+    return runfiles.resolveWorkspaceRelative(fileLike)
+  } catch {
+    // Fall through
+  }
+
+  // Find the repo mapping file
+  let repoMappingFile
+  try {
+    repoMappingFile = runfiles.resolve('_repo_mapping')
+  } catch {
+    throw new Error('Unable to locate (no repo mapping file): ' + fileLike)
+  }
+  const lines = fs.readFileSync(repoMappingFile, { encoding: 'utf8' }).split('\n')
+
+  // Build a map of "repo we declared we need" to "path"
+  const mapping = {}
+  for (const line of lines) {
+    if (line.startsWith(',')) {
+      const parts = line.split(',', 3)
+      mapping[parts[1]] = parts[2]
+    }
+  }
+
+  // Get the first segment of the path
+  const pathSegments = fileLike.split('/')
+  if (!pathSegments.length) {
+    throw new Error('Unable to locate ' + fileLike)
+  }
+
+  pathSegments[0] = mapping[pathSegments[0]] ? mapping[pathSegments[0]] : '_main'
+
+  try {
+    return runfiles.resolve(path.join(...pathSegments))
+  } catch {
+    // Fall through
+  }
+
+  throw new Error('Unable to find ' + fileLike)
+}
+
 // PUBLIC API
 
 module.exports = {