Build Instructions

Build Instructions

Prerequisites

For all versions of WebDriver:

• The Java JDK 11 or more recent. We suggest the most recent OpenJDK LTS version if it's not already on your computer.
• The source code can be forked and/or cloned from the GitHub repository. Note that the repository is several gigabytes, so if you are space or bandwidth limited consider making a shallow clone.
• Bazelisk. On macOS you can do this using homebrew: brew tap bazelbuild/tap && brew unlink bazel; brew install bazelbuild/tap/bazelisk

In addition, the InternetExplorerDriver needs some additional components and can only be fully built on Windows

• Visual Studio 2017 Professional or higher.
• "msbuild" should be on the PATH. This is most easily done by starting the "Visual Studio 2010 Command Prompt" from the Start menu.

Python builds will also need tox installed.

The build is based on rake, a well-known Ruby build tool. Provided you have all the gems required you can use that for building the project, though this isn't the recommended way to build. The bundled JRuby jar, invoked through the "go" wrapper, includes all dependencies without requiring any extra setup.

Build Systems

Selenium is in the process of migrating to a new build system (bazel), but this process is not yet complete, and we haven't integrated this into the existing rake-based solution we use. Consequently, you will occasionally need to issue bazel commands directly.

Building

Check that you're ready to build code by running bazel build grid. You will need to be connected to the Net at this point, because bazel will download some necessary components. If the build is successful, you can run the standalone selenium server using java -jar bazel-bin/java/server/src/org/openqa/selenium/grid/selenium_server_deploy.jar standalone

More typically, we use the go script in the root of the project to run our builds. For Ruby and Python, "go" is the tool to use. For other languages, bazel should be used for now.

The build script will determine which parts of WebDriver will be built. When there are native components that must be built, the build file will attempt to construct them before falling back to prebuilt binaries. Assuming you have checked out the source to $WEBDRIVER_HOME, now:

cd $WEBDRIVER_HOME   # Where the top level Rakefile is kept
go  
# or, on a UNIX system: 
./go

This will not only compile the source, but will also run any tests which need to be run. If these all pass, then you have successfully built WebDriver!

There are more detailed instructions about how the build system works in the CrazyFunBuild section.

By default, the output of the build is somewhat terse. A log of the java compilation stages is kept in "build/build_log.xml". You can also get more verbose output by adding "log=true" to the build targets. eg:

./go //java/client/test/org/openqa/selenium/support:large-tests:run log=true

Finally, you can get even more verbose logging by modifying the Rakefile and commenting out the line that reads:

verbose false

The test logs are kept in the "build/test_logs" folder.

Tips

Building Selenium Server

You'll get a long way with just:

bazel build grid

That'll build the standalone "selenium server" jar and (incidentally) the client library too. The build output will tell you where the output files are being placed.

Building the Android Atoms

./go //javascript/android-atoms:atoms

Useful Targets

For Java:

Target	Purpose
bazel build grid	Build the standalone server
bazel test java/client/test/org/openqa/selenium/chrome	Run the chrome tests
bazel test java/client/test/org/openqa/selenium/firefox	Run the firefox tests

For Javascript:

Target	Purpose
bazel run javascript/atoms:test_debug_server	Run a server on http://localhost:2310/filez for iterative JS development
bazel run javascript/atoms:test-chrome	Run the JS atoms tests for Chrome
bazel run javascript/atoms:test-firefox	Run the JS atoms tests for Firefox

Archived Instructions

All of these should be run using the "go" executable, when we re-integrate the build systems.

For everything:

Target	Purpose
clean	Delete all built artefacts

For Java:

Target	Purpose
test_java	Run every applicable Java test
test_htmlunit	Run all the HtmlUnitDriver tests
test_ie	Run all the InternetExplorerDriver tests
test_firefox	Run all the FirefoxDriver tests
selenium-server-standalone	Build the standalone server
//java/client/test/org/openqa/selenium:single:run	Run the SingleTestSuite

Useful parameters:

Parameter	Purpose	Example
haltonerror	This flag indicates if "go" should halt at an error. Default is true.	./go test_firefox haltonerror=false
haltonfailure	This flag indicates if "go" should halt at a failure. Default is true.	./go test_firefox haltonfailure=false
method	If set, only the specified test will be executed.	./go test_firefox method=testDoubleClick
onlyrun	If set, only tests in the specified class will be executed.	./go test_firefox onlyrun=XPathElementFindingTest
log	This flag indicates logging (e.g. test result streaming) should be dumped to the console, not just files. Default is false.	go test_firefox log=true
suspend	If set, suspends the JVM until a debugger connects before running tests. Useful in conjunction with debug. Default is false.	./go test_firefox suspend=true debug=true
debug	Enable the java remote debugger when starting JVMs for tests. Useful in conjunction with suspend. Default is false. Default debugger port is 5005.	./go test_firefox suspend=true debug=true
offline	If set, don't try to download any components from the internet (e.g. the gecko sdk). Default is false.	./go test_firefox offline=true
leaverunning	If set the browser window will not be closed after the last test.	./go test_firefox leaverunning=true
headless	Only applies to the android emulator. If set, the android emulator window will not be opened (and so the test run will not require an X display)	./go test_android headless=true

For Javascript:

Target	Purpose
//jsapi:debug:run	Run the test server (useful for working)
calcdeps	Recalculate dependencies once a goog.provide or goog.require changes

Common Problems

Nothing Compiles

Make sure that you've got the JAVA_HOME environment setting properly set up. In addition, make sure that you can execute "java", "jar" and "javac" from the command line. If you're on Windows, you'll also need to be able to execute "devenv". You may need to install a JDK. If a C++ component doesn't build properly on Windows, make sure that you are actually using the VS2017 version of msbuild (this might not be the case, even if you're in a VS2017 Command Prompt). If a C++ component doesn't build properly on macOS, make sure XCode is updated and run bazel clean --expunge before retrying.

I've Followed the Steps and All the Tests Fail

Other things to check:

• All the browsers need the correct vendor-supported driver (eg. geckodriver, chromedriver, MS WebDriver) on the $PATH
• The driver assumes that browsers are installed in the default locations for your OS.
• On some platforms such as Linux, Firefox is started with a shell script. There have been reports that if your installation of Firefox wraps this shell script with another one the FirefoxDriver won't work properly. Consider calling the original Firefox script.