`wptagent`

Cross-platform WebPageTest agent

🥡 Installation instructons
🐋 Docker instructions

Contributing

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

The master branch where most active development occurs has the Polyform Shield 1.0.0 license
The apache branch has the more permissive Apache 2.0 license

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

Windows

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: https://www.webpagetest.org/work/.
--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,8.8.8.8
--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,8.8.8.8
--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,8.8.8.8
--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,8.8.8.8
--rndis (deprecated): Enable reverse-tethering over rndis (Android 6+). Valid options:
- --rndis <ip>/<network>,<gateway>,<dns1>,<dns2>: Static Address. e.g. --rndis 192.168.0.8/24,192.168.0.1,8.8.8.8,8.8.4.4
- --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.

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

Unsupported

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

License

HTTPArchive/wptagent

ErrorLooks like something went wrong!

About

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Languages

Error
Looks like something went wrong!

Packages