Repository files navigation

Contributing •Installing •Building •Developing •Testing •Documenting •Releasing •License

Selenium is an umbrella project encapsulating a variety of tools andlibraries enabling web browser automation. Selenium specificallyprovides an infrastructure for theW3C WebDriver specification— a platform and language-neutral coding interface compatible with allmajor web browsers.

The project is made possible by volunteer contributors who'vegenerously 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 outourUser Manual for detailed examples and descriptions, and if youget stuck, there are several ways toGet Help.

Please readCONTRIBUTING.mdbefore submitting your pull requests.

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

• Bazelisk, a Bazel wrapper that automatically downloadsthe version of Bazel specified in.bazelversion file and transparently passes through allcommand-line arguments to the real Bazel binary.
• Java JDK version 17 or greater (e.g.,Java 17 Temurin)
  • SetJAVA_HOME environment variable to location of Java executable (the JDK not the JRE)
  • To test this, try running the commandjavac. This command won't exist if you only have the JREinstalled. If you're met with a list of command-line options, you're referencing the JDK properly.

• Xcode including the command-line tools. Install the latest version using:xcode-select --install
• Rosetta for Apple Silicon Macs. Addbuild --host_platform=//:rosetta to the.bazelrc.local file. We are workingto make sure this isn't required in the long run.

Several years agoJim Evans published a great article onSetting 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.

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.

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

As an alternative you can build aDev 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 IDEAshould point you to how such a container can be created.

You can also build a Docker image suitablefor building and testing Selenium using the Dockerfile in thedev image directory.

Selenium is built using a common build tool calledBazel, toallow 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 onBuilding Selenium

Often we wrap Bazel commands with our customRake 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 aBUILD.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 namedexecutable-grid and it isdefined 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 ahandy guidefor 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'reworking in IntelliJ, then we highly recommend installing theBazel IJplugin which is documented onits own site.

To use Selenium with the IntelliJ Bazel plugin, import the repository as a Bazel project, and select the projectview file from thescripts directory.ij.bazelproject for Mac/Linux andij-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 theirconfiguration 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 piecesfor Maven to use locally by deploying to your local maven repository (~/.m2/repository), using:

./go java:install

Dependencies are defined in the fileMODULE.bazel.To automatically update and pin new dependencies, run:

./go java:update

We follow thePEP8 Style Guide for Python Code (except we use a 120 character line length).This is checked and enforced with several linting tools, includingblack,docformatter,flake8,andisort.

To run all of the linting tools:

./go py:lint

You needtox installed to run the linting tools (pip install tox).

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 thepy 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 Pythonsite-packages directory,which might not be writable. To avoid this, you should create and activate avirtual environmentbefore installing.

Instead of usingirb, 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 viadebug gem:

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

bazel-selenium/external/bundle/bin/rdbg -A

If you want to useRubyMine for development,you can configure it use Bazel artifacts:

1. Openrb/ as a main project directory.
2. Runbundle exec rake update as necessary to create up-to-date artifacts. If this does not work, run./go rb:update from theselenium (parent) directory.
3. InSettings / Languages & Frameworks / Ruby SDK and Gems add newInterpreter pointing to../bazel-selenium/external/rules_ruby_dist/dist/bin/ruby.
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 secified inRuby Testing section below.

To keepCarbo.Bazel.lock synchronized withCargo.lock, run:

CARGO_BAZEL_REPIN=true bazel sync --only=crates

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 - run specific browser versions defined in the build (versions are updated regularly)
• --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 execution

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 thetest_size_filters argument like this:

bazeltest //<language>/... --test_size_filters=small

Tests can also be filtered by tag like:

bazeltest //<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

bazeltest //java/... --test_size_filters=small

bazeltest //java/... --test_size_filters=medium

bazeltest //java/... --test_size_filters=large --test_tag_filters=<browser>

bazeltest //java/test/org/openqa/selenium/chrome:ChromeDriverFunctionalTest

bazeltest //javascript/selenium-webdriver:tests

bazeltest //javascript/selenium-webdriver:tests --test_env=SELENIUM_BROWSER=firefox

bazeltest //py:unit

bazeltest //py:common-<browsername>

bazeltest //py:common-<browsername>-bidi

bazeltest //py:test-<browsername>

bazeltest //py:all

echo'<X.Y.Z>'> rb/.ruby-version

bazeltest //dotnet/test/common:AllTests --pin_browsers=true

bazeltest //dotnet/test/common:ElementFindingTest --pin_browsers=true

bazeltest //dotnet/test/common:ElementFindingTest-edge --pin_browsers=true

bazeltest //rust/...

bazeltest --test_env=DISPLAY=:99 //java/... --test_tag_filters=chrome

bazel test --run_under="xvfb-run -a" //java/...

API documentation can be found here:

• C#
• JavaScript
• Java
• Python
• Ruby

To update API documentation for a specific language:./go <language>:docs

To update all documentation:./go all:docs

Note that JavaScript generation iscurrently broken.

The full process for doing a release can be found inthe wiki

Releasing is a combination of building and publishing, which often requires coordination of multiple executionsand additional processing.As discussed in theBuilding 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']

Selenium's source code is made available under theApache 2.0 license.