selenium-webdriver 4.47.0 → 4.49.0

package/chromium.js

@@ -506,7 +506,7 @@ class Options extends Capabilities {
    * __Example 1: Using a Pre-configured Device__
    *
    *     let options = new chrome.Options().setMobileEmulation(
-   *         {deviceName: 'Google Nexus 5'});
+   *         {deviceName: 'Pixel 10'});
    *
    *     let driver = chrome.Driver.createSession(options);
    *

package/common/seleniumManager.js

@@ -21,7 +21,7 @@
  *  Wrapper for getting information from the Selenium Manager binaries
  */
 
-const { platform } = require('node:process')
+const { platform, arch } = require('node:process')
 const path = require('node:path')
 const fs = require('node:fs')
 const spawnSync = require('node:child_process').spawnSync
@@ -39,7 +39,7 @@ function getBinary() {
     darwin: 'macos',
     win32: 'windows',
     cygwin: 'windows',
-    linux: 'linux',
+    linux: arch === 'arm64' ? 'linux-arm64' : 'linux-x86_64',
   }[platform]
 
   const file = directory === 'windows' ? 'selenium-manager.exe' : 'selenium-manager'

package/example/chrome_mobile_emulation.js

@@ -30,7 +30,7 @@ const { Options } = require('../chrome')
   try {
     driver = await new Builder()
       .forBrowser('chrome')
-      .setChromeOptions(new Options().setMobileEmulation({ deviceName: 'Nexus 5X' }))
+      .setChromeOptions(new Options().setMobileEmulation({ deviceName: 'Pixel 10' }))
       .build()
     await driver.get('http://www.google.com/ncr')
     await driver.findElement(By.name('q')).sendKeys('webdriver', Key.RETURN)

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/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.47.0",
+  "version": "4.49.0",
   "description": "The official WebDriver JavaScript bindings from the Selenium project",
   "license": "Apache-2.0",
   "keywords": [
@@ -33,19 +33,19 @@
     "cddl": "^0.21.1",
     "cddl2ts": "^0.10.1",
     "clean-jsdoc-theme": "^4.3.3",
-    "eslint": "^10.8.1",
+    "eslint": "^10.10.0",
     "eslint-config-prettier": "^10.1.8",
     "eslint-plugin-mocha": "^11.3.0",
     "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.9.0",
+    "globals": "^17.12.0",
     "has-flag": "^5.0.1",
     "jsdoc": "^4.0.5",
     "mocha": "^11.8.0",
     "mocha-junit-reporter": "^2.2.1",
-    "multer": "^2.2.0",
+    "multer": "^2.3.0",
     "prettier": "^3.9.6",
     "serve-index": "^1.9.2",
     "sinon": "^22.1.0",