WebPageTest Advanced Usage: Custom Scripts and Analysis
WebPageTest occupies a unique position in the web performance tooling ecosystem. Unlike Lighthouse, which runs in a simulated environment with modeled throttling, WebPageTest executes tests on real browsers running on real hardware at real network locations worldwide. This distinction matters because real-device testing captures performance characteristics that simulation cannot replicate: actual network jitter, genuine CPU thermal throttling, and authentic browser rendering behavior under constrained resources.
Most engineers use WebPageTest for basic single-URL testing — paste a URL, select a location, wait for results. But the platform's real power lies in its scripted testing capabilities, custom metric extraction, filmstrip comparison analysis, and API-driven automation. This guide covers the advanced features that transform WebPageTest from a one-off diagnostic tool into a systematic performance measurement platform.
Scripted Multi-Step Testing
WebPageTest's scripting language enables multi-step user journey testing that measures performance across complete workflows rather than isolated page loads. Scripts use a line-by-line command syntax that controls navigation, form input, clicks, and timing measurement.
Script Syntax and Commands
Scripts consist of sequential commands, each on its own line. The most commonly used commands are navigate, click, setValue, exec, and waitFor. The logData command controls which steps contribute to the final report — set logData 0 for setup steps and logData 1 for the step you want to measure.
// Login flow: measure dashboard load after authentication
logData 0
// Step 1: Navigate to login page (not measured)
navigate https://app.example.com/login
// Step 2: Enter credentials
setValue name=email testuser@example.com
setValue name=password perf-test-2026
// Step 3: Submit login form
click id=login-button
// Wait for redirect to complete
waitForComplete
logData 1
// Step 4: Navigate to dashboard (THIS is measured)
navigate https://app.example.com/dashboardAdvanced Scripting Patterns
Conditional navigation: Use exec to run arbitrary JavaScript on the page, checking conditions before proceeding. This handles dynamic content like cookie consent banners, A/B test variants, or modal dialogs that appear inconsistently.
// Dismiss cookie banner if present, then measure page
navigate https://www.example.com
exec if(document.querySelector('.cookie-banner')) { document.querySelector('.cookie-accept').click(); }
sleep 2
logData 1
navigate https://www.example.com/product/12345SPA navigation measurement: Single-page applications do not trigger traditional page load events on navigation. Use exec combined with waitFor to measure client-side route transitions by waiting for specific DOM elements that indicate the target view has rendered.
API pre-warming: Some tests need specific server-side state. Use exec with fetch() to call API endpoints that seed test data or warm caches before the measured navigation begins. This isolates frontend performance from backend state variability.
Custom Metrics
WebPageTest's custom metrics feature lets you extract application-specific timing data that standard metrics do not capture. Custom metrics execute JavaScript snippets after page load completes and record the returned values alongside standard metrics in the results.
[hero-image-loaded]
return performance.getEntriesByName(
document.querySelector('.hero img')?.src
)[0]?.responseEnd || 0;
[above-fold-complete]
return Math.max(
...Array.from(document.querySelectorAll('[data-track-lcp]'))
.map(el => {
const entry = performance.getEntriesByName(el.src || el.href);
return entry.length ? entry[0].responseEnd : 0;
})
);
[interactive-widget-ready]
return window.__widgetReadyTimestamp || 0;
[dom-element-count]
return document.querySelectorAll('*').length;
[third-party-request-count]
return performance.getEntriesByType('resource')
.filter(r => !r.name.includes(location.hostname)).length;Custom metrics are particularly valuable for tracking business-relevant performance milestones that do not correspond to any standard web performance metric. An e-commerce site might track "time to product image visible," a news site might track "time to first headline rendered," and a monitoring dashboard might track "time to first chart drawn." These custom timing points often correlate more strongly with business outcomes than generic metrics like LCP.
Filmstrip Analysis
The filmstrip view captures screenshots at 100-millisecond intervals during page load, producing a visual timeline of what the user sees during the loading process. This visual record is invaluable for diagnosing perceived performance issues that metric numbers alone cannot convey.
Visual Progress Calculation
WebPageTest calculates a "Visual Progress" percentage at each filmstrip frame by comparing each frame to the fully-loaded state. A frame that is 50 percent visually complete means half the final pixels are already in place. The Speed Index metric derives from this visual progress curve — it represents the average percentage of visual completeness over time, rewarding pages that show content progressively rather than all at once after a long blank period.
Competitive Filmstrip Comparison
WebPageTest's comparison feature overlays filmstrips from multiple tests side by side. This is the single most effective way to benchmark against competitors. Submit your page and a competitor's page with identical test configuration (same location, same connection type, same browser), then use the visual comparison view to see exactly when each site shows meaningful content.
When presenting filmstrip comparisons to stakeholders, capture the specific frame where a meaningful difference appears. A competitor showing a fully rendered product page at 1.8 seconds while your page still shows a loading spinner at the same timestamp conveys performance impact more effectively than any metric chart. Use the A/B testing approach to validate that visual improvements translate to business metrics.
Connection Throttling and Location Strategy
WebPageTest's distributed test infrastructure spans dozens of locations worldwide, each offering multiple connection profiles. Selecting the right location and connection combination is critical for meaningful results.
Connection Profiles
| Profile | Down (Kbps) | Up (Kbps) | RTT (ms) | Use Case |
|---|---|---|---|---|
| Cable | 5,000 | 1,000 | 28 | Desktop broadband baseline |
| 3G Slow | 400 | 400 | 400 | Emerging market mobile |
| 3G Fast | 1,600 | 768 | 150 | Standard mobile baseline |
| 4G | 9,000 | 9,000 | 170 | Modern mobile |
| LTE | 12,000 | 12,000 | 70 | Urban mobile |
| FIOS | 20,000 | 5,000 | 4 | High-speed broadband |
| Custom | Variable | Variable | Variable | Match your RUM data |
Custom connection profiles should mirror your actual user base. Extract the 75th percentile connection characteristics from your RUM data — effective connection type, round-trip time, and downlink speed — and create a custom profile that matches. Testing against your real user conditions produces actionable results; testing against theoretical profiles produces theoretical improvements.
Test Location Selection
Choose test locations based on where your users are, not where your servers are. If your audience is primarily in Southeast Asia, test from Singapore, Tokyo, or Sydney — not from Virginia. The network latency between test location and your origin server directly impacts TTFB measurements, and testing from nearby locations masks latency issues that distant users experience.
Run the same test from multiple locations to build a geographic performance profile. A site that loads in 1.5 seconds from the US East Coast might take 4.5 seconds from Mumbai if the CDN configuration does not serve the APAC region effectively. This geographic spread reveals CDN coverage gaps and DNS routing issues invisible from a single test location.
API-Driven Automation
The WebPageTest API enables programmatic test execution, result retrieval, and integration with CI/CD pipelines. The RESTful API accepts test configuration as URL parameters or JSON body and returns a test ID that can be polled for results.
# Submit a test via API
curl -X POST "https://www.webpagetest.org/runtest.php" \
-d "url=https://example.com" \
-d "location=Dulles:Chrome" \
-d "connectivity=3GFast" \
-d "runs=5" \
-d "fvonly=1" \
-d "video=1" \
-d "f=json" \
-d "k=YOUR_API_KEY"
# Response includes test ID
# Poll for results:
curl "https://www.webpagetest.org/jsonResult.php?test=TEST_ID"Private Instances
Organizations with high test volumes or security requirements can deploy private WebPageTest instances. A private instance uses the same open-source WebPageTest server code but runs on your own infrastructure with your own test agents. Benefits include unlimited test capacity, testing behind firewalls, custom agent configurations matching your target device fleet, and no API rate limits.
Private instances integrate naturally with internal CI systems. Deploy test agents as Docker containers matching your most common user device profiles, connect them to the WebPageTest server, and run tests against pre-production environments that are not publicly accessible.
Interpreting Results: Beyond the Summary
Waterfall Deep Dive
The WebPageTest waterfall provides richer detail than browser DevTools network waterfalls because it captures data from the network layer rather than the browser API. Each request shows DNS, Connect, TLS, TTFB, and Download phases with precise timing. Color coding distinguishes content types: blue for HTML, green for CSS, orange for JavaScript, purple for images, and gray for fonts.
Key patterns to look for in the waterfall: long green bars on third-party requests indicating slow external dependencies, gaps between request completion and the next request start indicating main-thread blocking, request queuing at the HTTP/1.1 connection limit, and large TTFB bars indicating slow server processing or missing cache layers.
Connection View
The connection view reorganizes the waterfall by TCP connection rather than request order. This reveals connection reuse efficiency, HTTP/2 multiplexing behavior, and connection establishment overhead. Pages making requests to many different domains incur connection establishment costs (DNS + TCP + TLS) for each domain — a pattern that preconnect hints can mitigate but not eliminate.
Optimization Opportunities from WebPageTest
WebPageTest's optimization checklist evaluates specific technical implementations: Keep-alive enabled (connection reuse), Compress Transfer (gzip/brotli on text resources), Compress Images (JPEG quality and modern format usage), Cache Static Content (appropriate cache-control headers), Effective use of CDN (percentage of static resources served from edge), and No 3XX Redirects (redirect chains waste round trips).
Each optimization check is graded A through F. Focus on any grade below B as an immediate improvement opportunity. A "F" on caching means static resources lack Cache-Control headers entirely, leaving hundreds of kilobytes re-downloaded on every visit. A "D" on image compression means images could be 30 to 50 percent smaller without visible quality loss.
Cross-reference these findings with performance budgets to prioritize which optimizations deliver the most impact within your specific constraints and audience profile.