Skip to content

Latest commit

 

History

History
188 lines (146 loc) · 8.49 KB

README.md

File metadata and controls

188 lines (146 loc) · 8.49 KB
Raw

wptagent

Cross-platform WebPageTest agent

Contributing

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

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.

  • --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

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