[js] Fix MaxListenersExceededWarning in BiDi send (#17423)
* [js] Fix MaxListenersExceededWarning in BiDi send
Replace per-send 'message' listener with a single shared response
dispatcher that routes by request id. Concurrent BiDi traffic, such
as network interception during a navigation, previously attached a
new listener for every in-flight send() and tripped Node's
MaxListenersExceededWarning at the 11th concurrent request.
Pending requests are now tracked in a Map keyed by id; the dispatcher
clears the per-request timeout, removes the entry, and resolves the
caller. close() rejects any outstanding pendings so callers don't
hang on shutdown.
Adds a regression test that asserts no warning is emitted after 50
concurrent sends and that the message-listener count on the underlying
WebSocket remains constant.
Fixes #17380
* [js] Surface BiDi parse errors and fail pendings on socket close
Address review feedback on the MaxListenersExceededWarning fix:
- Emit an 'error' event (or process.emitWarning when no listener) on
JSON parse failures so callers see deterministic protocol errors
instead of opaque send() timeouts. Document that messages without a
numeric id are valid BiDi events and intentionally ignored by the
response dispatcher.
- Hook the WebSocket 'close' and 'error' events. If the peer
disconnects mid-request the in-flight send() promises now reject
promptly via a shared _failPending() helper instead of waiting for
RESPONSE_TIMEOUT (30s). A _closed flag keeps the helper idempotent
so close() and the underlying 'close' event do not double-reject.
Adds regression tests for both behaviors.
* [js] Fail fast in BiDi send() when the connection is closed
Address review feedback: after the underlying socket fails or closes,
_failPending() sets connected=false but waitForConnection() previously
only resolved on a future 'open' event, so a subsequent send() could
hang indefinitely instead of surfacing the closed state.
- send() now rejects immediately when _closed is true.
- waitForConnection() rejects on 'close'/'error' if it is waiting for
'open', and short-circuits to a rejection when _closed is already
set, so it can no longer leak a pending promise on a dead socket.
Adds a regression test asserting send() rejects with a clear error
once the peer has dropped the connection.
* [js] Track BiDi connect waiters centrally so close() unblocks them
Address review feedback: close() called removeAllListeners('close')
on the underlying socket before it actually closed, which could strip
the rejection listener that waitForConnection() registered. A close()
issued while another caller was awaiting connection could therefore
leave that wait pending forever.
Replace the per-call socket listener juggling in waitForConnection()
with a centrally-tracked Set of {resolve, reject} entries:
- The constructor's 'open' handler resolves all parked waiters.
- _failPending() rejects them, so an unexpected disconnect or an
explicit close() reliably unblocks any in-flight waitForConnection().
This removes the dependency on socket listener ordering inside
close(), which is what made the bug possible.
Adds a regression test using a plain-TCP server that accepts but
never completes the WebSocket upgrade, calls close() while the
client is still CONNECTING, and asserts the wait rejects.
* [js] Guard BiDi state transitions against post-close events
Address review feedback and proactively close adjacent seams in the
connection state machine:
- 'open' handler now early-returns when _closed is set and proactively
closes the now-orphan socket. Previously a handshake that completed
after close() left the instance with _closed=true AND connected=true.
- 'message' handler early-returns when _closed is set. Frames arriving
after close() are no longer processed (parse errors emitted, lookups
attempted) on a closed connection.
- send() additionally checks WebSocket.readyState !== OPEN after
waitForConnection() resolves, so sends fail with a clear error
rather than throwing from inside ws.send() if the raw socket has
transitioned to CLOSING/CLOSED.
Adds a regression test that calls close() before the WebSocket has
opened (against an echo server, where the handshake will succeed
moments later) and asserts isConnected stays false.
---------
Co-authored-by: Diego Molina <diemol@users.noreply.github.com>Selenium is an umbrella project encapsulating a variety of tools and libraries enabling web browser automation. Selenium specifically provides an infrastructure for the W3C WebDriver specification — a platform and language-neutral coding interface compatible with all major web browsers.
The project is made possible by volunteer contributors who've generously donated thousands of hours in code development and upkeep.
This README is for developers interested in contributing to the project. For people looking to get started using Selenium, please check out our User Manual for detailed examples and descriptions, and if you get stuck, there are several ways to Get Help.
Please read CONTRIBUTING.md before submitting your pull requests.
These are the requirements to create your own local dev environment to contribute to Selenium.
.bazelversion file and transparently passes through all command-line arguments to the real Bazel binary.JAVA_HOME environment variable to location of Java executable (the JDK not the JRE)javac. This command won‘t exist if you only have the JRE installed. If you’re met with a list of command-line options, you're referencing the JDK properly.xcode-select --installbuild --host_platform=//:rosetta to the .bazelrc.local file. We are working to make sure this isn't required in the long run.Several years ago Jim Evans published a great article on Setting Up a Windows Development Environment for the Selenium .NET Language Bindings; This article is out of date, but it includes more detailed descriptions and screenshots that some people might find useful.
This script will ensure a complete ready to execute developer environment. (nothing is installed or set that is already present unless otherwise prompted)
Set-ExecutionPolicy Bypass -Scope Process -Force to allow running the script in the processSet-ExecutionPolicy -ExecutionPolicy RemoteSigned
reg add "HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows\CurrentVersion\AppModelUnlock" /t REG_DWORD /f /v "AllowDevelopmentWithoutDevLicense" /d "1"
PATH environment variable (e.g., "C:\tools\msys64\usr\bin")bash.exe location as the BAZEL_SH environment variable (e.g., "C:\tools\msys64\usr\bin\bash.exe")BAZEL_VC environment variable (e.g. "C:\Program Files\Microsoft Visual Studio\2022\Community\VC")BAZEL_VC_FULL_VERSION environment variable (this can be discovered from the directory name in "$BAZEL_VC\Tools\MSVC\<BAZEL_VC_FULL_VERSION>")reg add "HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Command Processor" /t REG_DWORD /f /v "DisableUNCCheck" /d "1" reg add "HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\FileSystem" /t REG_DWORD /f /v "LongPathsEnabled" /d "1"
fsutil 8dot3name set 0C:/tmp instead of nested inside project directory:selenium/.bazelrc.windows.localIf you want to contribute to the project, but do not want to set up your own local dev environment, there are two alternatives available.
Rather than creating your own local dev environment, GitPod provides a ready to use environment for you.
As an alternative you can build a Dev Container - basically a docker container - suitable for building and testing Selenium using the devcontainer.json in the .devcontainer directory. Supporting IDEs like VS Code or IntelliJ IDEA should point you to how such a container can be created.
You can also build a Docker image suitable for building and testing Selenium using the Dockerfile in the dev image directory.
Selenium is built using a common build tool called Bazel, to allow us to easily manage dependency downloads, generate required binaries, build and release packages, and execute tests; all in a fast, efficient manner. For a more detailed discussion, read Simon Stewart's article on Building Selenium
Often we wrap Bazel commands with our custom Rake wrapper. These are run with the ./go command.
The common Bazel commands are:
bazel build — evaluates dependencies, compiles source files and generates output files for the specified target. It's used to create executable binaries, libraries, or other artifacts.bazel run — builds the target and then executes it. It's typically used for targets that produce executable binaries.bazel test — builds and runs the target in a context with additional testing functionalitybazel query — identifies available targets for the provided path.Each module that can be built is defined in a BUILD.bazel file. To execute the module you refer to it starting with a //, then include the relative path to the file that defines it, then :, then the name of the target. For example, the target to build the Grid is named executable-grid and it is defined in the 'selenium/java/src/org/openqa/selenium/grid/BAZEL.build' file. So to build the grid you would run: bazel build //java/src/org/openqa/selenium/grid:executable-grid.
The Bazel documentation has a handy guide for various shortcuts and all the ways to build multiple targets, which Selenium makes frequent use of.
To build everything for a given language:
bazel build //<language>/...
To build just the grid there is an alias name to use (the log will show where the output jar is located):
bazel build grid
To make things more simple, building each of the bindings is available with this ./go command:
./go <language>:build
Most of the team uses Intellij for their day-to-day editing. If you're working in IntelliJ, then we highly recommend installing the Bazel IJ plugin which is documented on its own site.
To use Selenium with the IntelliJ Bazel plugin, import the repository as a Bazel project, and select the project view file from the scripts directory. ij.bazelproject for Mac/Linux and ij-win.bazelproject for Windows.
We also use Google Java Format for linting, so using the Google Java Formatter Plugin is useful; there are a few steps to get it working, so read their configuration documentation. There is also an auto-formatting script that can be run: ./scripts/format.sh
While Selenium is not built with Maven, you can build and install the Selenium pieces for Maven to use locally by deploying to your local maven repository (~/.m2/repository), using:
./go java:install
Dependencies are defined in the file MODULE.bazel.
To update a dependency, modify the version in the MODULE.bazel file and run:
RULES_JVM_EXTERNAL_REPIN=1 bazel run @maven//:pin
To automatically update and pin new dependencies, run:
./go java:update
We follow the PEP8 Style Guide for Python Code (except we use a 120 character line length). This is checked and enforced with ruff, a linting/formatting tool. There is also an auto-formatting script that can be run: ./scripts/format.sh
To run Python code locally without building/installing the package, you must first install the dependencies:
pip install -r py/requirements.txt
Then, build the generated files and copy them into your local source tree:
./go py:local_dev
After that, you can import the selenium package directly from source from the py directory.
Instead of running from source, you can build and install the selenium package (wheel) locally:
./go py:install
This will attempt to install into the global Python site-packages directory, which might not be writable. To avoid this, you should create and activate a virtual environment before installing.
Instead of using irb, you can create an interactive REPL with all gems loaded using: bazel run //rb:console
If you want to debug code, you can do it via debug gem:
binding.break to the code where you want the debugger to start.ruby_debug configuration: bazel test --config ruby_debug <test>.bazel-selenium/external/bundle/bin/rdbg -A
If you want to use RubyMine for development, you can configure it use Bazel artifacts:
rb/ as a main project directory.selenium (parent) directory, run ./go rb:local_dev to create up-to-date artifacts.../bazel-selenium/external/rules_ruby++ruby+ruby/dist/bin/ruby.Rust Bazel dependencies are generated directly from rust/Cargo.toml and rust/Cargo.lock.
There are a number of bazel configurations specific for testing.
Here are examples of arguments we make use of in testing the Selenium code:
--pin_browsers=false - use Selenium Manager to locate browsers/drivers--headless - run browsers in headless mode (supported be Chrome, Edge and Firefox)--flaky_test_attempts 3 - re-run failed tests up to 3 times--local_test_jobs 1 - control parallelism of tests--cache_test_results=no, -t- - disable caching of test results and re-runs all of them--test_output all - print all output from the tests, not just errors--test_output streamed - run all tests one by one and print its output immediately--test_env FOO=bar - pass extra environment variable to test process--run_under="xvfb-run -a" - prefix to insert before the executionSelenium tests can be filtered by size:
These can be filtered using the test_size_filters argument like this:
bazel test //<language>/... --test_size_filters=small
Tests can also be filtered by tag like:
bazel test //<language>/... --test_tag_filters=this,-not-this
If there are multiple --test_tag_filters, only the last one is considered, so be careful if also using an inherited config
To run unit tests:
bazel test //java/... --test_size_filters=small
To run integration tests:
bazel test //java/... --test_size_filters=medium
To run browser tests:
bazel test //java/... --test_size_filters=large --test_tag_filters=<browser>
To run a specific test:
bazel test //java/test/org/openqa/selenium/chrome:ChromeDriverFunctionalTest
To run the tests run:
bazel test //javascript/selenium-webdriver:all
You can use --test_env to pass in the browser name as SELENIUM_BROWSER.
bazel test //javascript/selenium-webdriver:all --test_env=SELENIUM_BROWSER=firefox
Run unit tests with:
bazel test //py:unit
To run all tests with a specific browser:
bazel test //py:test-<browsername>
To run common tests with a specific browser (include BiDi tests):
bazel test //py:test-<browsername>-bidi
To run all Python tests:
bazel test //py:all
To run tests headless:
bazel test //py:test-<browsername> --//common:headless=true
Test targets:
| Command | Description |
|---|---|
bazel test //rb/... | Run unit, all integration tests and lint |
bazel test //rb:lint | Run RuboCop linter |
bazel test //rb/spec/... | Run unit and integration tests for all browsers |
bazel test //rb/spec/... --test_size_filters small | Run unit tests |
bazel test //rb/spec/unit/... | Run unit tests |
bazel test //rb/spec/... --test_size_filters large | Run integration tests for all browsers |
bazel test //rb/spec/integration/... | Run integration tests for all browsers |
bazel test //rb/spec/integration/... --test_tag_filters firefox | Run integration tests for local Firefox only |
bazel test //rb/spec/integration/... --test_tag_filters firefox-remote | Run integration tests for remote Firefox only |
bazel test //rb/spec/integration/... --test_tag_filters firefox,firefox-remote | Run integration tests for local and remote Firefox |
Ruby test targets have the same name as the spec file with _spec.rb removed, so you can run them individually. Integration tests targets also have a browser and remote suffix to control which browser to pick and whether to use Grid.
| Test file | Test target |
|---|---|
rb/spec/unit/selenium/webdriver/proxy_spec.rb | //rb/spec/unit/selenium/webdriver:proxy |
rb/spec/integration/selenium/webdriver/driver_spec.rb | //rb/spec/integration/selenium/webdriver:driver-chrome |
rb/spec/integration/selenium/webdriver/driver_spec.rb | //rb/spec/integration/selenium/webdriver:driver-chrome-remote |
rb/spec/integration/selenium/webdriver/driver_spec.rb | //rb/spec/integration/selenium/webdriver:driver-firefox |
rb/spec/integration/selenium/webdriver/driver_spec.rb | //rb/spec/integration/selenium/webdriver:driver-firefox-remote |
Supported browsers:
chromeedgefirefoxfirefox-betaiesafarisafari-previewIn addition to the Common Options Examples, here are some additional Ruby specific ones:
--test_arg "-eTimeouts" - test only specs which name include “Timeouts”--test_arg "<any other RSpec argument>" - pass any extra RSpec arguments (see bazel run @bundle//bin:rspec -- --help)Supported environment variables for use with --test_env:
WD_SPEC_DRIVER - the driver to test; either the browser name or ‘remote’ (gets set by Bazel)WD_REMOTE_BROWSER - when WD_SPEC_DRIVER is remote; the name of the browser to test (gets set by Bazel)WD_REMOTE_URL - URL of an already running server to use for remote testsDOWNLOAD_SERVER - when WD_REMOTE_URL not set; whether to download and use most recently released server version for remote testsDEBUG - turns on verbose debuggingHEADLESS - for chrome, edge and firefox; runs tests in headless modeDISABLE_BUILD_CHECK - for chrome and edge; whether to ignore driver and browser version mismatches (allows testing Canary builds)CHROME_BINARY - path to test specific Chrome browserCHROMEDRIVER_BINARY - path to test specific ChromeDriverEDGE_BINARY - path to test specific Edge browserMSEDGEDRIVER_BINARY - path to test specific msedgedriverFIREFOX_BINARY - path to test specific Firefox browserGECKODRIVER_BINARY - path to test specific GeckoDriverTo run with a specific version of Ruby you can change the version in rb/.ruby-version or from command line:
echo '<X.Y.Z>' > rb/.ruby-version
.NET tests currently only work with pinned browsers, so make sure to include that.
Run all tests with:
bazel test //dotnet/test/common
You can run specific tests by specifying the class name:
bazel test //dotnet/test/common:ElementFindingTests
If the module supports multiple browsers:
bazel test //dotnet/test/common:ElementFindingTests-edge
Rust tests are run with:
bazel test //rust/...
By default, Bazel runs these tests in your current X-server UI. If you prefer, you can alternatively run them in a virtual or nested X-server.
Xvfb :99 or Xnest :99DISPLAY=:99 jwmbazel test --test_env=DISPLAY=:99 //java/... --test_tag_filters=chrome
An easy way to run tests in a virtual X-server is to use Bazel's --run_under functionality:
bazel test --run_under="xvfb-run -a" //java/...
API documentation can be found here:
To update API documentation for a specific language: ./go <language>:docs
To update all documentation: ./go all:docs
The full process for doing a release can be found in the wiki
Releasing is a combination of building and publishing, which often requires coordination of multiple executions and additional processing. As discussed in the Building section, we use Rake tasks with the ./go command for these things. These ./go commands include the --stamp argument to provide necessary information about the constructed asset.
You can build and release everything with:
./go all:release
To build and release a specific language:
./go <language>:release
If you have access to the Selenium EngFlow repository, you can have the assets built remotely and downloaded locally using:
./go all:release['--config', 'release']