Source code
Revision control
Copy as Markdown
Other Tools
# Detection and Installation of Browser and WebDriver Binaries and for Chrome and Chromium
This is a detailed description of the process in which WPT detects and installs the browser
components for Chrome and Chromium. This process can seem convoluted and difficult to
understand at first glance, but the reason for this process is to best ensure these components
are compatible with each other and are the intended items that the user is trying to test.
## Chrome
### Detection
**Browser**: Because WPT does not offer installation of Chrome browser binaries, it will
not attempt to detect a Chrome browser binary in the virtual environment directory.
Instead, commonly-used installation locations on various operating systems are checked to
detect a valid Chrome binary. This detection process is only used if the user has not passed
a binary path as an argument using the `--binary` flag.
**WebDriver**: ChromeDriver detection for Chrome will only occur if a valid browser binary
has been found. Once the browser binary version is detected, the virtual environment
directory will be checked to see if a matching ChromeDriver version is already installed.
If the browser and ChromeDriver versions do not match, the ChromeDriver binary will be
removed from the directory and the user will be prompted to begin the webdriver installation
process. A ChromeDriver version is considered matching the browser version if ChromeDriver shares
the same major version, or next major version when testing Chrome Dev. For example, Chrome 98.x.x.x
is considered to match ChromeDriver version 98.x.x.x, or also ChromeDriver 99.x.x.x if testing
Chrome Dev.
Note: Both Chrome and Chromium’s versions of ChromeDriver are stored in separate
directories in the virtual environment directory i.e
`_venv3/bin/{chrome|chromium}/{chromedriver}`. This safeguards from accidentally
using Chromium’s ChromeDriver for a Chrome run and vice versa. Additionally, there
is no need to reinstall ChromeDriver versions if switching between testing Chrome and Chromium.
### Installation
**Browser**: Browser binary installation is not provided through WPT and will throw a
`NotImplementedError` if attempted via `./wpt install`. The user will need to
have a browser binary on their system that can be detected or provide a path explicitly
using the `--binary` flag.
**WebDriver**: A version of ChromeDriver will only be installed once a Chrome browser binary
has been given or detected. A `FileNotFoundError` will be raised if the user tries to download
ChromeDriver via `./wpt install` and a browser binary is not located. After browser binary
detection, a version of ChromeDriver that matches the browser binary will be installed.
The download source for this ChromeDriver is
If a matching ChromeDriver version cannot be found using this process, it is assumed that
the Chrome browser binary is a dev version which does not have a ChromeDriver version available
through official releases. In this case, the Chromium revision associated with this version is
Chromium's version of ChromeDriver for use from Chromium snapshots, as this is currently
the closest version we can match for Chrome Dev. Finally, if the revision number detected is
not available in Chromium snapshots, or if the version does not match any revision number,
the latest revision of Chromium's ChromeDriver is installed from Chromium snapshots.
## Chromium
### Detection
**Browser**: Chromium browser binary detection is only done in the virtual
environment directory `_venv3/browsers/{channel}/`, not on the user’s system
outside of this directory. This detection process is only used if the user has
not passed a binary path as an argument using the `--binary` flag.
**WebDriver**: ChromeDriver detection for Chromium will only occur if a valid browser binary has
been found. Once the browser binary version is detected, the virtual environment directory will
be checked to see if a matching ChromeDriver version is already installed. If the versions do not
match, the ChromeDriver binary will be removed from the directory and the user will be prompted to
begin the webdriver installation process. For Chromium, the ChromeDriver and browser versions must be
the same to be considered matching. For example, Chromium 99.0.4844.74 will only match ChromeDriver
99.0.4844.74.
### Installation
**Browser**: Chromium’s browser binary will be installed from
The last revision associated with the user’s operating system will be downloaded
(this revision is obtained by the LAST_CHANGE designation from the snapshots bucket).
Chromium does not have varying channels, so the installation uses the default `nightly`
designation. The install path is `_venv3/browsers/nightly/{chromium_binary}`.
Note: If this download process is successful, the Chromium snapshot URL that the browser
binary was downloaded from will be kept during the current invocation. If a Chromium ChromeDriver
is also downloaded later to match this browser binary, the same URL is used for that download to
ensure both components are downloaded from the same source.
**WebDriver**: A version of ChromeDriver will only be installed once a Chromium browser binary
has been given or detected. A FileNotFoundError will be raised if the user tries to download
ChromeDriver via the install command and a browser binary is not located. A version of
ChromeDriver that matches the version of the browser binary will be installed. The download
source for this ChromeDriver will be the Chromium snapshots. If a Chromium browser
binary and webdriver are installed in the same invocation of `./wpt run`
(for example, by passing both `--install-browser` and `--install-webdriver` flags), then the
browser binary and ChromeDriver will be pulled from the same Chromium snapshots URL (see Note
from browser installation). Although unusual, if a Chromium browser binary is detected and
it is not the tip-of-tree revision and the browser binary was not downloaded and installed
during this invocation of `./wpt run` and the currently installed ChromeDriver version does
not match the browser version, then an attempt will be made to detect the revision number from
and download the matching ChromeDriver using this revision number from Chromium snapshots.