selenium-webdriver 4.46.0 → 4.48.0

package/firefox.js

@@ -317,6 +317,7 @@ class Options extends Capabilities {
    *
    * @param {...string} paths The paths to the extension XPI files to install.
    * @return {!Options} A self reference.
+   * @deprecated Use {@link Driver#installAddon} instead.
    */
   addExtensions(...paths) {
     this.profile_().addExtensions(paths)

package/index.js

@@ -478,6 +478,14 @@ class Builder {
     return this.firefoxOptions_
   }
 
+  /**
+   * @return {firefox.ServiceBuilder} the Firefox service currently configured
+   *     for this instance.
+   */
+  getFirefoxService() {
+    return this.firefoxService_
+  }
+
   /**
    * Sets the {@link firefox.ServiceBuilder} to use to manage the geckodriver
    * child process when creating Firefox sessions locally.
@@ -650,6 +658,11 @@ class Builder {
 
     if (url) {
       this.log_.fine('Creating session on remote server')
+
+      if (typeof url === 'string') {
+        capabilities.set('se:remoteUrl', url)
+      }
+
       let client = Promise.resolve(url).then((url) => new _http.HttpClient(url, this.agent_, this.proxy_))
       let executor = new _http.Executor(client)
 

package/lib/atoms/find-elements.js

@@ -1,4 +1,22 @@
-// GENERATED CODE - DO NOT EDIT
+// 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.
+
+// DO NOT EDIT! This file is generated by javascript/selenium-webdriver/lib/atoms/make-atoms-module.js.
+// Regenerate with: `bazel build //javascript/selenium-webdriver/lib/atoms:all`
 module.exports = (function findElements(target, root) {
     const INVALID_SELECTOR = 'invalid selector';
     const INVALID_ARGUMENT = 'invalid argument';

package/lib/atoms/get-attribute.js

@@ -1,4 +1,22 @@
-// GENERATED CODE - DO NOT EDIT
+// 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.
+
+// DO NOT EDIT! This file is generated by javascript/selenium-webdriver/lib/atoms/make-atoms-module.js.
+// Regenerate with: `bazel build //javascript/selenium-webdriver/lib/atoms:all`
 module.exports = (function (element, attribute) {
     const PROPERTY_ALIASES = {
         'class': 'className',

package/lib/atoms/is-displayed.js

@@ -1,4 +1,22 @@
-// GENERATED CODE - DO NOT EDIT
+// 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.
+
+// DO NOT EDIT! This file is generated by javascript/selenium-webdriver/lib/atoms/make-atoms-module.js.
+// Regenerate with: `bazel build //javascript/selenium-webdriver/lib/atoms:all`
 module.exports = (function isShownElement(elem, optIgnoreOpacity) {
     var tagNameDescriptor = Object.getOwnPropertyDescriptor(Element.prototype, 'tagName');
     var computedStyleCache = new Map();

package/lib/bidi_connection.js

@@ -0,0 +1,84 @@
+// 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 BiDi = require('../bidi')
+
+/**
+ * One BiDi connection per driver, kept outside the WebDriver class itself so
+ * it isn't a discoverable method on it — see
+ * docs/decisions/17670-bidi-implementation-boundaries.md. Not re-exported from
+ * the package's public entry point.
+ *
+ * Stores the in-flight promise, not the resolved connection, so a second
+ * concurrent call for the same driver awaits the same creation instead of
+ * racing its own and leaking whichever connection loses.
+ * @type {WeakMap<object, Promise<BiDi>>}
+ */
+const connections = new WeakMap()
+
+/**
+ * Returns the BiDi connection for `driver`, creating it on first access.
+ * @param {object} driver The WebDriver instance to obtain a BiDi connection for.
+ * @returns {Promise<BiDi>} A promise resolving to `driver`'s BiDi connection, shared
+ *     with any other in-flight or already-resolved call for the same driver.
+ */
+function getBidiConnection(driver) {
+  if (!connections.has(driver)) {
+    connections.set(driver, createConnection(driver))
+  }
+  return connections.get(driver)
+}
+
+/**
+ * @param {object} driver
+ * @returns {Promise<BiDi>}
+ */
+async function createConnection(driver) {
+  const caps = await driver.getCapabilities()
+  const webSocketUrl = caps['map_'].get('webSocketUrl')
+  if (!webSocketUrl) {
+    throw new Error('WebDriver instance must support BiDi protocol')
+  }
+  return new BiDi(webSocketUrl.replace('localhost', '127.0.0.1'))
+}
+
+/**
+ * Closes `driver`'s BiDi connection, if one was ever opened. A no-op
+ * otherwise — must not lazily create a connection just to close it.
+ *
+ * Callers (e.g. quit()) invoke this fire-and-forget, so it must never reject:
+ * if the original connection attempt itself had failed, `pending` is already
+ * rejected and there is nothing live to close.
+ * @param {object} driver The WebDriver instance whose BiDi connection should be closed.
+ * @returns {Promise<void>} A promise that always resolves, once any open connection
+ *     has been closed (or immediately, if none was ever opened).
+ */
+async function closeBidiConnection(driver) {
+  const pending = connections.get(driver)
+  if (pending === undefined) {
+    return
+  }
+  connections.delete(driver)
+  try {
+    const connection = await pending
+    await connection.close()
+  } catch {
+    // Nothing to close — the original connection attempt failed.
+  }
+}
+
+module.exports = { getBidiConnection, closeBidiConnection }

package/lib/logging.js

@@ -271,6 +271,9 @@ class Logger {
 
     /** @private {Set<function(!Entry)>} */
     this.handlers_ = null
+
+    /** @private {Set<string>} ids already reported via {@link #deprecate}. */
+    this.deprecated_ = new Set()
   }
 
   /** @return {string} the name of this logger. */
@@ -392,6 +395,38 @@ class Logger {
     this.log(Level.INFO, loggable)
   }
 
+  /**
+   * Logs a deprecation notice at the {@link Level.WARNING} log level, once per
+   * `id` for this logger's lifetime — a repeat call with the same `id` is a
+   * no-op, matching the once-only behavior `util.deprecate` gives by call-site
+   * identity, but keyed on a stable id instead so it survives being wrapped,
+   * rebound, or called through multiple paths.
+   *
+   * `id` is only claimed once the notice is actually loggable at this
+   * logger's effective level — under the default `Level.OFF` root level, a
+   * call here logs nothing and leaves `id` unclaimed, so a later call (once
+   * logging is enabled) still gets to report it instead of finding it already
+   * silently used up.
+   * @param {string} id a stable, non-empty identifier for this deprecation
+   *     (e.g. `'webdriver-getBidi'`), distinct from the message text so
+   *     tooling can key off it even if the wording changes later.
+   * @param {string} message the deprecation notice to log.
+   * @throws {TypeError} if `id` is empty.
+   */
+  deprecate(id, message) {
+    if (!id) {
+      throw new TypeError('Logger#deprecate() requires a non-empty id')
+    }
+    if (this.deprecated_.has(id)) {
+      return
+    }
+    if (!this.isLoggable(Level.WARNING)) {
+      return
+    }
+    this.deprecated_.add(id)
+    this.warning(`[${id}] ${message}`)
+  }
+
   /**
    * Logs a message at the {@link Level.DEBUG} log level.
    * @param {(string|function(): string)} loggable the message to log, or a

package/lib/proxy.js

@@ -77,13 +77,6 @@ PacConfig.prototype.proxyAutoconfigUrl
  */
 function ManualConfig() {}
 
-/**
- * The proxy host for FTP requests.
- *
- * @type {(string|undefined)}
- */
-ManualConfig.prototype.ftpProxy
-
 /**
  * The proxy host for HTTP requests.
  *
@@ -138,30 +131,24 @@ function direct() {
  * Manually configures the browser proxy.  The following options are
  * supported:
  *
- * - `ftp`: Proxy host to use for FTP requests
  * - `http`: Proxy host to use for HTTP requests
  * - `https`: Proxy host to use for HTTPS requests
  * - `bypass`: A list of hosts requests should directly connect to,
  *     bypassing any other proxies for that request. May be specified as a
  *     comma separated string, or a list of strings.
  *
- * Behavior is undefined for FTP, HTTP, and HTTPS requests if the
+ * Behavior is undefined for HTTP and HTTPS requests if the
  * corresponding key is omitted from the configuration options.
  *
- * @param {{ftp: (string|undefined),
- *          http: (string|undefined),
+ * @param {{http: (string|undefined),
  *          https: (string|undefined),
  *          bypass: (Array<string>|undefined)}} options Proxy
  *     configuration options.
  * @return {!ManualConfig} A new proxy configuration object.
  */
-function manual({ ftp, http, https, bypass }) {
-  if (ftp !== undefined) {
-    console.warn('ftpProxy is deprecated and will be removed in the future')
-  }
+function manual({ http, https, bypass }) {
   return {
     proxyType: Type.MANUAL,
-    ftpProxy: ftp,
     httpProxy: http,
     sslProxy: https,
     noProxy: bypass,

package/lib/webdriver.js

@@ -40,7 +40,7 @@ const cdpTargets = ['page', 'browser']
 const { Credential } = require('./virtual_authenticator')
 const webElement = require('./webelement')
 const { isObject } = require('./util')
-const BIDI = require('../bidi')
+const { getBidiConnection, closeBidiConnection } = require('./bidi_connection')
 const { PinnedScript } = require('./pinnedScript')
 const JSZip = require('jszip')
 const Script = require('./script')
@@ -691,6 +691,16 @@ class WebDriver {
     this.pinnedScripts_ = {}
   }
 
+  /**
+   * The shared logger deprecation notices (e.g. {@link WebDriver#getBidi})
+   * are emitted through — a class-level accessor since a deprecation can be
+   * reported from a static/prototype context with no driver instance at hand.
+   * @return {!./logging.Logger} the shared `selenium.webdriver.webdriver` logger.
+   */
+  static get logger() {
+    return logging.getLogger('selenium.webdriver.webdriver')
+  }
+
   /**
    * Creates a new WebDriver session.
    *
@@ -794,10 +804,9 @@ class WebDriver {
         this._cdpWsConnection.close()
       }
 
-      // Close the BiDi websocket connection
-      if (this._bidiConnection !== undefined) {
-        this._bidiConnection.close()
-      }
+      // Not awaited: the session is already torn down by this point, so
+      // closing our end of the socket doesn't need to gate quit() completing.
+      closeBidiConnection(this)
     })
   }
 
@@ -1045,6 +1054,9 @@ class WebDriver {
   async findElementInternal_(locatorFn, context) {
     let result = await locatorFn(context)
     if (Array.isArray(result)) {
+      if (result.length === 0) {
+        throw new NoSuchElementError('Cannot locate an element with provided parameters')
+      }
       result = result[0]
     }
     if (!(result instanceof WebElement)) {
@@ -1088,7 +1100,15 @@ class WebDriver {
    * @private
    */
   async findElementsInternal_(locatorFn, context) {
-    const result = await locatorFn(context)
+    let result
+    try {
+      result = await locatorFn(context)
+    } catch (ex) {
+      if (ex instanceof NoSuchElementError) {
+        return []
+      }
+      throw ex
+    }
     if (result instanceof WebElement) {
       return [result]
     }
@@ -1301,19 +1321,6 @@ class WebDriver {
     this._cdpConnection.execute('Target.getTargets')
   }
 
-  /**
-   * Initiates bidi connection using 'webSocketUrl'
-   * @returns {BIDI}
-   */
-  async getBidi() {
-    if (this._bidiConnection === undefined) {
-      const caps = await this.getCapabilities()
-      let WebSocketUrl = caps['map_'].get('webSocketUrl')
-      this._bidiConnection = new BIDI(WebSocketUrl.replace('localhost', '127.0.0.1'))
-    }
-    return this._bidiConnection
-  }
-
   /**
    * Retrieves 'webSocketDebuggerUrl' by sending a http request using debugger address
    * @param {string} debuggerAddress
@@ -1778,6 +1785,36 @@ class WebDriver {
   }
 }
 
+/**
+ * Returns the WebDriver BiDi connection for this session.
+ *
+ * @deprecated BiDi is an internal implementation detail — this accessor hands
+ * back the raw transport directly, which is no longer supported public API.
+ * Use a composed BiDi module instead, e.g. `Network.create(driver)` or
+ * `require('selenium-webdriver/bidi/network')`.
+ * @function
+ * @name WebDriver#getBidi
+ * @returns {Promise<import('../bidi')>} A promise resolving to this session's raw
+ *     BiDi connection, opened on first access and reused afterward.
+ */
+// Object.defineProperty, not `WebDriver.prototype.getBidi = function () {...}`:
+// a plain assignment creates an enumerable property, but a method declared in
+// the class body (like every other method here) is non-enumerable — so BiDi
+// would become more discoverable off the driver than it was before.
+Object.defineProperty(WebDriver.prototype, 'getBidi', {
+  value: function () {
+    WebDriver.logger.deprecate(
+      'webdriver-getBidi',
+      'WebDriver#getBidi() is deprecated. Use a composed BiDi module instead, e.g. Network.create(driver) or ' +
+        "require('selenium-webdriver/bidi/network').",
+    )
+    return getBidiConnection(this)
+  },
+  writable: true,
+  enumerable: false,
+  configurable: true,
+})
+
 /**
  * Interface for navigating back and forth in the browser history.
  *

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "selenium-webdriver",
-  "version": "4.46.0",
+  "version": "4.48.0",
   "description": "The official WebDriver JavaScript bindings from the Selenium project",
   "license": "Apache-2.0",
   "keywords": [
@@ -20,35 +20,35 @@
     "url": "https://github.com/SeleniumHQ/selenium.git"
   },
   "engines": {
-    "node": ">= 20.0.0"
+    "node": ">= 22.0.0"
   },
   "dependencies": {
     "@bazel/runfiles": "^6.5.0",
     "jszip": "^3.10.1",
     "tmp": "^0.2.7",
-    "ws": "^8.21.0"
+    "ws": "^8.21.3"
   },
   "devDependencies": {
     "@eslint/js": "^10.0.1",
-    "cddl": "^0.21.0",
-    "cddl2ts": "^0.10.0",
+    "cddl": "^0.21.1",
+    "cddl2ts": "^0.10.1",
     "clean-jsdoc-theme": "^4.3.3",
-    "eslint": "^10.7.0",
+    "eslint": "^10.8.1",
     "eslint-config-prettier": "^10.1.8",
     "eslint-plugin-mocha": "^11.3.0",
-    "eslint-plugin-n": "^18.2.1",
+    "eslint-plugin-n": "^18.3.0",
     "eslint-plugin-no-only-tests": "^3.4.0",
     "eslint-plugin-prettier": "^5.5.6",
     "express": "^5.2.1",
-    "globals": "^17.7.0",
+    "globals": "^17.9.0",
     "has-flag": "^5.0.1",
     "jsdoc": "^4.0.5",
-    "mocha": "^11.7.6",
+    "mocha": "^11.8.0",
     "mocha-junit-reporter": "^2.2.1",
     "multer": "^2.2.0",
-    "prettier": "^3.9.5",
+    "prettier": "^3.9.6",
     "serve-index": "^1.9.2",
-    "sinon": "^22.0.0",
+    "sinon": "^22.1.0",
     "supports-color": "^10.2.2"
   },
   "scripts": {