2025-01-27 11:45:54 +03:00
<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> •
2025-06-24 15:56:23 +03:00
<a href="#releasing ">Releasing</a>
2025-01-27 11:45:54 +03:00
</p>
<br>
2016-10-13 22:29:02 -04:00
2016-10-13 22:27:47 -04:00
Selenium is an umbrella project encapsulating a variety of tools and
libraries enabling web browser automation. Selenium specifically
2020-09-26 01:38:03 +05:30
provides an infrastructure for the [W3C WebDriver specification ](https://w3c.github.io/webdriver/ )
2016-10-13 22:27:47 -04:00
— a platform and language-neutral coding interface compatible with all
2015-07-28 00:35:17 -05:00
major web browsers.
2015-03-25 13:27:11 -07:00
2016-10-13 22:27:47 -04:00
The project is made possible by volunteer contributors who've
generously donated thousands of hours in code development and upkeep.
2015-07-28 00:35:17 -05:00
2023-12-21 10:11:02 -06:00
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 ](https://selenium.dev/documentation/ ) for detailed examples and descriptions, and if you
get stuck, there are several ways to [Get Help ](https://www.selenium.dev/support/ ).
2015-03-14 15:46:23 +00:00
2025-01-27 11:45:54 +03:00
[](https://github.com/SeleniumHQ/selenium/actions/workflows/ci.yml)
[](https://github.com/SeleniumHQ/selenium/actions/workflows/ci-rbe.yml)
[](https://github.com/SeleniumHQ/selenium/releases)
2023-12-21 10:11:02 -06:00
## Contributing
2013-12-09 12:15:29 +00:00
2020-07-15 15:54:25 -05:00
Please read [CONTRIBUTING.md ](https://github.com/SeleniumHQ/selenium/blob/trunk/CONTRIBUTING.md )
2015-07-28 00:35:17 -05:00
before submitting your pull requests.
2013-12-09 12:15:29 +00:00
2023-12-21 10:11:02 -06:00
## Installing
2023-12-22 15:58:03 -06:00
These are the requirements to create your own local dev environment to contribute to Selenium.
2023-12-21 10:11:02 -06:00
### All Platforms
2025-10-28 15:55:25 -04:00
2020-12-10 15:59:17 +00:00
* [Bazelisk ](https://github.com/bazelbuild/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.
2023-12-21 10:11:02 -06:00
* Java JDK version 17 or greater (e.g., [Java 17 Temurin ](https://adoptium.net/temurin/releases/?version=17 ))
* Set `JAVA_HOME` environment variable to location of Java executable (the JDK not the JRE)
2020-12-10 15:59:17 +00:00
* 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.
2023-12-21 10:11:02 -06:00
### MacOS
2025-10-28 15:55:25 -04:00
2023-12-21 10:11:02 -06:00
* 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
2021-04-24 21:19:58 +01:00
to make sure this isn't required in the long run.
2020-12-10 15:59:17 +00:00
2023-12-21 10:11:02 -06:00
### Windows
2025-10-28 15:55:25 -04:00
2023-12-21 10:11:02 -06:00
Several years ago [Jim Evans ](https://www.linkedin.com/in/jimevansmusic/ ) published a great article on
[Setting Up a Windows Development Environment for the Selenium .NET Language Bindings ](https://jimevansmusic.blogspot.com/2020/04/setting-up-windows-development.html );
This article is out of date, but it includes more detailed descriptions and screenshots that some people might find useful.
2020-12-10 15:59:17 +00:00
2023-12-21 10:11:02 -06:00
<details>
<summary>Click to see Current Windows Setup Requirements</summary>
#### Option 1: Automatic Installation from Scratch
2025-10-28 15:55:25 -04:00
2024-03-01 07:17:01 -08:00
This script will ensure a complete ready to execute developer environment.
(nothing is installed or set that is already present unless otherwise prompted)
2023-12-21 10:11:02 -06:00
1. Open Powershell as an Administrator
2. Execute: `Set-ExecutionPolicy Bypass -Scope Process -Force` to allow running the script in the process
2024-03-01 07:17:01 -08:00
3. Navigate to the directory you want to clone Selenium in, or the parent directory of an already cloned Selenium repo
2023-12-21 10:11:02 -06:00
4. Download and execute this script in the powershell terminal: [scripts/dev-environment-setup.ps1]`
#### Option 2: Manual Installation
2025-10-28 15:55:25 -04:00
2023-12-21 10:11:02 -06:00
1. Allow running scripts in Selenium in general:
```
Set-ExecutionPolicy -ExecutionPolicy RemoteSigned
` ``
2. Enable Developer Mode:
` ``
reg add "HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows\CurrentVersion\AppModelUnlock" /t REG_DWORD /f /v "AllowDevelopmentWithoutDevLicense" /d "1"
` ``
3. Install [MSYS2](https://www.msys2.org/), 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"`)
4. Install the latest version of [Visual Studio Community](https://visualstudio.microsoft.com/vs/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>"`)
5. 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:
` ``shell
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
2020-12-10 15:59:17 +00:00
2023-12-21 10:11:02 -06:00
</details>
2020-12-10 15:59:17 +00:00
2023-12-21 10:11:02 -06:00
### Alternative Dev Environments
2020-12-10 15:59:17 +00:00
2023-12-21 10:11:02 -06:00
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.
2013-12-09 12:15:29 +00:00
2023-12-21 10:11:02 -06:00
#### Using GitPod
2022-07-12 13:18:35 +02:00
2023-12-21 10:11:02 -06:00
Rather than creating your own local dev environment, GitPod provides a ready to use environment for you.
2022-07-12 13:18:35 +02:00
[](https://gitpod.io/#https://github.com/SeleniumHQ/selenium)
2024-03-04 13:46:37 +01:00
#### Using Dev Container
As an alternative you can build a [Dev Container](https://containers.dev/) - basically a docker container -
suitable for building and testing Selenium using the devcontainer.json in the
[.devcontainer](.devcontainer/devcontainer.json) directory. Supporting IDEs like VS Code or IntelliJ IDEA
should point you to how such a container can be created.
2023-12-21 10:11:02 -06:00
#### Using Docker Image
2022-07-12 13:18:35 +02:00
2023-12-21 10:11:02 -06:00
You can also build a Docker image suitable
for building and testing Selenium using the Dockerfile in the
[dev image](scripts/dev-image/Dockerfile) directory.
2019-07-11 13:45:17 -05:00
2023-12-21 10:11:02 -06:00
## Building
2019-07-11 13:45:17 -05:00
2024-03-01 07:17:01 -08:00
Selenium is built using a common build tool called [Bazel](https://bazel.build/), to
2023-12-21 10:11:02 -06:00
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](https://www.selenium.dev/blog/2023/building-selenium/)
2019-07-11 13:45:17 -05:00
2023-12-21 10:11:02 -06:00
Often we wrap Bazel commands with our custom [Rake](http://rake.rubyforge.org/) wrapper. These are run with the ` ./go` command.
2016-03-10 13:36:25 -08:00
2023-12-21 10:11:02 -06:00
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.
2024-03-01 07:17:01 -08:00
* ` bazel run` — builds the target and then executes it.
2023-12-21 10:11:02 -06:00
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.
2013-12-09 12:15:29 +00:00
2024-03-01 07:17:01 -08:00
Each module that can be built is defined in a ` BUILD.bazel` file. To execute the module you refer to it starting with a
2023-12-21 10:11:02 -06:00
` //`, 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`.
2021-07-30 15:20:48 +01:00
2023-12-21 10:11:02 -06:00
The Bazel documentation has a [handy guide](https://bazel.build/run/build#specifying-build-targets)
for various shortcuts and all the ways to build multiple targets, which Selenium makes frequent use of.
2021-07-30 15:20:48 +01:00
2023-12-21 10:11:02 -06:00
To build everything for a given language:
2025-10-28 15:55:25 -04:00
2023-12-21 10:11:02 -06:00
` ``shell
bazel build //<language>/...
` ``
2011-04-06 17:25:32 +00:00
2023-12-21 10:11:02 -06:00
To build just the grid there is an alias name to use (the log will show where the output jar is located):
2025-10-28 15:55:25 -04:00
` ``shell
2023-12-21 10:11:02 -06:00
bazel build grid
2013-01-12 16:36:28 +00:00
` ``
2011-04-06 17:25:32 +00:00
2025-10-28 15:55:25 -04:00
To make things more simple, building each of the bindings is available with this ` ./go` command:
2023-12-21 10:11:02 -06:00
` ``shell
./go <language>:build
` ``
2013-12-09 12:15:29 +00:00
2023-12-21 10:11:02 -06:00
## Developing
### Java
#### IntelliJ
2025-10-28 15:55:25 -04:00
2023-12-21 10:11:02 -06:00
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](https://plugins.jetbrains.com/plugin/8609-bazel).
To use Selenium with the IntelliJ Bazel plugin, import the repository as a Bazel project, and select the project
view file from the [scripts](scripts) directory. ` ij.bazelproject` for Mac/Linux and ` ij-win.bazelproject` for Windows.
#### Linting
2025-10-28 15:55:25 -04:00
2023-12-21 10:11:02 -06:00
We also use Google Java Format for linting, so using the Google Java Formatter Plugin is useful;
2024-03-01 07:17:01 -08:00
there are a few steps to get it working, so read their [configuration documentation](https://github.com/google/google-java-format/blob/master/README.md#intellij-jre-config).
2023-12-21 10:11:02 -06:00
There is also an auto-formatting script that can be run: ` ./scripts/format.sh`
#### Local Installation
2025-10-28 15:55:25 -04:00
2023-12-21 10:11:02 -06:00
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:
2025-10-28 15:55:25 -04:00
2023-12-21 10:11:02 -06:00
` ``shell
./go java:install
2013-12-09 12:15:29 +00:00
` ``
2023-12-21 10:11:02 -06:00
#### Updating Dependencies
2025-03-19 14:06:25 -07:00
Dependencies are defined in the file [MODULE.bazel](https://github.com/SeleniumHQ/selenium/blob/trunk/MODULE.bazel).
2025-05-02 22:09:36 +02:00
To update a dependency, modify the version in the ` MODULE.bazel` file and run:
` ``shell
RULES_JVM_EXTERNAL_REPIN=1 bazel run @maven//:pin
` ``
2023-12-22 15:58:03 -06:00
To automatically update and pin new dependencies, run:
2023-12-21 10:11:02 -06:00
2023-12-22 15:58:03 -06:00
` ``shell
./go java:update
` ``
2023-12-21 10:11:02 -06:00
### Python
2025-05-17 08:26:02 -04:00
#### Linting and Formatting
2025-03-16 21:23:19 -04:00
We follow the [PEP8 Style Guide for Python Code](https://peps.python.org/pep-0008) (except we use a 120 character line length).
2025-05-17 08:26:02 -04:00
This is checked and enforced with [ruff](https://docs.astral.sh/ruff/), a linting/formatting tool.
There is also an auto-formatting script that can be run: ` ./scripts/format.sh`
2022-02-09 11:32:44 +01:00
2025-03-16 21:23:19 -04:00
#### Local Installation
To run Python code locally without building/installing the package, you must first install the dependencies:
2025-10-28 15:55:25 -04:00
2025-03-16 21:23:19 -04:00
` ``shell
pip install -r py/requirements.txt
` ``
Then, build the generated files and copy them into your local source tree:
2025-10-28 15:55:25 -04:00
2025-03-16 21:23:19 -04:00
` ``shell
./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:
2025-10-28 15:55:25 -04:00
2023-12-21 10:11:02 -06:00
` ``shell
./go py:install
` ``
2022-11-03 06:44:54 -07:00
2025-03-16 21:23:19 -04:00
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](https://packaging.python.org/en/latest/tutorials/installing-packages/#creating-virtual-environments)
before installing.
2023-12-21 10:11:02 -06:00
### Ruby
2021-07-30 15:20:48 +01:00
2023-12-21 10:11:02 -06:00
Instead of using ` irb`, you can create an interactive REPL with all gems loaded using: ` bazel run //rb:console`
2021-07-30 15:20:48 +01:00
2023-12-21 10:11:02 -06:00
If you want to debug code, you can do it via [` debug`](https://github.com/ruby/debug) gem:
2025-10-28 15:55:25 -04:00
2023-12-21 10:11:02 -06:00
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:
2021-07-30 15:20:48 +01:00
2025-10-28 15:55:25 -04:00
` ``shell
2023-12-21 10:11:02 -06:00
bazel-selenium/external/bundle/bin/rdbg -A
2021-07-30 15:20:48 +01:00
` ``
2024-03-01 07:17:01 -08:00
If you want to use [RubyMine](https://www.jetbrains.com/ruby/) for development,
2023-12-21 10:11:02 -06:00
you can configure it use Bazel artifacts:
2021-07-30 15:20:48 +01:00
2023-12-21 10:11:02 -06:00
1. Open ` rb/` as a main project directory.
2026-01-19 10:17:49 -06:00
2. From the ` selenium` (parent) directory, run ` ./go rb:local_dev` to create up-to-date artifacts.
3. In <kbd>Settings / Languages & Frameworks / Ruby SDK and Gems</kbd> add new <kbd>Interpreter</kbd> pointing to ` ../bazel-selenium/external/rules_ruby++ruby+ruby/dist/bin/ruby`.
2025-07-08 00:51:42 +09:00
4. You should now be able to run and debug any spec. It uses Chrome by default, but you can alter it using environment variables specified in [Ruby Testing](#ruby-2) section below.
2023-12-21 10:11:02 -06:00
### Rust
2025-10-28 15:55:25 -04:00
To keep ` Cargo.Bazel.lock` synchronized with ` Cargo.lock`, run:
2023-12-21 10:11:02 -06:00
` ``shell
2026-01-17 09:52:29 -06:00
CARGO_BAZEL_REPIN=true bazel run @crates//:all
2021-07-30 15:20:48 +01:00
` ``
2018-01-30 15:06:59 +03:00
2023-12-21 10:11:02 -06:00
## Testing
There are a number of bazel configurations specific for testing.
### Common Options Examples
Here are examples of arguments we make use of in testing the Selenium code:
2025-12-20 10:34:27 -06:00
* ` --pin_browsers=false` - use Selenium Manager to locate browsers/drivers
2024-03-15 11:26:40 -07:00
* ` --headless` - run browsers in headless mode (supported be Chrome, Edge and Firefox)
2023-12-21 10:11:02 -06:00
* ` --flaky_test_attempts 3` - re-run failed tests up to 3 times
* ` --local_test_jobs 1` - control parallelism of tests
2023-12-21 16:29:43 -06:00
* ` --cache_test_results=no`, ` -t-` - disable caching of test results and re-runs all of them
2023-12-21 10:11:02 -06:00
* ` --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 execution
### Filtering
Selenium tests can be filtered by size:
* small — typically unit tests where no browser is opened
* large — typically tests that actually drive a browser
* medium — tests that are more involved than simple unit tests, but not fully driving a browser
These can be filtered using the ` test_size_filters` argument like this:
2025-10-28 15:55:25 -04:00
` ``shell
2023-12-21 10:11:02 -06:00
bazel test //<language>/... --test_size_filters=small
2021-07-30 15:20:48 +01:00
` ``
2023-12-21 10:11:02 -06:00
Tests can also be filtered by tag like:
2025-10-28 15:55:25 -04:00
` ``shell
2023-12-21 10:11:02 -06:00
bazel test //<language>/... --test_tag_filters=this,-not-this
` ``
2021-07-30 15:20:48 +01:00
2025-03-14 15:59:12 -07:00
If there are multiple ` --test_tag_filters`, only the last one is considered,
2026-01-21 11:27:00 -05:00
so be careful if also using an inherited config.
2025-03-14 15:59:12 -07:00
2026-01-21 11:27:00 -05:00
### Language Specific Testing Guides
2021-07-30 15:20:48 +01:00
2026-01-21 11:27:00 -05:00
See the ` TESTING.md` file in the applicable language specific directory.
2016-06-07 22:27:00 +01:00
2023-12-21 10:11:02 -06:00
### Linux
2020-09-15 13:27:46 +02:00
2023-12-21 10:11:02 -06:00
<details>
<summary>Click to see Linux Testing Requirements</summary>
2020-11-27 11:34:30 +01:00
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.
2020-09-15 13:27:46 +02:00
1. Run the X server ` Xvfb :99` or ` Xnest :99`
2020-09-26 01:38:03 +05:30
2. Run a window manager, for example, ` DISPLAY=:99 jwm`
2020-09-15 13:27:46 +02:00
3. Run the tests you are interested in:
2025-10-28 15:55:25 -04:00
` ``shell
2020-09-15 13:27:46 +02:00
bazel test --test_env=DISPLAY=:99 //java/... --test_tag_filters=chrome
` ``
2020-11-27 11:34:30 +01:00
An easy way to run tests in a virtual X-server is to use Bazel's ` --run_under`
functionality:
2025-10-28 15:55:25 -04:00
2020-11-27 11:34:30 +01:00
` ``
2023-12-21 10:11:02 -06:00
bazel test --run_under="xvfb-run -a" //java/...
2020-11-27 11:34:30 +01:00
` ``
2023-12-21 10:11:02 -06:00
</details>
2020-11-27 11:34:30 +01:00
2021-08-31 23:41:55 +01:00
2023-12-21 10:11:02 -06:00
## Documenting
2021-08-31 23:41:55 +01:00
2023-12-21 10:11:02 -06:00
API documentation can be found here:
2019-07-11 13:45:17 -05:00
2023-12-21 10:11:02 -06:00
* [C#](https://seleniumhq.github.io/selenium/docs/api/dotnet/)
* [JavaScript](https://seleniumhq.github.io/selenium/docs/api/javascript/)
* [Java](https://seleniumhq.github.io/selenium/docs/api/java/index.html)
* [Python](https://seleniumhq.github.io/selenium/docs/api/py/)
* [Ruby](https://seleniumhq.github.io/selenium/docs/api/rb/)
2019-07-11 13:45:17 -05:00
2024-03-01 07:17:01 -08:00
To update API documentation for a specific language: ` ./go <language>:docs`
2019-07-11 13:45:17 -05:00
2024-03-01 07:17:01 -08:00
To update all documentation: ` ./go all:docs`
2019-07-11 13:45:17 -05:00
2023-12-21 10:11:02 -06:00
## Releasing
2019-07-11 13:45:17 -05:00
2023-12-21 10:11:02 -06:00
The full process for doing a release can be found in [the wiki](https://github.com/SeleniumHQ/selenium/wiki/Releasing-Selenium)
2019-07-11 13:45:17 -05:00
2023-12-21 10:11:02 -06:00
Releasing is a combination of building and publishing, which often requires coordination of multiple executions
2024-03-01 07:17:01 -08:00
and additional processing.
2023-12-21 10:11:02 -06:00
As discussed in the [Building](#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.
2019-07-11 13:45:17 -05:00
2023-12-21 10:11:02 -06:00
You can build and release everything with:
2025-10-28 15:55:25 -04:00
2023-12-21 10:11:02 -06:00
` ``shell
./go all:release
2019-07-11 13:45:17 -05:00
` ``
2023-12-21 10:11:02 -06:00
To build and release a specific language:
2025-10-28 15:55:25 -04:00
2023-12-21 10:11:02 -06:00
` ``shell
./go <language>:release
` ``
2019-07-11 13:45:17 -05:00
2023-12-21 10:11:02 -06:00
If you have access to the Selenium EngFlow repository, you can have the assets built remotely and downloaded locally using:
2025-10-28 15:55:25 -04:00
2023-12-21 10:11:02 -06:00
` ``shell
./go all:release['--config', 'release']
` ``
