Running Tests from the Local System¶
The tests are designed to be run from your local computer.
If you haven’t already, clone the web-platform-tests repository:
git clone https://github.com/web-platform-tests/wpt.git
Running the tests requires
pip as well as updating the
WPT requires Python 3.7 or higher.
The required setup is different depending on your operating system.
If not already present, use the system package manager to install
sudo apt-get install python3 python3-pip python3-venv
It is important to have a package that provides a
python binary. On Fedora,
for example, that means installing the
python-unversioned-command package. On
Ubuntu Focal and later, the package is called
The system-provided Python can be used, while
pip can be
installed for the user only:
python -m ensurepip --user
export PATH="$PATH:$( python3 -m site --user-base )/bin"
To make the
PATH change persistent, add it to your
~/.bash_profile file or
wherever you currently set your PATH.
See also additional setup required to run Safari.
Download and install Python 3. The
pip by default.
C:\Python39\Scripts to your
The standard Windows shell requires that all
wpt commands are prefixed
by the Python binary i.e. assuming
python is on your path the server is
python wpt serve
Windows Subsystem for Linux¶
Optionally on Windows you can use the Windows Subsystem for
Linux (WSL). If doing so,
installation and usage are similar to the Linux instructions. Be aware that WSL
may attempt to override
/etc/hosts each time it is launched, which would then
require you to re-run
hosts File Setup. This behavior
can be configured.
hosts File Setup¶
To get the tests running, you need to set up the test domains in your
On Linux, macOS or other UNIX-like system:
./wpt make-hosts-file | sudo tee -a /etc/hosts
And on Windows (this must be run in a PowerShell session with Administrator privileges):
python wpt make-hosts-file | Out-File $env:SystemRoot\System32\drivers\etc\hosts -Encoding ascii -Append
If you are behind a proxy, you also need to make sure the domains above are excluded from your proxy lookups.
Via the browser¶
The test environment can then be started using
This will start HTTP servers on two ports and a websockets server on
one port. By default the web servers start on ports 8000 and 8443 and the other
ports are randomly-chosen free ports. Tests must be loaded from the
first HTTP server in the output. To change the ports,
config.json file in the wpt root directory, and add
port definitions of your choice e.g.:
"http": [1234, "auto"],
hosts file is configured, the servers will be locally accessible at:
To use the web-based runner point your browser to:
This server has all the capabilities of the publicly-deployed version–see Running the Tests from the Web.
*See Trusting Root CA
Via the command line¶
Many tests can be automatically executed in a new browser instance using
./wpt run [browsername] [tests]
This will automatically load the tests in the chosen browser and extract the
test results. For example to run the
dom/historical.html tests in a local
copy of Chrome:
./wpt run chrome dom/historical.html
Or to run in a specified copy of Firefox:
./wpt run --binary ~/local/firefox/firefox firefox dom/historical.html
For details on the supported products and a large number of other options for customising the test run:
./wpt run --help
Running in parallel¶
To speed up the testing process, use the
--processes option to run multiple
browser instances in parallel. For example, to run the tests in dom/ with six
Firefox instances in parallel:
./wpt run --processes=6 firefox dom/
But note that behaviour in this mode is necessarily less deterministic than with a single process (the default), so there may be more noise in the test results.
./wpt run outputs test results and a summary in a human readable
format. For debugging,
--log-mach can give more verbose output. (In particular,
it will show the console output from the browser and driver;
by default, those are not shown) For example:
./wpt run --log-mach=- --log-mach-level=info firefox dom/
A machine readable JSON report can be produced using
--log-wptscreenshot is what is used to produce results for
wpt.fyi. For example:
./wpt run --log-wptreport=report.json --log-wptscreenshot=screenshots.txt firefox css/css-grid/
(See wpt.fyi documentation for how results are uploaded.)
For use in continuous integration systems, and other scenarios where regression tracking is required, the command-line interface supports storing and loading the expected result of each test in a test run. See Expectations Data for more information on creating and maintaining these files.
Polyfill scripts can be tested using the
--inject-script argument to either
wpt run or
wpt serve. See Testing Polyfills for