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.
Please read CONTRIBUTING.md
before submitting your pull requests.
Requirements
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 and jar on the $PATH (make sure you use java executable from JDK but not 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.
Install the latest version of Xcode including the command-line tools. This command should work xcode-select --install
Apple Silicon Macs should add build --host_platform=//:rosetta to their .bazelrc.local file. We are working
to make sure this isn't required in the long run.
Windows users:
Latest version of Visual Studio with command line tools and build tools installed
BAZEL_VS environment variable should point to the location of the build tools,
e.g. C:\Program Files (x86)\Microsoft Visual Studio\2019\BuildTools
BAZEL_VC environment variable should point to the location of the command line tools,
e.g. C:\Program Files (x86)\Microsoft Visual Studio\2019\Community\VC
BAZEL_VC_FULL_VERSION environment variable should contain the version of the installed command line tools,
e.g. 14.27.29110
A detailed setup guide can be seen on Jim Evan's post
If the Jim's blog instructions were followed, also make sure C:\tools\msys65\usr\bin is on the PATH.
Internet Explorer Driver
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.
Building
Bazel
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.
More detailed instructions for getting Bazel running are below, but if you can successfully get
the java and javascript folders to build without errors, you should be confident that you have the
correct binaries on your system.
Before Building
Ensure that you have Firefox installed and the latest
geckodriver on your $PATH.
You may have to update this from time to time.
Common Build Targets
Java
Click to see Java Build Steps
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>
The 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.
The 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.
JavaScript
Click to see JavaScript Build Steps
If you want to build all the JavaScript code you can run:
bazel build javascript/...
To build the NodeJS bindings you will need to run:
bazel build //javascript/node/selenium-webdriver
To run the tests run:
bazel test //javascript/node/selenium-webdriver:tests
You can pass in the environment variable SELENIUM_BROWSER with the name of the browser.
To publish to NPM run:
bazel run //javascript/node/selenium-webdriver:selenium-webdriver.publish
Python
Click to see Python Build Steps
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.
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:
bazel test javascript/atoms:test
In this case, javascript/atoms is the module directory,
test is a target in that directory's BUILD.bazel file.
As you see build targets scroll past in the log,
you may want to run them individually.
Build Output
bazel makes a top-level group of directories with the bazel- prefix on each directory.
Common Tasks (Bazel)
To build the bulk of the Selenium binaries from source, run the
following command from the root folder:
bazel build java/... javascript/...
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 --test_size_filters option:
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
Editing Code
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 :)
Tour
The codebase is generally segmented around the languages used to
write the component. Selenium makes extensive use of JavaScript, so
let's start there. First of all, start the development 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.
Help with go
More general, but basic, help for go…
./go --help
go is a wrapper around
Rake, so you can use the standard
commands such as rake -T to get more information about available
targets.
Maven per se
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.
./go maven-install
The maven jars should now be in your local ~/.m2/repository.
Updating Java dependencies
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:
(Optional) If we want to detect the dependencies which are not updated,
we can use the following command for automatic discovery:
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:
REPIN=1 bazel run @unpinned_maven//:pin
(Optional) If we use IntelliJ with the Bazel plugin, we need to synchronize
our project. To that aim, we click on Bazel → Sync → Sync Project
with BUILD Files.
Running browser tests on Linux
In order to run Browser tests, you first need to install the browser-specific drivers,
such as geckodriver,
chromedriver, or
edgedriver.
These need to be on your PATH.
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.
Run the X server Xvfb :99 or Xnest :99
Run a window manager, for example, DISPLAY=:99 jwm
Run the tests you are interested in:
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 --run_under
functionality:
bazel test --run_under="xvfb-run -a" //java/... --test_tag_filters=chrome
Bazel Installation/Troubleshooting
Selenium Build Docker Image
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.
MacOS
bazelisk
Bazelisk is a Mac-friendly launcher for Bazel. To install, follow these steps:
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:
xcode-select -p
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.
请发表评论