Selenium WebDriver Engine

Detailed Changelogs by Component

<img src="https://www.selenium.dev/images/programming/java.svg" width="20" height="20"> Java &nbsp;&nbsp;&nbsp; | &nbsp;&nbsp;&nbsp;<img src="https://www.selenium.dev/images/programming/python.svg" width="20" height="20"> Python &nbsp;&nbsp;&nbsp; | &nbsp;&nbsp;&nbsp;<img src="https://www.selenium.dev/images/programming/dotnet.svg" width="20" height="20"> DotNet &nbsp;&nbsp;&nbsp; | &nbsp;&nbsp;&nbsp;<img src="https://www.selenium.dev/images/programming/ruby.svg" width="20" height="20"> Ruby &nbsp;&nbsp;&nbsp; | &nbsp;&nbsp;&nbsp;<img src="https://www.selenium.dev/images/programming/javascript.svg" width="20" height="20"> JavaScript

<br>

<!-- Release notes generated using configuration in .github/release.yml at selenium-4.46.0 -->

What's Changed

• [build] Upgrade rules_rs to 0.0.90 and build Rust against @llvm on macOS by @AutomatedTester in https://github.com/SeleniumHQ/selenium/pull/17683
• [dotnet] Thread safe product info determination by @nvborisenko in https://github.com/SeleniumHQ/selenium/pull/17684
• [release] Skip release if package is already published by @diemol in https://github.com/SeleniumHQ/selenium/pull/17686
• [docs] add design decision record process and template by @titusfortner in https://github.com/SeleniumHQ/selenium/pull/17665
• [rust] Support pbzx-compressed macOS .pkg payloads by @AutomatedTester in https://github.com/SeleniumHQ/selenium/pull/17691
• [java] Mark all current BiDi related classes beta by @pujagani in https://github.com/SeleniumHQ/selenium/pull/17690
• [build] Upgrade rules_rs to 0.0.92 by @AutomatedTester in https://github.com/SeleniumHQ/selenium/pull/17688
• [ci] Ignore changes in docs/decisions directory for pull requests by @diemol in https://github.com/SeleniumHQ/selenium/pull/17693
• [build] Upgrade @llvm to 0.8.9 by @AutomatedTester in https://github.com/SeleniumHQ/selenium/pull/17703
• [rust] Use PKG again for Firefox macOS downloads by @AutomatedTester in https://github.com/SeleniumHQ/selenium/pull/17702
• [rb] trim whitespace around NO_PROXY entries by @aguspe in https://github.com/SeleniumHQ/selenium/pull/17565
• Treat prefix literally in UrlTemplate.match(url, prefix) by @vasiliy-mikhailov in https://github.com/SeleniumHQ/selenium/pull/17713
• [java] show browser version and available CDP versions by @asolntsev in https://github.com/SeleniumHQ/selenium/pull/17708
• Make Either.stream() and iterator() empty for a left value by @vasiliy-mikhailov in https://github.com/SeleniumHQ/selenium/pull/17714
• [java] Handle system proxy setting for arguments passed to selenium manager by @bhecquet in https://github.com/SeleniumHQ/selenium/pull/17402
• [js] Add binding-neutral BiDi schema with cddl2ts-gated fidelity by @titusfortner in https://github.com/SeleniumHQ/selenium/pull/17700
• [build] add copyright headers to rbs, pyi, ts, mjs, and erb files by @titusfortner in https://github.com/SeleniumHQ/selenium/pull/17720
• [rb] add ClientConfig for HTTP client customization by @titusfortner in https://github.com/SeleniumHQ/selenium/pull/17699
• [rb] Add copyright header for client_config.rbs by @nvborisenko in https://github.com/SeleniumHQ/selenium/pull/17722
• [dotnet] [bidi] Split event stream backed subscription and enumeration by @nvborisenko in https://github.com/SeleniumHQ/selenium/pull/17705
• [dotnet] [test] Moves Urls knowledge to testing web server by @nvborisenko in https://github.com/SeleniumHQ/selenium/pull/17724
• [java] fix comparator of Docker versions by @asolntsev in https://github.com/SeleniumHQ/selenium/pull/17723
• [dotnet] [test] Driver is protected thr

<h1 align="center">

<br/>

<a href="https://selenium.dev"><img src="common/images/selenium_logo_mark_green.svg" alt="Selenium" width="100"></a>

<br/>

Selenium

<br/>

</h1>

<h3 align="center">Automates browsers. That's it!</h3>

<p align="center">

<a href="#contributing">Contributing</a> •

<a href="#installing">Installing</a> •

<a href="#building">Building</a> •

<a href="#developing">Developing</a> •

<a href="#testing">Testing</a> •

<a href="#documenting">Documenting</a> •

<a href="#releasing">Releasing</a>

</p>

<br>

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.

CI

CI - RBE

Releases downloads

Contributing

Please read CONTRIBUTING.md

before submitting your pull requests.

Installing

These are the requirements to create your own local dev environment to contribute to Selenium.

All Platforms

• Bazelisk, a Bazel wrapper that automatically downloads

the version of Bazel specified in .bazelversion file and transparently passes through all

command-line arguments to the real Bazel binary.

• Java JDK version 17 or greater (e.g., Java 17 Temurin)
• Set JAVA_HOME environment variable to location of Java executable (the JDK not the JRE)
• To test this, try running the command 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.

MacOS

• Xcode including the command-line tools. Install the latest version using: xcode-select --install
• Rosetta for Apple Silicon Macs. Add build --host_platform=//:rosetta to the .bazelrc.local file. We are working

to make sure this isn't required in the long run.

Windows

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.

<details>

<summary>Click to see Current Windows Setup Requirements</summary>

Option 1: Automatic Installation from Scratch

This script will ensure a complete ready to execute developer environment.

(nothing is installed or set that is already present unless otherwise prompted)

1. Open Powershell as an Administrator
2. Execute: Set-ExecutionPolicy Bypass -Scope Process -Force to allow running the script in the process
3. Navigate to the directory you want to clone Selenium in, or the parent directory of an already cloned Selenium repo
4. Download and execute this script in the powershell terminal: [scripts/dev-environment-setup.ps1]`

Option 2: Manual Installation

1. Allow running scripts in Selenium in general:

    Set-ExecutionPolicy -ExecutionPolicy RemoteSigned

1. Enable Developer Mode:

    reg add "HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows\CurrentVersion\AppModelUnlock" /t REG_DWORD /f /v "AllowDevelopmentWithoutDevLicense" /d "1"

1. Install MSYS2, which is an alternative shell environment that provides Unix-like commands

• Add bin directory to PATH environment variable (e.g., "C:\tools\msys64\usr\bin")
• Add bash.exe location as the BAZEL_SH environment variable (e.g., "C:\tools\msys64\usr\bin\bash.exe")

1. Install the latest version of Visual Studio Community

• Use the visual studio installer to modify and add the "Desktop development with C++" Workload
• Add Visual C++ build tools installation directory location to BAZEL_VC environment variable (e.g. "C:\Program Files\Microsoft Visual Studio\2022\Community\VC")
• Add Visual C++ Build tools version to BAZEL_VC_FULL_VERSION environment variable (this can be discovered from the directory name in "$BAZEL_VC\Tools\MSVC\<BAZEL_VC_FULL_VERSION>")

1. Add support for long file names (bazel has a lot of nested directories that can exceed default limits in Windows)

• Enable Long Paths support with these 2 registry commands:

    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"

• Allow Bazel to create short name versions of long file paths: fsutil 8dot3name set 0
• Set bazel output to C:/tmp instead of nested inside project directory:
• Create a file selenium/.bazelrc.windows.local
• Add "startup --output_user_root=C:/tmp" to the file

</details>

Alternative Dev Environments

If you want to contribute to the project, but do not want to set up your own local dev environment,

there are two alternatives available.

Using GitPod

Rather than creating your own local dev environment, GitPod provides a ready to use environment for you.

Open in Gitpod

Using Dev Container

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.

Using Docker Image

You can also build a Docker image suitable

for building and testing Selenium using the Dockerfile in the

dev image directory.

Using Worktrees

Bazel keeps its build outputs and downloaded dependencies under each checkout by default, which means

working from multiple worktrees re-downloads dependencies and rebuilds artifacts.

Pointing Bazel at user-level caches avoids that.

Add the following to /path/to/your/home/.bazelrc

common --disk_cache=/path/to/your/home/.cache/bazel-disk
common --repository_cache=/path/to/your/home/.cache/bazel-repo

--disk_cache stores compiled action outputs; --repository_cache stores downloaded external

dependencies (e.g. http_archive tarballs). Both directories grow unbounded over time — prune them

periodically if disk space matters. Keep the cache on the same filesystem as your checkouts so Bazel

can hardlink instead of copy.

Bazel also creates a separate output base (compiled outputs, analysis cache, and the Bazel

server) per checkout path. Unlike the caches above, it is not removed when you delete a worktree —

so frequently created and discarded worktrees leak gigabytes of stale output.

On macOS/Linux, make a worktree self-cleaning by pointing its output base inside the worktree. Add

this to that worktree's .bazelrc.local:

startup --output_base=.local/output-base

.local/ is gitignored and excluded in .bazelignore, so removing the worktree removes its output

base with it. The shared --disk_cache/--repository_cache above still keep downloads and action

outputs shared across worktrees.

(Windows users should instead keep startup --output_user_root=C:/tmp in .bazelrc.windows.local as

described above, to avoid path-length limits — do not nest the output base deeper inside the repo on

Windows.)

Building

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 functionality
• bazel 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

Developing

Java

IntelliJ

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](https://plugins.jetbrains.com/plugin/8609-bazel) 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.

Linting

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

Local Installation

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

Updating Dependencies

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

Python

Linting and Formatting

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

Local Installation

To run Python code locally without building/installing the package, you must first install the dependencies:

pip install -r py/requirements_lock.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.

Ruby

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:

1. Add binding.break to the code where you want the debugger to start.
2. Run tests with ruby_debug configuration: bazel test --config ruby_debug <test>.
3. When debugger starts, run the following in a separate terminal to connect to debugger:

bazel-se