Skip to content


Switch branches/tags

Name already in use

A tag already exists with the provided branch name. Many Git commands accept both tag and branch names, so creating this branch may cause unexpected behavior. Are you sure you want to create this branch?

Latest commit


Git stats


Failed to load latest commit information.
Latest commit message
Commit time
June 1, 2023 11:59
February 16, 2022 14:50
August 19, 2021 08:42
January 27, 2020 13:33
November 2, 2020 08:53
November 2, 2020 08:53
November 2, 2020 08:53
May 20, 2022 13:45
February 8, 2023 15:15


Cross-platform WebPageTest agent


There are separate lines of development under different licenses (pull requests accepted to either):

Supported Platforms/Browsers

  • Chromium-based browsers are the only ones that currently support manipulating requests (changing headers, blocking requests, etc). Firefox and Safari do not currently support capturing response bodies and running optimization checks.
  • All browsers should support basic page loading, scripts, and video capture on all platforms.
  • Traffic-shaping is supported on all platforms.

⚠️ Known Issues

  • Internet Explorer does not support manipulating requests (adding headers, blocking requests, etc)

Linux (with display, or headless with Xvfb)

  • Chrome: Stable, Beta, and Unstable
  • Firefox: Stable and Nightly
  • Opera: Stable, Beta, and Developer
  • Brave: Stable, Beta, Dev, and Nightly
  • Microsoft Edge: Dev
  • Epiphany: Ubuntu 20.04+
  • Vivaldi


  • Chrome: Stable, Beta, Dev and Canary
  • Firefox: Stable, ESR, Developer Edition, Beta, and Nightly
  • Microsoft Edge: Legacy and Chromium-based
  • Internet Explorer
  • Opera: Stable, Beta and Developer
  • Brave: Stable, Beta, Dev and Nightly

MacOS (Intel and Apple Silicon)

  • Chrome: Stable and Canary
  • Firefox: Stable and Nightly
  • Safari: iOS Simulator

Android (requires a tethered host; Raspberry Pi preferred)

  • Chrome (Stable, Beta, Dev, and Canary)
  • Samsung Internet
  • Several browsers run as “black box” tests (single page load, only visual metrics):
    • Chrome (Stable, Beta, Dev and Canary)
    • Samsung Browser
    • Opera
    • Opera Mini
    • UC Browser
    • UC Mini
    • Firefox (Stable and Beta)

Command-line options

Basic agent config

  • -v, -vv, -vvv…: Increase verbosity (specify multiple times for more). -vvvv for full debug output.

  • --name: Agent name (defaults to the machine’s hostname).

  • --exit: Exit after the specified number of minutes. Useful for running in a shell script that does maintenance or periodic updates (like hourly).

  • --dockerized: The agent is running inside a docker container.

  • --ec2: Load config settings from EC2 user data.

  • --gce: Load config settings from GCE user data.

  • --log: Log critical errors to the given file.

  • --noidle: Doesn't wait for system idle at any point.

  • --healthcheckport: HTTP Health check port (defaults to 8889). Set to 0 to disable. Returns 200 if the agent is running and communicating with the server, 503 otherwise.

  • --har : Generate a per-run HAR file as part of the test result (defaults to False).

Video capture/display settings (Linux only)

  • --xvfb: Use an Xvfb virtual display for headless testing.
  • --fps: Video capture frame rate (defaults to 10). Valid range is 1–60.

Server/location configuration

  • --server (required): URL for WebPageTest work. Example:
  • --location (required): Location ID (as configured in the server’s locations.ini).
  • --validcertificate: Validate server certificates (HTTPS server, defaults to False).
  • --key : Location key (if configured in locations.ini).

Traffic-shaping (defaults to host-based)

  • --shaper: Override default traffic shaper. Supported values:
    • none: Disable traffic-shaping (i.e. when you can’t run as root).
    • netem,<interface>: Use NetEm to bridge reverse-tethered traffic (specify outbound interface). Example: --shaper netem,eth0
    • remote,<server>,<down pipe>,<up pipe>: Connect to the remote server over ssh and use preconfigured dummynet pipes. SSH keys for root user should be pre-authorized.
    • chrome: Use Chrome DevTools’s traffic-shaping. Only for Chromium-based browsers, and as a last resort because of inaccuracy.

Android testing

  • --android: Run tests on an attached Android device.
  • --device: Device ID, if more than one Android is attached.
  • --gnirehtet: Use the gnirehtet tool for reverse-tethering. You will need to manually approve the vpn once per mobile device. Valid options are:
    • <external interface>,<dns>: e.g. --gnirehtet eth0,
  • --vpntether: (Android 7+) Use vpn-reverse-tether for reverse-tethering. You will need to manually approve the vpn once per mobile device. Valid options are:
    • <external interface>,<dns>: e.g. --vpntether eth0,
  • --vpntether2 (recommended): Use vpn-reverse-tether v2 for reverse-tethering. You will need to manually approve the VPN once per mobile device. Valid options:
    • <external interface>,<dns>: e.g. --vpntether2 eth0,
  • --simplert: Use SimpleRT for reverse-tethering. The APK should be installed manually (adb install simple-rt/simple-rt-1.1.apk) and tested once manually (./simple-rt -i eth0, then disconnect and re-connect phone) to dismiss any system dialogs. The ethernet interface and DNS server should be passed as options:
    • <interface>,<dns1>: i.e. --simplert eth0,
  • --rndis (deprecated): Enable reverse-tethering over rndis (Android 6+). Valid options:
    • --rndis <ip>/<network>,<gateway>,<dns1>,<dns2>: Static Address. e.g. --rndis,,,
    • --rndis dhcp

Authenticating the agent with the server

  • --username: Username if using HTTP Basic Auth with WebPageTest server.
  • --password: Password if using HTTP Basic Auth with WebPageTest server.
  • --cert: Client certificate if using certificates to authenticate the WebPageTest server connection.
  • --certkey: Client-side private key (if not embedded in the client certificate).

Running tests locally on the command-line

The test result is written as JSON to stdout. If a server, location, and key are provided, then the test will be uploaded to the given WebPageTest server and the test ID returned in the output JSON.

  • --testurl: Test the given URL via the command line (required unless --testspec is provided)
  • --testspec: Path to a full JSON file with test parameters
  • --browser: What browser to test in (can also be specified in the JSON file)
  • --testout: Output format fot the test result. Valid options:
    • id: Test ID (if tests are uploaded to a server/location)
    • url: URL to test result (if tests are uploaded to a server/location)
    • json: JSON-formatted raw test result
  • --testoutdir (optional): Output directory for the raw JSON test results
  • --testruns: Number of runs to test. Defaults to 1.
  • --testrv: Include repeat view (defaults to only testing first view)

Supported features

The following Script Commands are supported on Windows, Linux, Mac, and Android:

  • navigate
  • exec and execAndWait
  • block
  • sleep
  • logData
  • combineSteps
  • setEventName
  • setUserAgent
  • setBrowserSize, setViewportSize, and setDeviceScaleFactor
  • setActivityTimeout and setTimeout
  • blockDomains and blockDomainsExcept
  • setDns and `setDnsName
  • setHeader and addHeader (addHeader add multiple values for the same header, effectively the same as setHeader)
  • resetHeaders
  • setCookie
  • setABM
  • click, clickAndWait, and sendClick
  • selectValue and setValue
  • setInnerHTML and setInnerText
  • submitForm
  • overrideHost


There are no plans to implement the following Script Commands:

  • sendKeyDown
  • setDOMElement
  • waitForComplete
  • overrideHostUrl
  • ignoreErrors
  • logErrors (TODO: can’t find any mention of this in this GitHub organization?)
  • loadFile
  • loadVariables
  • minInterval
  • endInterval
  • expireCache
  • requiredRequest
  • setDOMRequest
  • waitForJSDone (change semantics to console.log message)
  • if, else, and endif