WebPageTest Complete Guide: Deep Performance Analysis

Navigate to webpagetest.org and paste your URL into the main field. The first decision -- test location -- has the biggest impact on your TTFB results. Choose a location that represents your primary user base. If most of your users are in the US East Coast, use Virginia. For European users, London or Frankfurt. For global analysis, run separate tests from multiple regions and compare the TTFB columns to identify geographic CDN gaps.

For device selection, the default "Desktop" Chrome profile is suitable for understanding your core loading pipeline. However, for a realistic representation of real-world CWV scores, always also test using a mobile emulation profile. WebPageTest's "Motorola G4" or "Moto G (gen 4)" emulation provides CPU throttling that closely matches the mid-range Android device performance the Chrome User Experience Report uses as its baseline for mobile scoring.

Click the Advanced Settings tab to reveal the full configuration panel. The most important settings are connection speed, number of test runs, and repeat view. Use 4G (9 Mbps, 170ms RTT) for mobile tests or Cable (5 Mbps, 28ms RTT) for desktop. These presets match typical field conditions and produce waterfall data that correlates well with real-user CrUX scores.

Set Number of Tests to Run to at least 3. WebPageTest automatically identifies the median run based on SpeedIndex and uses that as the representative result. With 3 runs you discard one outlier; with 5 or 9 runs you get even more stable medians for statistical rigor. Enable First View and Repeat View to see both cold-cache and warm-cache performance in a single test submission.

Test URL:          https://your-site.com/
Test Location:     Virginia, USA -- EC2 (us-east-1)
Browser:           Chrome
Connection:        4G (9 Mbps / 170ms RTT)
Number of Tests:   3
Repeat View:       First View and Repeat View

Advanced:
  Capture Video:      Yes   (required for filmstrip)
  Capture Timeline:   Yes   (required for long-task analysis)
  Block Ads:          No    (test real-world conditions)
  Ignore SSL Errors:  No
  Inject Script:      (leave blank for baseline)
  DNS Override:       (use for staging environment tests)

When the test completes, the results page opens with a row of summary metric cards at the top. These show LCP, CLS, TBT (Total Blocking Time -- a Lighthouse proxy for INP), TTFB, Start Render, Speed Index, and Time to Interactive. Each metric is color-coded green (Good), orange (Needs Improvement), or red (Poor) against the same Core Web Vitals thresholds Google uses.

Below the summary cards you will find a First View vs. Repeat View comparison table. A dramatic improvement in Repeat View LCP (say, 4.2s down to 0.8s) indicates that your images are successfully cached but are not being preloaded for first-time visitors -- a prime candidate for adding rel="preload" or serving from a CDN with proper cache headers. If Repeat View shows little improvement, your caching strategy needs attention.

The waterfall chart is the most diagnostic view in WebPageTest. Each horizontal bar represents a single network request. The bar's left edge marks when the request started; its right edge marks when the response completed. The bar is divided into color-coded segments: DNS lookup (teal), initial connection (orange), SSL negotiation (purple), time to first byte (green), and content download (blue).

The critical elements to identify are: the render-blocking line (a solid vertical blue line where the browser first begins painting), any requests whose bars start before this line and extend significantly into the timeline (these are blocking render), long white gaps between resource bars (indicating main-thread work blocking the network stack), and deep request chains where a late-discovered resource triggers additional fetches that delay LCP.

Click the Filmstrip View tab to see screenshots captured every 100 milliseconds during the page load. The filmstrip is particularly valuable for diagnosing the perceived loading experience -- the gap between when the page first renders something meaningful and when it is visually complete determines whether users feel the page is fast or slow, independent of the raw network timings.

Look for two patterns. First, a long blank white screen at the beginning of the filmstrip (before Start Render) indicates render-blocking resources. Second, large portions of the layout shifting or appearing late indicates either lazy-loaded content being below-the-fold LCP, or images without explicit width and height attributes causing layout recalculation. The filmstrip view makes these problems visually obvious in a way that metric numbers alone cannot.

The Content Breakdown section shows a pie chart and table of your page weight divided by content type (HTML, CSS, JavaScript, images, fonts, other) and by domain. Third-party origins -- analytics scripts, chat widgets, A/B testing platforms, social embeds -- commonly account for 30% to 60% of the total request count and frequently appear on the critical path, blocking LCP.

To quantify the impact of a specific third party, use WebPageTest's Block field in the Advanced Settings. Enter the domain to block (for example, googletagmanager.com) and run the test again. Compare LCP and TBT between the blocked and unblocked versions. This gives you a precise dollar figure for the performance cost of each third-party integration, which is essential data when making architectural decisions or negotiating with marketing teams.

Many of the most performance-critical pages in an application -- dashboards, checkout pages, account settings -- sit behind authentication. WebPageTest's Script feature lets you automate a user journey so the test agent navigates through login before measuring your target page. Scripts run in the actual browser instance and support the full range of browser actions.

The script syntax uses simple tab-delimited commands. Common commands include navigate to load a URL, setValue to fill form fields by selector, submitForm to submit forms, setCookie to inject session cookies directly (faster than a full login flow), and exec to run arbitrary JavaScript. Once you have navigated past the authentication gate, add a final navigate command pointing to your actual target URL -- that final navigation is what WebPageTest measures.

// Step 1: Navigate to login page
navigate  https://your-app.com/login

// Step 2: Wait for form to render
sleep  2000

// Step 3: Fill in credentials
setValue  name=email    your-test-user@example.com
setValue  name=password testpassword123

// Step 4: Submit the login form
submitForm  id=login-form

// Step 5: Wait for post-login redirect to complete
sleep  3000

// Step 6: Navigate to the page you want to test
navigate  https://your-app.com/dashboard/

// WebPageTest measures everything from this final navigate call

// Alternative: inject session cookie to skip login UI entirely
// (faster, more stable)
setCookie  https://your-app.com  session=your-session-token-here
navigate   https://your-app.com/dashboard/

Running WebPageTest manually is useful for diagnostics, but real performance discipline requires automated testing on every deployment. WebPageTest provides a REST API and an official webpagetest npm package that lets you submit tests, poll for completion, retrieve results as JSON, and fail CI builds when metrics exceed defined thresholds.

The typical CI integration pattern is: trigger a test after deployment to a staging or preview URL, wait for results (usually 60--120 seconds), extract LCP, CLS, and TBT from the JSON response, compare against your performance budget, and fail the build with a descriptive error message if any metric is out of range. Combine this with the test result URL included in the build log so developers can click through directly to the waterfall for debugging.

import WebPageTest from 'webpagetest';

const wpt = new WebPageTest('www.webpagetest.org', process.env.WPT_API_KEY);

const BUDGETS = {
  'largest-contentful-paint': 2500,  // ms
  'cumulative-layout-shift':  0.10,
  'total-blocking-time':      200,   // ms
  'time-to-first-byte':       800,   // ms
};

async function runAudit(url) {
  console.log(`Starting WebPageTest audit for ${url}`);

  const result = await wpt.runTest(url, {
    location:    'Dulles:Chrome',
    connectivity: '4G',
    runs:         3,
    firstViewOnly: false,
    video:        true,
  });

  if (result.statusCode !== 200) {
    throw new Error(`Test failed: ${result.statusText}`);
  }

  const { median } = result.data;
  const fv = median.firstView;

  const metrics = {
    'largest-contentful-paint': fv.chromeUserTiming?.LargestContentfulPaint,
    'cumulative-layout-shift':  fv.CumulativeLayoutShift,
    'total-blocking-time':      fv.TotalBlockingTime,
    'time-to-first-byte':       fv.TTFB,
  };

  console.log('Results:', metrics);
  console.log('Full report:', result.data.summary);

  let passed = true;
  for (const [key, value] of Object.entries(metrics)) {
    const budget = BUDGETS[key];
    if (value > budget) {
      console.error(`FAIL ${key}: ${value} exceeds budget ${budget}`);
      passed = false;
    } else {
      console.log(`PASS ${key}: ${value}`);
    }
  }

  if (!passed) process.exit(1);
}

runAudit(process.env.DEPLOY_URL || 'https://your-site.com/');