Use WebPageTest API for Automated Performance Testing

Understanding the WebPageTest REST API

Web performance directly impacts user experience, search engine rankings, and conversion rates. While the WebPageTest web interface provides an excellent visual way to analyze website speed, the WebPageTest API enables developers to integrate performance testing directly into their development workflows, CI/CD pipelines, and monitoring systems. This programmatic approach allows for automated, consistent performance measurement at scale.

The WebPageTest API is a RESTful interface that accepts commands through POST and GET requests to the WebPageTest server. Through this API, you can programmatically run performance tests, check test status, retrieve results, and configure test parameters--all without interacting with the web interface. This automation capability transforms performance testing from a manual, occasional task into a continuous, integrated part of your development process.

The primary API endpoint is https://www.webpagetest.org/runtest.php, which handles test submissions. When you submit a test through the API, you receive a response containing a testId that uniquely identifies your test run. You use this testId to check the test status and retrieve results from additional endpoints. This design allows you to submit tests asynchronously and poll for completion, which is essential for integrating with automated workflows where you need to run tests without blocking execution.

The API supports multiple response formats, including JSON and XML. JSON is generally preferred for programmatic use because it integrates seamlessly with modern programming languages and makes it easy to extract specific values from responses.

Authentication Requirements

The WebPageTest public instance requires API key authentication for all test submissions. You obtain an API key by creating a free account on the WebPageTest website. Once logged in, you can generate API keys from your account settings. These keys are tied to your account and are used to track your API usage and ensure fair access to the public testing infrastructure.

Authentication is performed by including your API key in the HTTP header of your requests. The specific header name is X-WPT-API-KEY, and you set its value to your personal API key. This approach keeps your API key out of URL parameters and logs, reducing the risk of accidental exposure.

Running Tests Programmatically

Running a test through the API involves sending a POST or GET request to the runtest.php endpoint with the URL you want to test and any optional configuration parameters. The API accepts numerous parameters that control virtually every aspect of how the test is executed, from the testing location and browser to network conditions and custom headers.

The most basic test submission requires only the URL parameter. When you submit a test, the API immediately returns a response with a testId and status information. If the test is accepted and queued for execution, the response indicates this with a status code. You then use the testId to check progress and retrieve results when the test completes.

Essential Test Parameters

Beyond the required URL parameter, several configuration options are essential for meaningful automated testing:

• location: Specifies where the test should run from geographically and which browser to use. Locations are specified in the format location:browser.connectivity. For example, ec2-us-east-1:Chrome.Cable runs a test from an AWS EC2 instance in Virginia using Chrome on a cable modem connection.

• runs: Controls how many times the test executes. Multiple runs help account for variability in performance testing. The API allows up to 9 runs on the public instance, with 3 runs being a common choice that balances statistical significance with testing time.

• fvonly: When set to 1, skips the Repeat View test that normally loads the page a second time to measure caching behavior. For quick smoke tests, this reduces testing time.

• video: When set to 1, captures video frames during page loading. Video capture is required for calculating the Speed Index metric and enables the filmstrip view that shows how the page renders over time.

Example: Running a comprehensive test

curl --request POST \
 --url "https://www.webpagetest.org/runtest.php?url=https://example.com&location=Dulles:Chrome.Cable&runs=3&fvonly=0&video=1&f=json" \
 --header "X-WPT-API-KEY: YOUR_API_KEY"

When you submit a test successfully, the API returns a JSON response containing your testId. This identifier is crucial for all subsequent interactions with your test, from checking status to retrieving results. Store this value securely in your automation scripts.

Checking Test Status and Retrieving Results

After submitting a test, you need to monitor its progress until completion. The API provides a dedicated endpoint for checking test status: https://www.webpagetest.org/testStatus.php. You call this endpoint with your testId as a parameter to receive status information without retrieving the full results.

The status response includes information about the test's current state--whether it's queued, in progress, or complete. Status codes in the 1xx range indicate that the test is not yet ready, while a status code of 200 indicates the test is complete and results are available. If there's an error with the test, the response includes an error message explaining what went wrong.

Polling for status is a common pattern in API integration. Your code submits a test, saves the testId, then enters a loop that periodically checks the status endpoint. Between checks, you typically wait 5-10 seconds to avoid overwhelming the API. Once the status indicates completion, you proceed to retrieve the full results.

Key Performance Metrics Returned

The results object includes page-level metrics that measure different aspects of page loading and user-perceived performance:

• TTFB (Time to First Byte): Measures how long the server takes to begin sending content after receiving the request. This metric reflects server responsiveness and can indicate slow database queries, inefficient server-side code, or network latency.

• FCP (First Contentful Paint): Marks when the first piece of content--text, image, or canvas--becomes visible to the user. This metric indicates when the user sees something meaningful, making it a key indicator of perceived load time.

• LCP (Largest Contentful Paint): Identifies when the largest content element in the viewport finishes rendering. This Core Web Vital metric directly correlates with user satisfaction, as it represents when the main page content is available. For comprehensive SEO optimization, optimizing LCP is essential for both user experience and search rankings.

• Speed Index: Measures how quickly page content becomes visually complete, expressed as a score where lower is better. It considers not just when elements appear, but how much of the page is visible at each point during loading.

• TBT (Total Blocking Time): Measures how long the main thread is blocked by JavaScript execution, preventing user interaction. High TBT indicates excessive JavaScript that delays the page from becoming responsive.

Once a test completes, you retrieve the comprehensive results from the jsonResult.php endpoint. The results object contains all performance metrics along with detailed information about each network request made during page loading.

Integrating with CI/CD Pipelines

Automating performance testing within your continuous integration and deployment pipeline ensures that performance regressions are caught before they reach production. The WebPageTest API integrates well with popular CI/CD systems, allowing you to run tests automatically on code changes.

A common pattern is to trigger a WebPageTest run as part of your build process, then compare results against a performance budget or previous baseline. If metrics exceed thresholds or show significant regression, the build can fail with actionable feedback about what changed.

Many teams run tests against staging environments rather than production, testing each deployment before it goes live. Others run tests against production continuously, monitoring performance over time and alerting on significant changes. The API supports both approaches, with the choice depending on your workflow and risk tolerance.

Common Integration Patterns

1. Deploy-to-Staging Testing: Run WebPageTest automatically when deploying to staging environments
2. Performance Budget Enforcement: Fail builds when metrics exceed defined thresholds
3. Trend Monitoring: Track performance metrics over time to identify gradual degradation
4. Baseline Comparison: Compare new builds against historical performance baselines

Example: Performance budget check in GitHub Actions

- name: Check performance budget
 run: |
 results=$(curl "https://www.webpagetest.org/jsonResult.php?test=${{ env.TEST_ID }}")
 lcp=$(echo $results | jq -r '.data.average.firstView.LargestContentfulPaint')
 if [ "$lcp" -gt 2500 ]; then
 echo "LCP ($lcp ms) exceeds budget of 2500 ms"
 exit 1
 fi

By integrating automated performance testing into your CI/CD workflow, you ensure consistent performance monitoring without manual intervention. Establish effective automated performance testing practices to get reliable, actionable results without overwhelming testing infrastructure or slowing down development workflows. Combine API-based lab testing with real-user monitoring (RUM) to capture both controlled measurement and actual production experience.

Sources

1. WebPageTest API Reference - Official API documentation with complete endpoint documentation, authentication details, and response formats
2. O'Reilly: Using WebPageTest Chapter 9 - Book chapter covering programmatic API usage
3. DebugBear: WebPageTest Guide - Practical usage guide and metric explanations
4. WebPageTest API Node.js Wrapper - Official Node.js API wrapper with CLI tools