selenium-webdriver 4.21.0 → 4.22.0

package/CHANGES.md

@@ -1,3 +1,11 @@
+## 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/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)
         }

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/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) => {
@@ -81,27 +139,37 @@ class LogInspector {
 
         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) => {
@@ -118,29 +186,26 @@ 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()))
@@ -153,24 +218,31 @@ class LogInspector {
           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) => {
@@ -191,7 +263,16 @@ 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
       }
 
@@ -209,12 +290,12 @@ class LogInspector {
 
         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
       }
 
@@ -229,14 +310,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
   }
 
   /**

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/script.js

@@ -0,0 +1,63 @@
+// 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')
+
+class Script {
+  #driver
+  #logInspector
+
+  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 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)
+  }
+}
+
+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.22.0",
   "description": "The official WebDriver JavaScript bindings from the Selenium project",
   "license": "Apache-2.0",
   "keywords": [
@@ -30,6 +30,7 @@
   "devDependencies": {
     "@bazel/runfiles": "^5.8.1",
     "@eslint/js": "^9.1.1",
+    "clean-jsdoc-theme": "^4.3.0",
     "eslint": "^9.1.0",
     "eslint-config-prettier": "^9.1.0",
     "eslint-plugin-mocha": "^10.4.3",
@@ -38,6 +39,7 @@
     "eslint-plugin-prettier": "^5.1.3",
     "express": "^4.19.2",
     "globals": "^15.0.0",
+    "jsdoc": "^4.0.3",
     "mocha": "^10.4.0",
     "mocha-junit-reporter": "^2.2.1",
     "multer": "^1.4.5-lts.1",
@@ -49,7 +51,8 @@
     "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-jasmine": "bazel test //javascript/node/selenium-webdriver:tests",
+    "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'