completefrontend
Open lab My progress
THE WEB PERFORMANCE FIELD GUIDE

WebPageTest in depth

Script WebPageTest through several pages, block domains, test for single points of failure, collect custom metrics, and try a fix before you build it.

By the end, you can
  • 01
    Script a visitWrite a WebPageTest script that measures several steps, and say which lines start a step and which only set one up.
  • 02
    Break third parties on purposeBlock a domain to see what it costs, and send it to the blackhole to see what an outage does to your page.
  • 03
    Measure and try your own thingsCollect a custom metric with a few lines of JavaScript, and test a fix by injecting it before you build it.

Questions a one-page test can't answer

Ravi looks after the Leaf and Kettle website. In WebPageTest basics, he tested one page. He watched it load on a phone, frame by frame.

But Asha doesn't visit one page. She opens the home page. She taps Mint tea. She taps Add to cart, then opens her cart. How did each of those steps feel? Ravi has more questions, too:

  • A new tea page loads a library from Google's servers. What does that cost?
  • What if Google's server stops answering?
  • How tall is the promotion that pushes the store down? WebPageTest doesn't report that.
  • Would keeping room for the promotion stop the jump? Can he find out before he builds it?

A plain test can't answer these. It loads one page and reports its usual numbers. But WebPageTest can do more. You can give it a list of things to do. You can block a server, or break it on purpose. You can ask for numbers of your own. You can even change the page on its way to the browser.

This lesson does each of those with WebPageTest's own agent, the program on its test machines. First, Asha's visit. The course wrote it as a list of steps, and the agent measured each one:

One visit, three stepsPop out in the code editor (opens in a new tab)JavaScript
// One visit, three steps, measured by WebPageTest's agent.// Each step's clock starts at its own command, in ms.const steps = [  { name: "home", drawnBy: 458 },  { name: "tea-page", drawnBy: 280 },  { name: "cart", drawnBy: 265 },]; for (const step of steps) console.log(`${step.name}: drawn by ${step.drawnBy} ms.`);
  • Lines 1 and 2 are comments. A millisecond (ms) is a thousandth of a second. Each step has its own clock. It starts when that step's command runs.
  • Lines 4 to 6 hold the three steps: the home page, the Mint tea page, and the cart. drawnBy is when the screen stopped changing. WebPageTest calls that visually complete.
  • Line 9 prints home: drawn by 458 ms., tea-page: drawn by 280 ms. and cart: drawn by 265 ms.

Here is the whole visit, with the frames the agent kept for each step:

Three measured steps of one visit to the store's multi-page copy, one row each, with the frames WebPageTest's agent kept. Step 1, home: 0 ms, a white screen; 450 ms, the home page's words, before its photo; 458 ms, the home page with its photo of mint tea. Step 2, tea-page: 0 ms, the home page, as the tap on Mint tea starts the step; 280 ms, the Mint tea page. Step 3, cart: 0 ms, the Mint tea page, showing Cart (1) after the tap on Add to cart; 259 ms, the cart page, empty, showing Cart (0); 265 ms, the cart page listing mint-tea, showing Cart (1).1. homedrawn by 458 msStep 1 at 0 ms: a white screen0 msStep 1 at 450 ms: the home page's words, before its photo450 msStep 1 at 458 ms: the home page with its photo of mint tea458 ms2. tea-pagedrawn by 280 msStep 2 at 0 ms: the home page, as the tap on Mint tea starts the step0 msStep 2 at 280 ms: the Mint tea page280 ms3. cartdrawn by 265 msStep 3 at 0 ms: the Mint tea page, showing Cart (1) after the tap on Add to cart0 msStep 3 at 259 ms: the cart page, empty, showing Cart (0)259 msStep 3 at 265 ms: the cart page listing mint-tea, showing Cart (1)265 ms
Real frames from WebPageTest's agent, one row per step. Each step's clock starts at its own command. The cart page showed an empty cart for 6 ms before the store's script filled it in.

Each step got its own filmstrip, its own waterfall and its own numbers. A one-page test gives you only the first row. The list that made it is called a script.

Real-life analogyA script is the mystery shopper's errand list

Last lesson, the mystery shopper visited one shop and wrote down what they saw. This time, you hand them a list: go in, find the mint tea, put it in the basket, go to the till. They time each errand on its own. Their report has one page per errand.

In real life: The errand list you hand the shopper
In WebPageTest: The script
In real life: One errand on the list
In WebPageTest: One line, like clickAndWait class=feature
In real life: An errand they time and report on
In WebPageTest: A measured step
In real life: A name for that errand on the report
In WebPageTest: setEventName tea-page
The main idea

A WebPageTest script is a list of commands, one per line, that the test machine follows. With scripts and a few test options, one test can measure several steps, block or break other servers, collect your own numbers, and try a fix. Your site doesn't change. Only the test does.

Scripting a visit, step by step

A script is plain text. Each line starts with a command. After it comes what the command acts on. WebPageTest's test page has a Script tab where you type it. Here is the script for Asha's visit:

Asha's visit, as a WebPageTest scriptText
setEventName homenavigate %URL%setEventName tea-pageclickAndWait class=featureclick id=addsetEventName cartclickAndWait href=cart.html
  • Line 1 names the next step home. That name is what you'll see in the results.
  • Line 2 loads a page and waits for it to finish. %URL% stands for the address in the test's URL box. Here, that's the store's home page.
  • Line 3 names the next step.
  • Line 4 clicks the element whose class is feature. On the home page, that's the Mint tea link. Then it waits for the browser to finish what the click started.
  • Line 5 clicks Add to cart, the button whose id is add. It doesn't wait, and it isn't measured.
  • Lines 6 and 7 name the last step and click the link to the cart.

So which lines are steps? Only two kinds of line start a measured step: navigate, and any command that ends in AndWait. Every other line either sets up the next step or changes the whole test.

Lines 4, 5 and 7 pick an element by one of its attributes, written as attribute=value. The value can't contain spaces. The agent turns that into code it runs in the page. This example does the same thing, step by step:

From one script line to code in the pagePop out in the code editor (opens in a new tab)JavaScript
// How the agent turns one script line into code it runs on the page.const line = "clickAndWait class=feature";const [command, target] = line.split(" ");const [attribute, value] = target.split("="); console.log(command.endsWith("AndWait") ? "A measured step." : "Not a step of its own.");console.log(`document.querySelector('[${attribute}="${value}"]').click();`);
  • Line 2 is the script's line 4.
  • Line 3 splits it at the space: the command, then the target.
  • Line 4 splits the target at the equals sign: the attribute, then its value.
  • Line 6 checks the command's ending. It prints A measured step.
  • Line 7 prints the code the agent runs: document.querySelector('[class="feature"]').click();

One more rule. The agent reads each line split by tabs, not spaces. WebPageTest's server turns a script typed with spaces into tabs before it sends it. If you run the agent yourself, use tabs.

Be careful with typing mistakes. WebPageTest's docs warn that "if a script step fails, it does so silently". Nothing tells you. So check each step's frames. If a step's last frame isn't the page you expected, a line didn't work.

What the three steps showed

Each step has its own results. Reading them one by one, three things stand out that a one-page test would miss.

The tap on Mint tea starts with a detour. The link says mint-tea.html. The site answered 301, a redirect, and sent the browser to the same address without .html. That cost 140 ms before the real request began. You met redirects in The navigation timeline.

Later steps reuse the first one's work. The home step looked up the store's address, which took 223 ms. The tea page step needed no lookup. It reused the open connection. And 4 of its files came back as 304 Not Modified: the browser still had them from the home page.

The cart flashed empty. At 259 ms, the cart page showed "Your cart" with no items and Cart (0). 6 ms later, the store's script read the cart and filled it in.

Why it matters: visitors don't load pages, they take paths. A script tests the path, with the clicks people really make. That's how it finds hops, flashes and slow steps that a typed address never shows.

Build a script yourself. Start from one the course ran, then add or remove lines. Each line's note says what the agent does with it:

Playground: build a WebPageTest script
The scriptText
setEventName home
navigate %URL%
setEventName tea-page
clickAndWait class=feature
click id=add
setEventName cart
clickAndWait href=cart.html
What the agent does7 lines
  1. Line 1: Sets upNames the next measured step "home".
  2. Line 2: Measured stepMeasured step 1, "home". The agent loads %URL%. Then it waits for the browser's activity to finish.
  3. Line 3: Sets upNames the next measured step "tea-page".
  4. Line 4: Measured stepMeasured step 2, "tea-page". The agent runs document.querySelector('[class="feature"]').click(); Then it waits for the browser's activity to finish.
  5. Line 5: Sets upRuns document.querySelector('[id="add"]').click(); and moves straight on. It isn't a step of its own.
  6. Line 6: Sets upNames the next measured step "cart".
  7. Line 7: Measured stepMeasured step 3, "cart". The agent runs document.querySelector('[href="cart.html"]').click(); Then it waits for the browser's activity to finish.
Try it yourself
3 measured steps: home, tea-page, cart

This is the script the course ran. The agent recorded: home: drawn by 458 ms, 7 requests. tea-page: drawn by 280 ms, 8 requests. cart: drawn by 265 ms, 7 requests.

The rules come from WebPageTest's agent: navigate and AndWait lines start measured steps, and blocking and DNS lines apply to the whole test.

Try logData too. Pick An empty script, then add logData 0, navigate %URL%, logData 1 and navigate %URL%. The first page loads, but it isn't recorded. WebPageTest's docs use that to sign in to a site without measuring the sign-in page.

How the course recorded these tests

  • WebPageTest's agent, version 250303.095116, from its code at commit 560e4d5, set up as in the last lesson.
  • Chrome for Testing 157.0.8103.52, in its headless mode, on the laptop's own connection.
  • Three runs of each test, first view only. The numbers come from the middle run, by load time added up over its steps.
  • Asha's visit used desktop Chrome, in the agent's default window of 1366 by 768 pixels. The store's multi-page copy needs that width: its tea page puts the photo and the words side by side.
  • The other tests used last lesson's phone, the Motorola G Power, with its processor slowed 15 times.
  • The new tea page in the next sections goes live with this lesson, so the agent loaded it from a small server on the laptop. Its jQuery still came from Google's servers, over the internet.
  • One Chrome feature was off: Local Network Access. It stops public pages from reaching the computer's own addresses. But the agent marks the start of each click step with a request to its own address on the laptop.
  • The store's analytics script reports each visit to /visit. The course's copy has no server there, so those reports came back 404.

Blocking domains and requests

Ravi is trying a new tea page. It loads jQuery, a popular JavaScript library, from Google's servers. A file from a company other than yours is called a third party. Here is the part of the page that matters:

The new tea page's head and its last scriptHTML
<head>  <link rel="stylesheet" href="styles.css">  <script src="https://ajax.googleapis.com/ajax/libs/jquery/3.7.1/jquery.min.js"></script></head><body>  <!-- The header, the photo, the price and the Add to cart button. -->  <script>    let count = 0;    $("#add").on("click", () => $("#cart").text(`Cart (${++count})`));  </script></body>
  • Line 2 loads the page's styles.
  • Line 3 loads jQuery from ajax.googleapis.com. It has no async or defer. So the browser stops reading the page until jQuery has arrived and run. It draws nothing until then. You met these render-blocking scripts in Render-blocking and parser-blocking resources.
  • Lines 8 and 9 use jQuery, the $, to make the Add to cart button count.

What does jQuery cost Asha? Find out by testing the page without it. WebPageTest has two commands for that:

  • block refuses any request whose full address contains one of the words you give it.
  • blockDomains refuses every request to the host names you give it, in full.

The test's Block tab has a box for each. As a script, it's two lines:

The tea page, with Google's library blockedText
blockDomains ajax.googleapis.com
navigate %URL%

Line 1 blocks every request to Google's library server. Line 2 loads the page. Inside the agent, the two commands work differently:

  • For blockDomains, the agent gives Chrome a rule. The rule sends ajax.googleapis.com to the laptop's own address. Nothing answers there, so the connection is refused at once.
  • For block, the agent sends Chrome the DevTools command that DevTools' own request blocking uses. Chrome refuses a matching request before it leaves the browser.
Real-life analogyCooking the dinner without one ingredient

Your dinner waits for a sauce from a shop across town. How much time does the sauce cost? Cook the same dinner once without it, and time it. You learn how much sooner dinner is ready. You also learn which dish doesn't work without the sauce.

In real life: The slow sauce from another shop
In WebPageTest: jQuery, from Google's server
In real life: Cooking the same dinner without it
In WebPageTest: The same test with blockDomains
In real life: Dinner is ready sooner
In WebPageTest: Start render comes sooner
In real life: But one dish tastes wrong
In WebPageTest: But the Add to cart button no longer works

The course ran the tea page both ways, on last lesson's phone:

The tea page, with and without Google's libraryPop out in the code editor (opens in a new tab)JavaScript
// The new tea page on the emulated phone, middle runs, in ms.const asItIs = { startRender: 900, requests: 5 };const blocked = { startRender: 458, requests: 4 }; console.log(`Start render: ${asItIs.startRender - blocked.startRender} ms sooner.`);console.log(`Requests in the waterfall: ${asItIs.requests}, then ${blocked.requests}.`);
  • Line 2 holds the page as it is: start render, and the number of requests in the waterfall.
  • Line 3 holds the same page with Google's library blocked.
  • Line 5 prints Start render: 442 ms sooner.
  • Line 6 prints Requests in the waterfall: 5, then 4.
Two filmstrips of the new tea page on an emulated phone, every 250 ms from 0 to 1 second. As it is: white until 900 ms, while jQuery came from Google's server between 179 ms and 466 ms. With Google's library blocked: white until 458 ms, and the library's request was refused at once.0 ms2505007501,000As it isAs it is at 0 ms: a white screenAs it is at 250 ms: a white screenAs it is at 500 ms: a white screenAs it is at 750 ms: a white screenAs it is at 1,000 ms: the frame from 900 ms, 100% completeStart render: 900 msjQuery's request: 179 to 466 msBlockedBlocked at 0 ms: a white screenBlocked at 250 ms: a white screenBlocked at 500 ms: the frame from 458 ms, 100% completeBlocked at 750 ms: the frame from 458 ms, 100% completeBlocked at 1,000 ms: the frame from 458 ms, 100% completeStart render: 458 msjQuery's request: refused at once
Real frames from WebPageTest's agent, middle runs. A bar marks a frame that changed. Without Google's library, the page drew 442 ms sooner.

Where did the 442 ms go? As it is, jQuery's request ran from 179 ms to 466 ms. First the browser had to look up Google's address, which took 120 ms. Then it had to connect and set up encryption before it could even ask. And jQuery had to run, on the phone's slowed processor. Blocked, none of that happened.

But the blocked page didn't work. The test's console said net::ERR_CONNECTION_REFUSED for jQuery. So the page's last script had no $ to call. The Add to cart button did nothing.

Notice the waterfall too. It had one request fewer: jQuery's request isn't in it at all. The agent's code leaves out requests refused this way. It gives the reason: blocking sends a domain to the computer's own address, which refuses the connection. The console still lists the request.

Why it matters: blocking tells you what a third party costs, in time and in features. That's what you need to decide if it's worth keeping, or worth loading another way.

Testing for single points of failure

Blocking answered "what does jQuery cost?". It didn't answer Ravi's next question: what if Google's server stops answering? That's a different question. A blocked request fails at once. A server that's down often doesn't answer at all.

Patrick Meenan, who set up WebPageTest's blackhole server, put it this way: "When these things fail, the servers usually become unreachable and requests time out." A test that fails quickly shows the page without the file, he wrote, "but the experience won't be right".

Real-life analogyA number that's out of service, or a phone that rings forever

You call a shop. If the line says "this number is not in service", you know at once, and you move on. But if it just rings, you wait. You keep waiting, in case someone picks up. Only after a long time do you give up.

In real life: "This number is not in service"
In WebPageTest: A blocked request: refused at once
In real life: A phone that rings and rings
In WebPageTest: A server that never answers
In real life: You, waiting with the phone to your ear
In WebPageTest: The browser, with a white screen
In real life: Finally hanging up
In WebPageTest: The connection timing out

A single point of failure, or SPOF, is one part that stops the whole thing when it fails. On the web, a frontend SPOF is a file from another server that your page can't draw without. A render-blocking third-party script is the classic one.

To test for one, WebPageTest has a server that never answers: blackhole.webpagetest.org. Its docs say it "silently drops all traffic". The test page's SPOF tab takes a list of hosts to fail, one per line. WebPageTest then runs two tests, labelled "Original" and "SPOF", so you can compare them. Here is the script it builds for the SPOF test:

The SPOF test WebPageTest buildsText
setDnsName ajax.googleapis.com blackhole.webpagetest.orgsetTimeout 240navigate %URL%
  • Line 1 makes a fake name. When Chrome looks up ajax.googleapis.com, it gets the blackhole's address instead. The agent looks that address up first, then gives Chrome the rule.
  • Line 2 lets the step run for up to 240 seconds, so the test doesn't give up first.
  • Line 3 loads the page.

The course ran it on the tea page, on the same phone:

The tea page, when Google's server doesn't answerPop out in the code editor (opens in a new tab)JavaScript
// Start render on the new tea page, middle runs, in ms.const asItIs = 900;const googleDown = 75321; const seconds = (ms) => (ms / 1000).toFixed(1);console.log(`As it is: ${seconds(asItIs)} s.`);console.log(`Google's server not answering: ${seconds(googleDown)} s.`);
  • Lines 2 and 3 hold start render from the two tests' middle runs.
  • Line 5 turns milliseconds into seconds, with one decimal place.
  • Lines 6 and 7 print As it is: 0.9 s. and Google's server not answering: 75.3 s.
The new tea page on an emulated phone, drawn to scale from 0 to 80 seconds. As it is: a white screen for 0.9 s, then the page. With Google's server sent to WebPageTest's blackhole: a white screen at 0, 25 and 50 seconds, still white, until the page appeared at 75.3 s.As it isAs it is, at 900 ms: the tea pagewhite for 0.9 sGoogle's servernot answeringGoogle's server not answering, at 0.0 s: a white screenGoogle's server not answering, at 25.0 s: a white screenGoogle's server not answering, at 50.0 s: a white screenGoogle's server not answering, at 75,379 ms: the tea page at lastwhite for 75.3 s0 s20 s40 s60 s80 s
Real frames from WebPageTest's agent, middle runs. The bars show how long each screen stayed white. One script tag, from a server that didn't answer, kept the whole page blank for over a minute.

In the test, the screen stayed white for 75 seconds. Why 75? The browser kept trying to connect to a server that never answered. The test ran on a laptop, and its system gives up on such a connection after 75 seconds. Then the console said net::ERR_CONNECTION_TIMED_OUT, the browser moved past jQuery, and the page drew. A real phone has its own limit, set by its own system. Until it gives up, Asha stares at a white screen. Meenan's own example, a news site whose Twitter button was down, stayed white for 20 seconds.

The fix is to make sure no outside file can stop your page from drawing. Load third-party scripts with async or defer, so the page draws without them. Meenan's news site needed only that: loading its Twitter button asynchronously. Or serve the file from your own server. Script loading strategies and Loading third parties well show how.

Why it matters: any outside server can be slow or down some day. A SPOF test shows you that day now, on video, while you can still fix it.

Custom metrics: measure what you need

Back to the store from the last lesson, after its first fix. Its promotion arrives a second late and pushes everything down. Ravi wants to keep room for it. But how much room? WebPageTest doesn't measure one element's height. You can ask it to.

A custom metric is a little JavaScript that WebPageTest runs in the page at the end of the test. Whatever it returns is saved with the test's other numbers. The HTTP Archive, which reports on how the web is built, uses them for its reports.

Real-life analogyYour own question for the house inspector

Before you buy a house, an inspector checks it against a standard list. You can also hand them a question of your own: "How wide is the gap for the fridge?" They measure it on the day, and write the answer into the same report.

In real life: The inspector's usual checklist
In WebPageTest: WebPageTest's own metrics
In real life: "Please also measure the gap for the fridge"
In WebPageTest: A custom metric
In real life: Measured on the day, in the house itself
In WebPageTest: Run in the test's browser, at the end of the test
In real life: The answer, written into the report
In WebPageTest: The value, saved with the test's numbers

The test's Custom tab takes metrics in a simple form: a name in square brackets, then the code. The course gave every test in this lesson the same four:

Four custom metrics, as the Custom tab takes themText
[promo-height]const promo = document.querySelector("#news");return promo ? promo.offsetHeight : 0; [imgs-without-size]const images = Array.from(document.images);return images.filter((img) => !img.getAttribute("width") || !img.getAttribute("height")).length; [blocking-third-party]const scripts = Array.from(document.querySelectorAll("head script[src]"));return scripts.filter((s) => !s.async && !s.defer && new URL(s.src).host !== location.host).length; [third-party-requests]return $WPT_REQUESTS.filter((request) => new URL(request.url).host !== location.host).length;
  • Line 1 names the first metric. Lines 2 and 3 are its code. They find the promotion, #news, and return its height in pixels, or 0 if the page has none.
  • Lines 5 to 7 count the images that are missing a width or a height. Those are the images that can push a page around.
  • Lines 9 to 11 count scripts in the head that come from another host and have neither async nor defer. That's a SPOF finder.
  • Lines 13 and 14 count requests to other hosts. Before it runs the code, the agent replaces $WPT_REQUESTS with the list of every request Chrome started.

Each metric's code is written as if it were inside a function, so it ends with return. The agent really does wrap it in a function and call it. If the code throws an error, the agent catches it, and the metric is just empty. The test itself carries on.

Here is what the agent returned on two pages:

What the custom metrics returned
MetricThe storeThe tea page
blocking-third-party01
imgs-without-size00
promo-height1200
third-party-requests11
  • imgs-without-size: 0 on both. Every image has its size. So images aren't what moves the store.
  • promo-height: 120 on the store. That's how much room the promotion needs on this phone.
  • blocking-third-party: 1 on the tea page. That's jQuery, the SPOF from the last section. Run this on every test, and it flags the next one before it costs you.
  • third-party-requests: 1 on each. On the store, that's its chat widget's request to chat.example, which never finds a server. The store's waterfall doesn't show that request. The list behind $WPT_REQUESTS still has it.

Why it matters: WebPageTest measures what most pages need. A custom metric measures what your page needs, in the same test, with the same conditions, every time it runs.

Experiments: test a fix before you build it

Now Ravi knows the size of the fix. It's one CSS rule: keep 120 px for the promotion. Would it stop the jump? He could build it, ship it and test it. Or he could test it first.

Real-life analogyTape on the floor before the new sofa

Before you buy a big sofa, you can mark its shape on the floor with tape. Then you walk around the room. Can you still open the door? If the tape says no, you've lost nothing. You haven't bought the sofa yet.

In real life: The room as it is
In WebPageTest: The control run: the page as it is
In real life: Tape on the floor where the sofa would go
In WebPageTest: The fix, added on the page's way to the browser
In real life: Walking around the tape
In WebPageTest: Running the same test again
In real life: Buying the sofa
In WebPageTest: Building the fix into the site

WebPageTest's experiments

WebPageTest does this for you on its Opportunities & Experiments page. After a test, the page lists what could be better. Each item offers experiments: changes WebPageTest can make to the page for one test, with no code from you. Its own page calls them "no-code experiments", for testing "the impact of suggested optimizations, without changing your actual site".

For the tea page, its code would flag jQuery. It checks every render-blocking request from another host. Its title reads "Potential SPOF: 1 3rd-party request is blocking page rendering." Its experiments include "Make Scripts Timeout", which uses the blackhole, and "Block Scripts". There are custom ones too, like "Add HTML to end of head".

When you run an experiment, WebPageTest's code makes two tests:

  • The control run, labelled "Original (Control Run)": the page as it is.
  • The experiment: the same page, with the changes. It sets a cookie, wpt-experiments, that lists them.

Both send the page through WebPageTest's own server for experiments, so they travel the same way. Both are first view only.

To run one, you need an account. WebPageTest's code answers "Must be logged in to use experiments." A free account can run two of them: "Defer Render-Blocking Scripts" and "Add HTML to end of head". The rest need WebPageTest Pro, which its page says gives "unlimited access to no-code experiments".

The same idea, by hand

You can try the same idea by hand, on any test. The test page's advanced settings have an Inject Script box: "JavaScript to run after the document has started loading". A checkbox runs it "before any page scripts run". The course injected the fix with it:

The fix, injected before the page's own code runsJavaScript
const sheet = new CSSStyleSheet();
sheet.replaceSync("#news { min-height: 120px; }");
document.adoptedStyleSheets = [sheet];
  • Line 1 makes an empty style sheet in JavaScript.
  • Line 2 fills it with one rule: keep at least 120 px for #news, the promotion's box.
  • Line 3 adds it to the page. adoptedStyleSheets is the list of style sheets made in JavaScript that a page uses. It works before any of the page's HTML has arrived.

The course ran three tests on the phone:

  • the control: the store as it is;
  • the experiment: the same store, with the fix injected;
  • and later, the store with the same rule built into its CSS. That copy is the one Project: fix a slow store builds.

Here are their layout shift scores. CLS adds up how much the page jumped. How CLS works explains it.

One rule, tested before and after it was builtPop out in the code editor (opens in a new tab)JavaScript
// The store's layout shift score (CLS), from each test's middle run.const cls = { control: 0.146, experiment: 0, built: 0 }; for (const [test, score] of Object.entries(cls)) console.log(`${test}: ${score}`);
  • Line 2 holds the three tests' scores, from their middle runs.
  • Line 4 prints control: 0.146, experiment: 0 and built: 0.
The store from the last lesson on an emulated phone, at 1, 2 and 3 seconds. Control: as it is: at 1.0 s the frame from 764 ms, at 2.0 s the frame from 1,517 ms, at 3.0 s the frame from 2,416 ms; layout shift score 0.146. Experiment: fix injected: at 1.0 s the frame from 853 ms, at 2.0 s the frame from 1,508 ms, at 3.0 s the frame from 2,469 ms; layout shift score 0. Later: fix built: at 1.0 s the frame from 977 ms, at 2.0 s the frame from 1,640 ms, at 3.0 s the frame from 2,591 ms; layout shift score 0. In the control, the promotion pushes the photo down at the end. With the fix, the room is kept from the start.1.0 s2.0 s3.0 sControl:as it isControl: as it is at 1,000 ms: the frame from 764 ms, 61% completeControl: as it is at 2,000 ms: the frame from 1,517 ms, 71% completeControl: as it is at 3,000 ms: the frame from 2,416 ms, 100% completeLayout shift score: 0.146Experiment:fix injectedExperiment: fix injected at 1,000 ms: the frame from 853 ms, 71% completeExperiment: fix injected at 2,000 ms: the frame from 1,508 ms, 72% completeExperiment: fix injected at 3,000 ms: the frame from 2,469 ms, 100% completeLayout shift score: 0Later:fix builtLater: fix built at 1,000 ms: the frame from 977 ms, 71% completeLater: fix built at 2,000 ms: the frame from 1,640 ms, 72% completeLater: fix built at 3,000 ms: the frame from 2,591 ms, 100% completeLayout shift score: 0
Real frames from WebPageTest's agent, middle runs. In the control, the photo moves down when the promotion arrives. With the 120 px kept for it, injected or built, nothing moves.

The frames show why. In the control, the photo moved down when the promotion arrived, at 2,416 ms. With the fix, the room was there from the first frame, and the promotion filled it. The built fix did exactly what the experiment said it would.

Start render moved a little: 764 ms, 853 ms and 977 ms. That's ordinary noise between tests, not the fix. Noise and variability explains it. The jump is what the fix was for, and the jump is gone.

Why it matters: a fix tested first is a fix you know works. You can try several, keep the one that helps, and build only that.

Which test answers this question?

Each kind of test answers its own question. Read this table across: the question, the test, and what it shows.

Which test answers which question
The questionThe testWhat it shows
How fast is each step of a visit?A script with a navigate or AndWait line per step.A filmstrip, a waterfall and numbers for every step.
What does this third party cost?The same page with blockDomains or block.The page without it, and whether it still works.
What if that server goes down?A SPOF test that sends its host to the blackhole.What visitors see while the browser waits.
How big is this one thing on my page?A custom metric that measures it.Your own number, saved with the test's numbers.
Would this fix help?An experiment, or the original with the fix injected.The two tests side by side, before you change the site.

A script is the frame for all of them. Now sort these questions by the other four tests:

Which test answers this question?
  • How much faster is the page without the chat widget?
  • Does the page still work if the ad script never loads?
  • What do visitors see if the font server stops answering?
  • Can one slow outside server keep the screen white?
  • How many iframes does the page end up with?
  • How tall is the cookie banner on a phone?
  • Would preloading the photo make it appear sooner?
  • Would defer on the analytics script speed up start render?
Try it yourself
0 of 8 correct

Sort each question by the kind of WebPageTest test that answers it.

Choose a category for every card. You can change an answer at any time; Reset clears them all.

Common mix-ups

  • "Every line of a script is a step." No. Only navigate and commands that end in AndWait start a measured step. The others set one up, or change the whole test.
  • "WebPageTest tells you when a script line fails." No. Its docs say a failing step fails silently. Check each step's frames.
  • "Blocking a third party shows what happens when it goes down." No. A blocked request fails at once. A server that's down usually doesn't answer. Only the blackhole shows that wait.
  • "A blocked request shows up in the waterfall." No. The agent leaves a refused request out of the waterfall. Look in the test's console instead.
  • "A custom metric slows the page down." No. It runs at the end of the test, after the page has loaded.
  • "An experiment changes your real site." No. It changes the page only on its way to the test's browser. The control run shows the site as it is.

Practice exercises

Answer first, then use the hints.

Exercise 1 · Warm-upThe Add to cart line

This is the click example, run on line 5 of Asha's visit. What does its first line print?

Starter codePop out in the code editor (opens in a new tab)JavaScript
// How the agent turns one script line into code it runs on the page.
const line = "click id=add";
const [command, target] = line.split(" ");
const [attribute, value] = target.split("=");

console.log(command.endsWith("AndWait") ? "A measured step." : "Not a step of its own.");
console.log(`document.querySelector('[${attribute}="${value}"]').click();`);

Answer, then press Check. Spacing and letter case don’t matter.

    Exercise 2 · Warm-upWhat jQuery costs in load time

    These are the tea page's load times, as it is and with Google's library blocked. How many ms sooner was the load?

    Starter codePop out in the code editor (opens in a new tab)JavaScript
    // The new tea page's load time, middle runs, in ms.
    const asItIs = { loadTime: 914 };
    const blocked = { loadTime: 468 };
    
    console.log(`Load time: ${asItIs.loadTime - blocked.loadTime} ms sooner.`);

    Answer, then press Check. Spacing and letter case don’t matter.

      Exercise 3 · PracticeA step with no name

      In the script builder, pick Google's server down. What name does the playground give its one measured step?

      Answer, then press Check. Spacing and letter case don’t matter.

        Exercise 4 · PracticeThe tea page without jQuery

        Open the new tea page in Chrome, with DevTools open. Block Google's library domain in the Network panel, and reload. Which error does the Console show for the page's own script?

        Answer, then press Check. Spacing and letter case don’t matter.

          Exercise 5 · ChallengeBlock everything but your own

          WebPageTest's scripting docs list a command that blocks every domain except the ones you name. Which command is it?

          Answer, then press Check. Spacing and letter case don’t matter.

            Exercise 6 · ChallengeWhat to turn on for a SPOF test

            The SPOF docs say to make sure one test option is on, so you can compare the two tests. Which option?

            Answer, then press Check. Spacing and letter case don’t matter.

              Check your understanding

              For each question, think of the test that would show the answer.

              WebPageTest in depth quiz · 7 questionsScore: first tries count
              1. Question 1 of 7What does the click example print on its first line?

                Read the code, then predictPop out in the code editor (opens in a new tab)JavaScript
                // How the agent turns one script line into code it runs on the page.
                const line = "clickAndWait class=feature";
                const [command, target] = line.split(" ");
                const [attribute, value] = target.split("=");
                
                console.log(command.endsWith("AndWait") ? "A measured step." : "Not a step of its own.");
                console.log(`document.querySelector('[${attribute}="${value}"]').click();`);

                Choose an answer to see the explanation.

              2. Question 2 of 7Which lines of a WebPageTest script start a measured step?

                Choose an answer to see the explanation.

              3. Question 3 of 7The recorded tea page drew sooner with Google's library blocked. Why isn't blocking a good test of an outage?

                Choose an answer to see the explanation.

              4. Question 4 of 7In the recorded SPOF test, why did the tea page finally draw?

                Choose an answer to see the explanation.

              5. Question 5 of 7When does WebPageTest run a custom metric?

                Choose an answer to see the explanation.

              6. Question 6 of 7What does a WebPageTest experiment compare?

                Choose an answer to see the explanation.

              7. Question 7 of 7The recorded experiment injected one CSS rule. What did it change?

                Choose an answer to see the explanation.

              Key takeaways

              • A WebPageTest script is one command per line. navigate and AndWait lines start measured steps, each with its own results.
              • A script tests the path visitors take, so it finds redirects, cache wins and flashes that one page never shows.
              • block and blockDomains show what a third party costs, and what breaks without it. The request fails at once.
              • A SPOF test sends a host to the blackhole, which never answers. It shows what an outage does to your page.
              • A custom metric is JavaScript that runs at the end of the test. Its return value is saved with the test's numbers.
              • An experiment compares a control run with a run that has the change, before you build it. Experiments need an account.

              Remember the one-liner.
              Script the path, break the third parties on purpose, measure what you need, and test the fix before you build it.

              Sources

              The facts on this page come from these docs and source files:

              Coming next: Choosing test conditions. Pick devices, processors and networks that match your real visitors, and learn what each kind of throttling fakes.

              CompleteFrontend Clear concepts. Working examples.