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.
Selenium's source code is made available under the Apache 2.0 license.
Please read CONTRIBUTING.md before submitting your pull requests.
.bazelversionfile and transparently passes through all command-line arguments to the real Bazel binary.
$PATH(make sure you use
javaexecutable from JDK but not 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.
pip install tox
build --host_platform=//:rosettato their
.bazelrc.localfile. We are working to make sure this isn't required in the long run.
BAZEL_VSenvironment variable should point to the location of the build tools, e.g.
C:\Program Files (x86)\Microsoft Visual Studio\2022\BuildTools
BAZEL_VCenvironment variable should point to the location of the command line tools, e.g.
C:\Program Files (x86)\Microsoft Visual Studio\2022\Community\VC
BAZEL_VC_FULL_VERSIONenvironment variable should contain the version of the installed command line tools, e.g.
C:\tools\msys65\usr\binis on the
If you plan to compile the IE driver, you also need:
The build will work on any platform, but the tests for IE will be skipped silently if you are not building on Windows.
GitPod provides a ready to use environment to develop.
To configure and use your local machine, keep reading.
Bazel was built by the fine folks at Google. Bazel manages dependency downloads, generates the Selenium binaries, executes tests, and does it all rather quickly.
Ensure that you have Firefox installed and the latest
geckodriver on your
$PATH. You may have to update this from time to time.
To build the most commonly-used modules of Selenium from source, execute this command from the root project folder:
bazel build java/...
If you want to test you can run then you can do so by running the following command
bazel test //java/... --test_size_filters=small,medium,large --test_tag_filters=<browser>
test_size_filters argument takes small, medium, large. Small are akin to unit tests, medium is akin to integration tests, and large is akin to end-to-end tests.
test_tag_filters allow us to pass in browser names and a few different tags that we can find in the code base.
To build the Grid deployment jar, run this command:
bazel build grid
The log will show where the output jar is located.
To build the NodeJS bindings you will need to run:
To run the tests run:
You can pass in the environment variable
SELENIUM_BROWSER with the name of the browser.
To publish to NPM run:
If you want to build the python bindings run:
bazel build //py:selenium
To run the tests run:
bazel test //py:test-<browsername>
If you add
--//common:pin_browsers it will download the browsers and drivers for you to use.
To install locally run:
bazel build //py:selenium-wheel pip install bazel-bin/py/selenium-*.whl
To publish run:
bazel build //py:selenium-wheel //py:selenium-sdist twine upload bazel-bin/py/selenium-*.whl bazel-bin/py/selenium-*.tar.gz
To build the Ruby code run:
bazel build //rb/...
To run unit tests:
bazel test --cache_test_results=no --test_output=all //rb:unit-test
To run tests on a browser:
bazel test --cache_test_results=no --test_output=all //rb:<browsername>-test
To run remote tests on a browser:
bazel test --cache_test_results=no --test_output=all //rb:remote-<browsername>-test
To run a particular test on a browser:
bazel test --cache_test_results=no --test_output=all --test_arg="-e<Test_Target>" //rb:<browsername>-test
Optional Environment Variable toggles in test suite:
ENV['WD_SPEC_DRIVER']- the driver to test; either the browser name or ‘remote’ (gets set by Bazel)
ENV['WD_REMOTE_BROWSER']- when ‘WD_SPEC_DRIVER’ is ‘remote’; the name of the browser to test (gets set by Bazel)
ENV['WD_REMOTE_URL']- url of an already running server to use for remote tests
WD_REMOTE_URLnot set; whether to download and use most recently released server version for remote tests
ENV['DEBUG']- turns on verbose debugging
ENV['HEADLESS']- for chrome, edge and firefox; runs tests in headless mode
ENV['DISABLE_BUILD_CHECK']- for chrome and edge; whether to ignore driver and browser version mismatches (allows testing Canary builds)
ENV['CHROME_BINARY']- path to test specific Chrome browser
ENV['EDGE_BINARY']- path to test specific Edge browser
ENV['FIREFOX_BINARY']- path to test specific Firefox browser
If you want to use RubyMine for development, a bit of extra configuration is necessary to let the IDE know about Bazel toolchain and artifacts:
bazel build @bundle//:bundle //rb:selenium-devtools //rb:selenium-webdriverbefore configuring IDE.
rb/as a main project directory.
-I ../bazel-bin/rb/libto Ruby arguments.
Bazel can not build .NET, yet, but it can set up tests with:
bazel build //dotnet/test/common:chrome
Tests can then be run with:
cd dotnet dotnet test
More information about running Selenium's .NET tests can be found in this README.md
Bazel files are called BUILD.bazel, and the order the modules are built is determined by the build system. If you want to build an individual module (assuming all dependent modules have previously been built), try the following:
In this case,
test is a target in that directory's
As you see build targets scroll past in the log, you may want to run them individually.
bazel makes a top-level group of directories with the
bazel- prefix on each directory.
To build the bulk of the Selenium binaries from source, run the following command from the root folder:
To run tests within a particular area of the project, use the “test” command, followed by the folder or target. Tests are tagged with “small”, “medium”, or “large”, and can be filtered with the
bazel test --test_size_filters=small,medium java/...
Bazel's “test” command will run all tests in the package, including integration tests. Expect the
test java/... to launch browsers and consume a considerable amount of time and resources.
To bump the versions of the pinned browsers to their latest stable versions:
bazel run scripts:pinned_browsers > temp.bzl && mv temp.bzl common/repositories.bzl
Most of the team use either Intellij IDEA or VS.Code 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.
If you do use IntelliJ and the Bazel plugin, there is a project view checked into the tree in scripts/ij.bazelproject which will make it easier to get up running, and editing code :)
bazel run debug-server
The tests in this directory are normal HTML files with names ending with
_test.html. Click on one to load the page and run the test.
More general, but basic, help for
go is a wrapper around Rake, so you can use the standard commands such as
rake -T to get more information about available targets.
Selenium is not built with Maven. It is built with
bazel, though that is invoked with
go as outlined above, so you do not have to learn too much about that.
That said, it is possible to relatively quickly build Selenium pieces for Maven to use. You are only really going to want to do this when you are testing the cutting-edge of Selenium development (which we welcome) against your application. Here is the quickest way to build and deploy into your local maven repository (
~/.m2/repository), while skipping Selenium's own tests.
The maven jars should now be in your local
The coordinates (groupId:artifactId:version) of the Java dependencies are defined in the file maven_deps.bzl. The process to modify these dependencies is the following:
bazel run @maven//:outdated
Modify maven_deps.bzl. For instance, we can bump the version of a given artifact detected in the step before.
Repin dependencies. This process is required to update the file maven_install.json, which is used to manage the Maven dependencies tree (see rules_jvm_external for further details). The command to carry out this step is the following:
RULES_JVM_EXTERNAL_REPIN=1 bazel run @unpinned_maven//:pin
In order to run Browser tests, you first need to install the browser-specific drivers, such as
edgedriver. These need to be on your
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.
bazel 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
bazel test --run_under="xvfb-run -a" //java/... --test_tag_filters=chrome
If you're finding it hard to set up a development environment using bazel and you have access to Docker, then you can build a Docker image suitable for building and testing Selenium in from the Dockerfile in the dev image directory.
Bazelisk is a Mac-friendly launcher for Bazel. To install, follow these steps:
brew tap bazelbuild/tap && \ brew uninstall bazel; \ brew install bazelbuild/tap/bazelisk
If you‘re getting errors that mention Xcode, you’ll need to install the command-line tools.
Bazel for Mac requires some additional steps to configure properly. First things first: use the Bazelisk project (courtesy of philwo), a pure golang implementation of Bazel. In order to install Bazelisk, first verify that your Xcode will cooperate: execute the following command:
If the value is
/Applications/Xcode.app/Contents/Developer/, you can proceed with bazelisk installation. If, however, the return value is
/Library/Developer/CommandLineTools/, you'll need to redirect the Xcode system to the correct value.
sudo xcode-select -s /Applications/Xcode.app/Contents/Developer/ sudo xcodebuild -license
The first command will prompt you for a password. The second step requires you to read a new Xcode license, and then accept it by typing “agree”.
(Thanks to this thread for these steps)