selenium-webdriver 4.43.0 → 4.45.0

package/CHANGES.md

@@ -1,3 +1,24 @@
+## 4.45.0
+
+- Support CDP versions: v147, v148, v149
+- update vulnerable dependency with a range (#17466)
+- update dev dependencies (#17479)
+- update eslint to v10 with fixes (#17482)
+- Use the typescript atom for get attribute (#17526)
+- Move JS bindings to use typescript atoms for isDisplayed and Find-Element (#17547)
+- trim agent formatting guidance (#17617)
+- [build] Automated Browser Version Update (#17609)
+- Add Javascript/Typescript CDDL code generator for WebDriver BiDi (#17574)
+- Expose BiDi CDDL ast and model as shared artifacts (#17657)
+
+## 4.44.0
+
+- Support CDP versions: v146, v147, v148
+- [Agents] Update agents to make sure do linting. (#17366)
+- Standardize README files across bindings (#17245)
+- Fix MaxListenersExceededWarning in BiDi send (#17423)
+- [JavaScript] Move 'isDisplayed' atom to be typescript (#17316)
+
 ## 4.43.0
 
 - Support CDP versions: v145, v146, v147

package/README.md

@@ -1,230 +1,102 @@
 # selenium-webdriver
 
-Selenium is a browser automation library. Most often used for testing
-web-applications, Selenium may be used for any task that requires automating
-interaction with the browser.
+JavaScript language bindings for [Selenium WebDriver](https://www.selenium.dev).
+Selenium automates browsers for testing and web-based task automation.
 
-## Installation
-
-Selenium may be installed via npm with
-
-    npm install selenium-webdriver
+Requires Node.js >= 20.
 
-You will need to download additional components to work with each of the major
-browsers. The drivers for Chrome, Firefox, and Microsoft's IE and Edge web
-browsers are all standalone executables that should be placed on your system
-[PATH]. Apple's safaridriver (v10 and above) can be found at the
-following path – /usr/bin/safaridriver. To enable automation on safari,
-you need to run command `safaridriver --enable`.
-
-| Browser           | Component                        |
-| :---------------- | :------------------------------- |
-| Chrome            | [chromedriver(.exe)][chrome]     |
-| Internet Explorer | [IEDriverServer.exe][release]    |
-| Edge              | [MicrosoftWebDriver.msi][edge]   |
-| Firefox           | [geckodriver(.exe)][geckodriver] |
-| Opera             | [operadriver(.exe)][operadriver] |
-| Safari            | [safaridriver]                   |
+## Installation
 
-## Usage
+```bash
+npm install selenium-webdriver
+```
 
-The sample below and others are included in the `example` directory. You may
-also find the tests for selenium-webdriver informative.
+## Quick Start
 
 ```javascript
-const { Builder, Browser, By, Key, until } = require('selenium-webdriver')
+const { Builder, Browser } = require('selenium-webdriver')
 
 ;(async function example() {
-  let driver = await new Builder().forBrowser(Browser.FIREFOX).build()
+  let driver = await new Builder().forBrowser(Browser.CHROME).build()
   try {
-    await driver.get('https://www.google.com/ncr')
-    await driver.findElement(By.name('q')).sendKeys('webdriver', Key.RETURN)
-    await driver.wait(until.titleIs('webdriver - Google Search'), 1000)
+    await driver.get('https://www.selenium.dev')
+    console.log(await driver.getTitle())
   } finally {
     await driver.quit()
   }
 })()
 ```
 
-### Using the Builder API
+Selenium Manager automatically handles browser driver installation — no manual driver setup required.
+
+## Configuring the Builder
 
-The `Builder` class is your one-stop shop for configuring new WebDriver
-instances. Rather than clutter your code with branches for the various browsers,
-the builder lets you set all options in one flow. When you call
-`Builder#build()`, all options irrelevant to the selected browser are dropped:
+The `Builder` sets default options for all browsers in a single chain; options
+for non-selected browsers are dropped at `build()` time. The target browser can
+be swapped at runtime via the `SELENIUM_BROWSER` environment variable.
 
 ```javascript
-const webdriver = require('selenium-webdriver')
+const { Builder, Browser } = require('selenium-webdriver')
 const chrome = require('selenium-webdriver/chrome')
 const firefox = require('selenium-webdriver/firefox')
 
-let driver = new webdriver.Builder()
-  .forBrowser(webdriver.Browser.FIREFOX)
-  .setChromeOptions(/* ... */)
-  .setFirefoxOptions(/* ... */)
+let driver = new Builder()
+  .forBrowser(Browser.FIREFOX)
+  .setChromeOptions(new chrome.Options())
+  .setFirefoxOptions(new firefox.Options())
   .build()
 ```
 
-Why would you want to configure options irrelevant to the target browser? The
-`Builder`'s API defines your _default_ configuration. You can change the target
-browser at runtime through the `SELENIUM_BROWSER` environment variable. For
-example, the `example/google_search.js` script is configured to run against
-Firefox. You can run the example against other browsers just by changing the
-runtime environment
-
-    # cd node_modules/selenium-webdriver
-    node example/google_search
-    SELENIUM_BROWSER=chrome node example/google_search
-    SELENIUM_BROWSER=safari node example/google_search
-
-### The Standalone Selenium Server
-
-The standalone Selenium Server acts as a proxy between your script and the
-browser-specific drivers. The server may be used when running locally, but it's
-not recommend as it introduces an extra hop for each request and will slow
-things down. The server is required, however, to use a browser on a remote host
-(most browser drivers, like the IEDriverServer, do not accept remote
-connections).
+## Running Against a Remote Server
 
-To use the Selenium Server, you will need to install the
-[JDK](http://www.oracle.com/technetwork/java/javase/downloads/index.html) and
-download the latest server from [Selenium][release]. Once downloaded, run the
-server with
-
-    java -jar selenium-server-4.27.0.jar standalone
-
-You may configure your tests to run against a remote server through the Builder
-API:
+To run scripts against a [Selenium Grid](https://www.selenium.dev/documentation/grid/)
+or standalone server, point the Builder at the server URL, or set
+`SELENIUM_REMOTE_URL`:
 
 ```javascript
-let driver = new webdriver.Builder()
-  .forBrowser(webdriver.Browser.FIREFOX)
-  .usingServer('http://localhost:4444/wd/hub')
-  .build()
+let driver = new Builder().forBrowser(Browser.CHROME).usingServer('http://localhost:4444').build()
 ```
 
-Or change the Builder's configuration at runtime with the `SELENIUM_REMOTE_URL`
-environment variable:
+```bash
+SELENIUM_REMOTE_URL="http://localhost:4444" node script.js
+```
 
-    SELENIUM_REMOTE_URL="http://localhost:4444/wd/hub" node script.js
+## Node Support Policy
 
-You can experiment with these options using the `example/google_search.js`
-script provided with `selenium-webdriver`.
+Each `selenium-webdriver` release targets the latest _semver-minor_ of Node's
+[LTS and Current releases](https://github.com/nodejs/release#release-schedule).
+
+| Level         | Guarantee                                                                 |
+| :------------ | :------------------------------------------------------------------------ |
+| _supported_   | API compatible without runtime flags; bugs investigated and fixed.        |
+| _best effort_ | Bugs investigated as time permits; API compatibility only where required. |
+| _unsupported_ | Bug reports closed as will-not-fix; API compatibility not guaranteed.     |
+
+Versions older than the active LTS, unstable release branches (e.g. `v.Next`),
+and _semver-major_ Node releases outside the LTS / Current pair are _unsupported_.
 
 ## Documentation
 
-API documentation is available online from the [Selenium project][api].
-Additional resources include
+- [Getting Started](https://www.selenium.dev/documentation/webdriver/getting_started/)
+- [JavaScript API Docs](https://www.selenium.dev/selenium/docs/api/javascript/)
+- [Selenium Manager](https://www.selenium.dev/documentation/selenium_manager/)
+- [Selenium Grid](https://www.selenium.dev/documentation/grid/)
 
-- the #selenium channel on Libera IRC
-- the [selenium-users@googlegroups.com][users] list
-- [SeleniumHQ](https://selenium.dev/documentation/) documentation
+## Support
+
+- [Selenium Chat](https://www.selenium.dev/support/#ChatRoom)
+- [GitHub Issues](https://github.com/SeleniumHQ/selenium/issues)
 
 ## Contributing
 
-Contributions are accepted either through [GitHub][gh] pull requests or patches
-via the [Selenium issue tracker][issues].
+Contributions are welcome via [GitHub](https://github.com/SeleniumHQ/selenium/) pull requests.
+See the [source code](https://github.com/SeleniumHQ/selenium/tree/trunk/javascript/selenium-webdriver) for this binding.
 
-## Node Support Policy
+## Links
 
-Each version of selenium-webdriver will support the latest _semver-minor_
-version of the [LTS] and stable Node releases. All _semver-major_ &
-_semver-minor_ versions between the LTS and stable release will have "best
-effort" support. Following a Selenium release, any _semver-minor_ Node releases
-will also have "best effort" support. Releases older than the latest LTS,
-_semver-major_ releases, and all unstable release branches (e.g. "v.Next")
-are considered strictly unsupported.
-
-For example, suppose the current LTS and stable releases are v22.13.0 and
-v23.6.0,
-respectively. Then a Selenium release would have the following support levels:
-
-|  Version   |    Support    |
-| :--------: | :-----------: |
-| <= 16.20.2 | _unsupported_ |
-|  16.20.2   |   supported   |
-|   18.8.0   |   supported   |
-| >= 22.13.0 |  best effort  |
-|   v.Next   | _unsupported_ |
-
-### Support Level Definitions
-
-- _supported:_ A selenium-webdriver release will be API compatible with the
-  platform API, without the use of runtime flags.
-
-- _best effort:_ Bugs will be investigated as time permits. API compatibility is
-  only guaranteed where required by a _supported_ release. This effectively
-  means the adoption of new JS features, such as ES2015 modules, will depend
-  on what is supported in Node's LTS.
-
-- _unsupported:_ Bug submissions will be closed as will-not-fix and API
-  compatibility is not guaranteed.
-
-### Projected Support Schedule
-
-If Node releases a new [LTS] each October and a new major version every 6
-months, the support window for selenium-webdriver will be roughly:
-
-| Release |     Status      | END-OF-LIFE |
-| :-----: | :-------------: | :---------: |
-|  v18.x  | Maintenance LTS | 2025-04-30  |
-|  v19.x  |   End-of-Life   | 2023-06-01  |
-|  v20.x  | Maintenance LTS | 2026-04-30  |
-|  v21.x  |   End-of-Life   | 2024-06-01  |
-|  V22.x  |   Active LTS    | 2027-04-30  |
-|  V23.x  |     Current     | 2025-06-01  |
-
-## Issues
-
-Please report any issues using the [Selenium issue tracker][issues]. When using
-the issue tracker
-
-- **Do** include a detailed description of the problem.
-- **Do** include a link to a [gist](http://gist.github.com/) with any
-  interesting stack traces/logs (you may also attach these directly to the bug
-  report).
-- **Do** include a [reduced test case][reduction]. Reporting "unable to find
-  element on the page" is _not_ a valid report - there's nothing for us to
-  look into. Expect your bug report to be closed if you do not provide enough
-  information for us to investigate.
-- **Do not** use the issue tracker to submit basic help requests. All help
-  inquiries should be directed to the [user forum][users] or #selenium IRC
-  channel.
-- **Do not** post empty "I see this too" or "Any updates?" comments. These
-  provide no additional information and clutter the log.
-- **Do not** report regressions on closed bugs as they are not actively
-  monitored for updates (especially bugs that are >6 months old). Please open a
-  new issue and reference the original bug in your report.
+- [npm](https://www.npmjs.com/package/selenium-webdriver)
+- [Documentation](https://www.selenium.dev/documentation/?tab=javascript)
 
 ## License
 
-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.
-
-[LTS]: https://github.com/nodejs/LTS
-[PATH]: http://en.wikipedia.org/wiki/PATH_%28variable%29
-[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
-[edge]: http://go.microsoft.com/fwlink/?LinkId=619687
-[geckodriver]: https://github.com/mozilla/geckodriver/releases/
-[reduction]: http://www.webkit.org/quality/reduction.html
-[release]: https://www.selenium.dev/downloads/
-[users]: https://groups.google.com/forum/#!forum/selenium-users
-[safaridriver]: https://developer.apple.com/library/prerelease/content/releasenotes/General/WhatsNewInSafari/Articles/Safari_10_0.html#//apple_ref/doc/uid/TP40014305-CH11-DontLinkElementID_28
-[operadriver]: https://github.com/operasoftware/operachromiumdriver/releases
+Licensed under the [Apache License 2.0](https://www.apache.org/licenses/LICENSE-2.0).

package/bidi/browsingContextInspector.js

@@ -124,7 +124,7 @@ class BrowsingContextInspector {
     this.ws.on('message', (event) => {
       const { params } = JSON.parse(Buffer.from(event.toString()))
       if (params) {
-        let response = null
+        let response
         if ('navigation' in params) {
           response = new NavigationInfo(params.context, params.navigation, params.timestamp, params.url)
         } else if ('accepted' in params) {

package/bidi/generated/bluetooth.d.ts

@@ -0,0 +1,223 @@
+export type BluetoothBluetoothUuid = string;
+export interface BluetoothBluetoothManufacturerData {
+    key: number;
+    data: string;
+}
+export interface BluetoothCharacteristicProperties {
+    broadcast?: boolean;
+    read?: boolean;
+    writeWithoutResponse?: boolean;
+    write?: boolean;
+    notify?: boolean;
+    indicate?: boolean;
+    authenticatedSignedWrites?: boolean;
+    extendedProperties?: boolean;
+}
+export type BluetoothRequestDevice = string;
+export interface BluetoothRequestDeviceInfo {
+    id: BluetoothRequestDevice;
+    name: string | null;
+}
+export type BluetoothRequestDevicePrompt = string;
+export interface BluetoothScanRecord {
+    name?: string;
+    uuids?: BluetoothBluetoothUuid[];
+    appearance?: Number;
+    manufacturerData?: BluetoothBluetoothManufacturerData[];
+}
+export type BluetoothCommand = BluetoothHandleRequestDevicePrompt | BluetoothSimulateAdapter | BluetoothDisableSimulation | BluetoothSimulatePreconnectedPeripheral | BluetoothSimulateAdvertisement | BluetoothSimulateGattConnectionResponse | BluetoothSimulateGattDisconnection | BluetoothSimulateService | BluetoothSimulateCharacteristic | BluetoothSimulateCharacteristicResponse | BluetoothSimulateDescriptor | BluetoothSimulateDescriptorResponse;
+export interface BluetoothHandleRequestDevicePrompt {
+    method: "bluetooth.handleRequestDevicePrompt";
+    params: BluetoothHandleRequestDevicePromptParameters;
+}
+export type BluetoothHandleRequestDevicePromptParameters = (BluetoothHandleRequestDevicePromptAcceptParameters | BluetoothHandleRequestDevicePromptCancelParameters) & {
+    context: string;
+    prompt: BluetoothRequestDevicePrompt;
+};
+export interface BluetoothHandleRequestDevicePromptAcceptParameters {
+    accept: true;
+    device: BluetoothRequestDevice;
+}
+export interface BluetoothHandleRequestDevicePromptCancelParameters {
+    accept: false;
+}
+export interface BluetoothSimulateAdapter {
+    method: "bluetooth.simulateAdapter";
+    params: BluetoothSimulateAdapterParameters;
+}
+export interface BluetoothSimulateAdapterParameters {
+    context: string;
+    leSupported?: boolean;
+    state: "absent" | "powered-off" | "powered-on";
+}
+export interface BluetoothDisableSimulation {
+    method: "bluetooth.disableSimulation";
+    params: BluetoothDisableSimulationParameters;
+}
+export interface BluetoothDisableSimulationParameters {
+    context: string;
+}
+export interface BluetoothSimulatePreconnectedPeripheral {
+    method: "bluetooth.simulatePreconnectedPeripheral";
+    params: BluetoothSimulatePreconnectedPeripheralParameters;
+}
+export interface BluetoothSimulatePreconnectedPeripheralParameters {
+    context: string;
+    address: string;
+    name: string;
+    manufacturerData: BluetoothBluetoothManufacturerData[];
+    knownServiceUuids: BluetoothBluetoothUuid[];
+}
+export interface BluetoothSimulateAdvertisement {
+    method: "bluetooth.simulateAdvertisement";
+    params: BluetoothSimulateAdvertisementParameters;
+}
+export interface BluetoothSimulateAdvertisementParameters {
+    context: string;
+    scanEntry: BluetoothSimulateAdvertisementScanEntryParameters;
+}
+export interface BluetoothSimulateAdvertisementScanEntryParameters {
+    deviceAddress: string;
+    rssi: Number;
+    scanRecord: BluetoothScanRecord;
+}
+export interface BluetoothSimulateGattConnectionResponse {
+    method: "bluetooth.simulateGattConnectionResponse";
+    params: BluetoothSimulateGattConnectionResponseParameters;
+}
+export interface BluetoothSimulateGattConnectionResponseParameters {
+    context: string;
+    address: string;
+    code: number;
+}
+export interface BluetoothSimulateGattDisconnection {
+    method: "bluetooth.simulateGattDisconnection";
+    params: BluetoothSimulateGattDisconnectionParameters;
+}
+export interface BluetoothSimulateGattDisconnectionParameters {
+    context: string;
+    address: string;
+}
+export interface BluetoothSimulateService {
+    method: "bluetooth.simulateService";
+    params: BluetoothSimulateServiceParameters;
+}
+export interface BluetoothSimulateServiceParameters {
+    context: string;
+    address: string;
+    uuid: BluetoothBluetoothUuid;
+    type: "add" | "remove";
+}
+export interface BluetoothSimulateCharacteristic {
+    method: "bluetooth.simulateCharacteristic";
+    params: BluetoothSimulateCharacteristicParameters;
+}
+export interface BluetoothSimulateCharacteristicParameters {
+    context: string;
+    address: string;
+    serviceUuid: BluetoothBluetoothUuid;
+    characteristicUuid: BluetoothBluetoothUuid;
+    characteristicProperties?: BluetoothCharacteristicProperties;
+    type: "add" | "remove";
+}
+export interface BluetoothSimulateCharacteristicResponse {
+    method: "bluetooth.simulateCharacteristicResponse";
+    params: BluetoothSimulateCharacteristicResponseParameters;
+}
+export interface BluetoothSimulateCharacteristicResponseParameters {
+    context: string;
+    address: string;
+    serviceUuid: BluetoothBluetoothUuid;
+    characteristicUuid: BluetoothBluetoothUuid;
+    type: "read" | "write" | "subscribe-to-notifications" | "unsubscribe-from-notifications";
+    code: number;
+    data?: number[];
+}
+export interface BluetoothSimulateDescriptor {
+    method: "bluetooth.simulateDescriptor";
+    params: BluetoothSimulateDescriptorParameters;
+}
+export interface BluetoothSimulateDescriptorParameters {
+    context: string;
+    address: string;
+    serviceUuid: BluetoothBluetoothUuid;
+    characteristicUuid: BluetoothBluetoothUuid;
+    descriptorUuid: BluetoothBluetoothUuid;
+    type: "add" | "remove";
+}
+export interface BluetoothSimulateDescriptorResponse {
+    method: "bluetooth.simulateDescriptorResponse";
+    params: BluetoothSimulateDescriptorResponseParameters;
+}
+export interface BluetoothSimulateDescriptorResponseParameters {
+    context: string;
+    address: string;
+    serviceUuid: BluetoothBluetoothUuid;
+    characteristicUuid: BluetoothBluetoothUuid;
+    descriptorUuid: BluetoothBluetoothUuid;
+    type: "read" | "write";
+    code: number;
+    data?: number[];
+}
+export type BluetoothEvent = BluetoothRequestDevicePromptUpdated | BluetoothGattConnectionAttempted;
+export interface BluetoothRequestDevicePromptUpdated {
+    method: "bluetooth.requestDevicePromptUpdated";
+    params: BluetoothRequestDevicePromptUpdatedParameters;
+}
+export interface BluetoothRequestDevicePromptUpdatedParameters {
+    context: string;
+    prompt: BluetoothRequestDevicePrompt;
+    devices: BluetoothRequestDeviceInfo[];
+}
+export interface BluetoothGattConnectionAttempted {
+    method: "bluetooth.gattConnectionAttempted";
+    params: BluetoothGattConnectionAttemptedParameters;
+}
+export interface BluetoothGattConnectionAttemptedParameters {
+    context: string;
+    address: string;
+}
+export interface BluetoothCharacteristicEventGenerated {
+    method: "bluetooth.characteristicEventGenerated";
+    params: BluetoothCharacteristicEventGeneratedParameters;
+}
+export interface BluetoothCharacteristicEventGeneratedParameters {
+    context: string;
+    address: string;
+    serviceUuid: BluetoothBluetoothUuid;
+    characteristicUuid: BluetoothBluetoothUuid;
+    type: "read" | "write-with-response" | "write-without-response" | "subscribe-to-notifications" | "unsubscribe-from-notifications";
+    data?: number[];
+}
+export interface BluetoothDescriptorEventGenerated {
+    method: "bluetooth.descriptorEventGenerated";
+    params: BluetoothDescriptorEventGeneratedParameters;
+}
+export interface BluetoothDescriptorEventGeneratedParameters {
+    context: string;
+    address: string;
+    serviceUuid: BluetoothBluetoothUuid;
+    characteristicUuid: BluetoothBluetoothUuid;
+    descriptorUuid: BluetoothBluetoothUuid;
+    type: "read" | "write";
+    data?: number[];
+}
+export declare class Bluetooth {
+    private readonly bidi;
+    private constructor();
+    static create(driver: unknown): Promise<Bluetooth>;
+    handleRequestDevicePrompt(params: BluetoothHandleRequestDevicePromptParameters): Promise<void>;
+    simulateAdapter(params: BluetoothSimulateAdapterParameters): Promise<void>;
+    disableSimulation(params: BluetoothDisableSimulationParameters): Promise<void>;
+    simulatePreconnectedPeripheral(params: BluetoothSimulatePreconnectedPeripheralParameters): Promise<void>;
+    simulateAdvertisement(params: BluetoothSimulateAdvertisementParameters): Promise<void>;
+    simulateGattConnectionResponse(params: BluetoothSimulateGattConnectionResponseParameters): Promise<void>;
+    simulateGattDisconnection(params: BluetoothSimulateGattDisconnectionParameters): Promise<void>;
+    simulateService(params: BluetoothSimulateServiceParameters): Promise<void>;
+    simulateCharacteristic(params: BluetoothSimulateCharacteristicParameters): Promise<void>;
+    simulateCharacteristicResponse(params: BluetoothSimulateCharacteristicResponseParameters): Promise<void>;
+    simulateDescriptor(params: BluetoothSimulateDescriptorParameters): Promise<void>;
+    simulateDescriptorResponse(params: BluetoothSimulateDescriptorResponseParameters): Promise<void>;
+    onRequestDevicePromptUpdated(callback: (params: BluetoothRequestDevicePromptUpdatedParameters) => void): Promise<void>;
+    onGattConnectionAttempted(callback: (params: BluetoothGattConnectionAttemptedParameters) => void): Promise<void>;
+}