A waterfall is evidence, not a horoscope. WebPageTest runs a page in a browser under a chosen test setup and records the network and rendering events from that run. The official repository describes itself as the performance-testing code behind webpagetest.org and points separately to a cross-platform browser agent. That split is the basic shape: orchestration on one side, a browser doing real work on the other.

The result is synthetic evidence. It is not a census of production visitors, an accessibility conformance decision, a security review or an SEO verdict. That limitation is useful because a controlled run can be repeated. Trouble begins when one immaculate result gets promoted to universal truth, usually by lunchtime and with a chart.

Start with the question, not the score

A useful test begins with a falsifiable question. Did a deployment delay visible content? Is an external resource holding up rendering? Does a cached navigation behave differently from a first visit? "Is the site fast?" is too vague. It combines several stages of loading, several user populations and whatever mood the network happens to be in.

Record the URL, browser, test location, connection profile, cache state and number of runs. The exact choices available depend on the hosted service or private-instance configuration. Keep those choices fixed across a comparison. Changing the code and the test environment together produces an answer, but not necessarily to a question anyone asked.

Run more than one sample. Network negotiation, server response, cache state and third-party services can vary without a deployment. A common WebPageTest practice is to select the median run for the metric being discussed. Retain the individual run rather than imagining an "average waterfall": a run that is median for one timing can be an outlier for another.

The WebPageTest documentation uses First View and Repeat View for different test states. First View examines a navigation without the retained browser state created by the preceding run. Repeat View examines another navigation after that state exists. Repeat View is not a model of every returning visitor; caches expire, URLs change and browsers discard data with admirable disregard for presentation deadlines.

The machine behind the waterfall

Conceptually, a WebPageTest job has four parts:

A test definition identifies the page and test conditions.
The service schedules that work.
An agent runs the browser in the selected environment.
The resulting timing, request and visual evidence is assembled for inspection.

The official project keeps the cross-platform browser agent separate from the server repository. Agent placement is therefore part of the measurement, not plumbing to ignore. A result from one location and connection profile should not be compared casually with a result produced somewhere else under different conditions.

A connection profile creates a controlled laboratory condition. It does not reproduce a particular visitor's device, radio state, operating system, background activity and route across the internet. Use it to make repeatable comparisons, then describe the profile when reporting the result. "Mobile was slow" is not a test configuration.

Private instances are explicitly supported by the project. They add operational responsibility: the web application can be running while no correctly configured agent is available to perform work. The current README directs operators with agent-configuration problems to the instance's /install page to check whether the configuration is valid.

Read the run in the order a visitor experiences it

Begin with visual progression when the result includes it. Establish when something useful appears, when the principal content becomes recognizable and whether later rendering moves or replaces it. Only then use the waterfall to explain what the browser was doing. Starting at the largest request often produces an elegant investigation of an asset the visitor never waited for.

Read each waterfall row as a sequence of stages rather than one coloured rectangle. Name lookup, connection setup, TLS negotiation where applicable, waiting for the first response byte and transferring content describe different problems. Reused connections will not repay every setup cost, so two similarly sized resources can have very different bars without violating physics.

Vertical proximity is not causality. A request starting late might have been discovered late, initiated by another resource, queued behind browser work or deliberately deferred. A request finishing last might occur after the page is already usable. Correlate request timing with visual changes, initiator information and browser-timeline evidence when the result provides them.

Treat reported milestones as signposts, not diagnoses. If a visual milestone is late, identify the responsible content and trace backwards through discovery, request timing and rendering. If the visual record looks healthy while a late background request dominates total activity, improving that request may still be worthwhile, but it is a different claim from improving initial experience.

A performance result also does not establish accessibility conformance. A page can appear quickly while retaining missing labels, unusable keyboard order or other barriers. Likewise, a laboratory timing is not a security finding or a search-ranking decision. Preserve the narrow claim: this browser produced this result under these declared conditions.

Automation has a small identity crisis

The project supports submitting work programmatically. Its current README identifies two bulk examples: /bulktest, a PHP command-line tool that submits tests, gathers results and aggregates analyses; and /batchtool, a Python tool that submits tests and gathers results. Those are useful starting points when manual testing has become ceremonial clicking.

Store the test identifier, URL, configuration, execution time and relevant deployment revision with automated results. A number detached from its test conditions is difficult to reproduce and very easy to place in a dashboard. Dashboards are exceptionally good at preserving ambiguity in high resolution.

Keep the server, browser agent and any client wrappers distinct in inventories and bug reports. Record the source and revision of each component rather than allowing one convenient package label to stand for the whole system. A shared name can otherwise become a tiny administrative ambush.

Licensing also requires identifying the branch being evaluated. The current README says the master branch, where most active development occurs, uses the Polyform Shield 1.0.0 license, while the apache branch uses Apache 2.0. For self-hosting or redistribution, record the component and branch rather than assigning one unqualified license to everything called WebPageTest.

Where the waterfall floods the basement

The rerun changed although nobody deployed

Symptom: timings and request bars move noticeably between otherwise similar tests. Cause: each run samples variable network negotiation, server response, caching and external services. Do: keep the location, browser, connection profile and cache state fixed; collect several runs; retain the distribution and inspect outliers instead of choosing whichever result supports the meeting's preferred weather.

Repeat View looks heroic while a cold navigation does not

Symptom: Repeat View improves sharply, but the first navigation remains slow. Cause: the two views have different retained browser state. Do: label them separately and compare like with like. Use First View evidence for questions about an uncached navigation, and Repeat View only when retained resources are genuinely part of the question.

The last request gets blamed for the whole page

Symptom: the team targets whichever waterfall row finishes last. Cause: completion order does not establish that a request delayed useful rendering. Do: compare its timing with visual progression, inspect what initiated it and confirm the proposed dependency through a controlled change. A late analytics request and a late principal image may occupy similar clock time while affecting the page differently.

The private instance loads but agents do not run tests

Symptom: the WebPageTest application is reachable, yet agent-backed work does not complete. Cause: the web server and browser agents are separate components, and the agent configuration may be invalid. Do: open the instance's /install page and resolve the reported configuration problem before debugging the page under test.

An automation report gives the server a wrapper's version

Symptom: package inventories or bug reports disagree about the installed WebPageTest version. Cause: the server, agent and client wrappers are separate artifacts, but their identities have been collapsed into one field. Do: identify each artifact explicitly, record its source and keep wrapper version, server release and agent revision in separate fields.

One laboratory result becomes a site-quality verdict

Symptom: a single run is cited as proof that accessibility, security or SEO is satisfactory. Cause: the evidence has escaped its scope. Do: report exactly what the configured browser run established, then evaluate those other concerns with evidence designed for them. A green performance result can be a very tidy label on the wrong box.

References

Important notice. Tap any item to read it in full.

Accuracy is not guaranteed

This article was produced with substantial automated assistance and is published without individual expert verification of every statement. It may contain errors, omissions, oversimplifications, or claims that were accurate when written and have since been superseded. Software, protocols, specifications and best practice in this field change quickly.

Verify before you rely on it

Treat this page as a starting point and a pointer to primary sources, never as an authority in itself. Before acting on anything here, check it against the official documentation, the original publication, or the vendor's own materials, which are linked in the references above. Where this page and a primary source disagree, the primary source is correct and this page is wrong.

No warranty

This content is provided "as is", without warranty of any kind, express or implied, including but not limited to warranties of accuracy, completeness, currency, merchantability, or fitness for a particular purpose.

No liability

To the fullest extent permitted by applicable law, scoutb2.io and its authors accept no liability for any loss or damage whatsoever, whether direct, indirect, incidental, consequential or otherwise, arising from use of or reliance on this article. This expressly includes lost time, lost data, damaged samples or specimens, wasted reagents or compute, failed experiments, equipment damage, and commercial loss.

Not professional advice

Nothing here constitutes professional, scientific, engineering, regulatory, safety or legal advice. You remain solely responsible for your own experimental design, safety assessment, regulatory compliance and data handling, and for any code you run or procedure you perform.

About the illustration

Any image accompanying this article is editorial and decorative. It was produced with generative AI, is not a technical diagram, is not to scale, and is not an accurate depiction of any structure, process or result. Do not read measurements, structures or relationships from it.

Third-party names and links

Product, project and organisation names are the property of their respective owners and are used for identification only. Their mention is not endorsement, affiliation or sponsorship in either direction. External links are provided for convenience and we neither control nor are responsible for third-party content.

Corrections

If you find an error, tell us and we will correct or withdraw the page.

WebPageTest shows what one browser did, not what every visitor felt