How to Measure Page Load Time With Puppeteer
Measure a named Puppeteer navigation milestone, inspect browser timing phases, and report results with enough context to make comparisons meaningful.

To measure page load time with Puppeteer, time page.goto() with Node.js performance.now() and name the navigation condition you await, such as load or domcontentloaded. For browser-side phase details, read the document’s Navigation Timing entry after navigation. These are different measurements: the first is the elapsed time around Puppeteer’s navigation promise, while the second describes timestamps recorded by the browser.
There is no single universal “page load time.” A page can dispatch DOMContentLoaded while images are still loading, dispatch load before an application finishes rendering useful content, or keep network activity open after the interface is ready. Pick the signal that matches the question and report it with the URL, browser, environment, and test conditions.
1. Install Puppeteer and measure a navigation milestone
Use a current Node.js installation and create a small project. Puppeteer’s package includes its supported browser download flow; if you use a separately managed browser, make sure its version is compatible with the Puppeteer version.
mkdir puppeteer-timing
cd puppeteer-timing
npm init -y
npm install puppeteer
Save this as measure.mjs, then run node measure.mjs https://example.com. It records a wall-clock interval around page.goto(), checks the HTTP response status, and reads document navigation timings.
import puppeteer from 'puppeteer';
const url = process.argv[2] ?? 'https://example.com';
const waitUntil = 'load';
const browser = await puppeteer.launch({ headless: true });
try {
const page = await browser.newPage();
const startedAt = performance.now();
const response = await page.goto(url, {
waitUntil,
timeout: 60_000,
});
const navigationMs = performance.now() - startedAt;
const timing = await page.evaluate(() => {
const [entry] = performance.getEntriesByType('navigation');
if (!entry) return null;
return {
fetchToResponseEndMs: entry.responseEnd - entry.fetchStart,
requestToFirstByteMs: entry.responseStart - entry.requestStart,
responseDownloadMs: entry.responseEnd - entry.responseStart,
domContentLoadedMs: entry.domContentLoadedEventEnd,
loadEventMs: entry.loadEventEnd,
transferSizeBytes: entry.transferSize,
};
});
console.log(JSON.stringify({
url,
status: response?.status() ?? null,
waitUntil,
navigationMs,
timing,
}, null, 2));
} finally {
await browser.close();
}
The elapsed value is in milliseconds. In Puppeteer, page.goto() resolves with the main resource response, or may return null in same-document cases. A resolved promise does not guarantee a successful HTTP status. Inspect response.status() when a response exists: an HTTP 404 or 500 can still be a completed navigation. [Puppeteer page.goto() API]
This script uses Node’s monotonic performance clock around the awaited promise. It includes the time Puppeteer spends waiting for the chosen lifecycle condition. Browser Navigation Timing values are timestamps from the document’s own navigation timeline. Do not add those values to navigationMs or treat them as interchangeable.
2. Choose what “loaded” means
The waitUntil option controls when Puppeteer considers navigation complete. It accepts one lifecycle event or an array of events:

| Condition | What it waits for | Use it when |
|---|---|---|
commit |
The response has been received and the document has started loading. | You need an early navigation milestone, not a rendered page. |
domcontentloaded |
The browser has fired DOMContentLoaded. |
You care about HTML parsing and deferred scripts reaching that event. |
load |
The browser has fired the document load event. |
You want a conventional document and dependent-resource milestone. |
networkidle0 |
There are no more than zero network connections for at least 500 ms. | You explicitly need a quiet network window and the page supports it. |
networkidle2 |
There are no more than two network connections for at least 500 ms. | You need a network-idle approximation that tolerates a small number of ongoing requests. |
These events mean different things. DOMContentLoaded is not proof that every image or application task is complete. The load event is not proof that the page is useful to a person. Network-idle conditions can be delayed by polling, analytics, streaming, or other background traffic. Choose the condition that answers your measurement question, and write it into the result label. [Puppeteer lifecycle events]
For an application-specific ready condition, wait for a known selector or state rather than equating network quiet with readiness. For example, navigate to the document milestone, then wait for the main content:
await page.goto(url, { waitUntil: 'domcontentloaded', timeout: 60_000 });
await page.waitForSelector('[data-app-ready="true"]', { timeout: 15_000 });
That measures the total script interval through the application condition only if you start the timer before both waits. Label it as “time to app-ready selector,” not as the browser’s load time. Puppeteer also supports waiting for a JavaScript condition with waitForFunction(). [waitForSelector, waitForFunction]
3. Read Navigation Timing phases
The Navigation Timing API provides phase timestamps for the main HTML document. Subtract the relevant start from the end to get an elapsed interval. Commonly useful values include:
responseStart - requestStart: request interval until the first response byte arrives.responseEnd - responseStart: time spent receiving the response after the first byte.responseEnd - fetchStart: approximate fetch-through-response interval.domContentLoadedEventEnd: elapsed document timeline value at completion of the event handlers.loadEventEnd: elapsed document timeline value at completion of load handlers, when available.
The sample returns the raw document timeline offsets for the event values. For an event field that could be zero or not yet useful, check it before presenting a result. The chosen Puppeteer wait condition should normally ensure the event you want has occurred, but production code should still handle absent entries and zero values rather than silently reporting a misleading number. [MDN: PerformanceNavigationTiming]
Navigation Timing is about the document navigation. To inspect scripts, stylesheets, images, and other dependencies, collect Resource Timing entries separately:
const resources = await page.evaluate(() =>
performance.getEntriesByType('resource').map((entry) => ({
name: entry.name,
initiatorType: entry.initiatorType,
durationMs: entry.duration,
transferSizeBytes: entry.transferSize,
}))
);
console.log(resources);
Resource timing answers which dependent resources took time; it is not a substitute for the document’s navigation entry. Some cross-origin resource details may be restricted unless the resource origin grants access through timing policy. A zero transfer size can also arise in cache-related cases, so interpret it with the rest of the entry and the test setup.
4. Measure an interaction that causes navigation
When a click triggers navigation, arm the navigation wait before performing the click. Waiting after the click can miss a fast navigation and cause a timeout or race:
const startedAt = performance.now();
const [response] = await Promise.all([
page.waitForNavigation({ waitUntil: 'load', timeout: 60_000 }),
page.click('a[href="/next"]'),
]);
const elapsedMs = performance.now() - startedAt;
console.log({ status: response?.status() ?? null, elapsedMs });
The same pattern applies to actions like form submission. If the interaction updates the current page without navigation, use an application condition such as a selector or state change instead. Puppeteer documents the navigation-wait race and recommends coordinating the wait with the action. [Puppeteer waitForNavigation]
5. Control the test conditions
Timing is affected by more than the URL. For comparisons, keep the setup consistent and record it with each run:
- Browser and platform: use the same Puppeteer and browser versions, machine class, operating system, and headless mode.
- Viewport and device scale: use the same viewport, scale factor, and device emulation where relevant.
- Network: keep network conditions consistent. If you add throttling, report its settings.
- Cache and service workers: decide whether runs are warm-cache or cold-cache and whether service workers are enabled. Do not mix those conditions in one comparison.
- Page state: use the same authentication, cookies, consent state, and geographic context.
- Completion rule: use the same lifecycle event or app-ready condition for every run.
- Sample count: capture multiple trials and state how you summarize them. Keep individual observations when diagnosing variable behavior.
One run is vulnerable to machine load, network variation, cache state, and platform behavior. Report results as lab automation timings with the conditions attached; do not imply they are field user-experience measurements. TTFB is an early response metric that includes redirect and connection phases as well as request time. It is not total page-load completion. [web.dev: Time to First Byte]
6. Run the same measurement with cURL, Python, or Node.js
These alternatives can measure HTTP response timing, but they do not reproduce a browser’s DOM lifecycle or run page JavaScript. Use them to ask a different question, such as how long a command-line HTTP client spends receiving a response. Puppeteer remains the appropriate method when the target is a browser milestone.
cURL
curl -L -sS -o /dev/null \
-w 'http_code=%{http_code}\nnamelookup=%{time_namelookup}s\nconnect=%{time_connect}s\nfirst_byte=%{time_starttransfer}s\ntotal=%{time_total}s\n' \
https://example.com
-L follows redirects; the reported total is the transfer time for the completed request chain. time_starttransfer is an HTTP client milestone, not the page’s rendered state or necessarily the exact same definition as a browser Navigation Timing field.
Python
import time
import requests
url = "https://example.com"
started = time.perf_counter()
response = requests.get(url, timeout=30, allow_redirects=True)
elapsed_ms = (time.perf_counter() - started) * 1000
print({
"status": response.status_code,
"final_url": response.url,
"elapsed_ms": round(elapsed_ms, 2),
"bytes": len(response.content),
})
Install the dependency with python -m pip install requests. This reports the client’s elapsed request time, including body download; Requests does not execute browser scripts or wait for a DOM event.
Node.js fetch
const url = 'https://example.com';
const startedAt = performance.now();
const response = await fetch(url, { redirect: 'follow' });
const body = await response.arrayBuffer();
const elapsedMs = performance.now() - startedAt;
console.log({
status: response.status,
finalUrl: response.url,
elapsedMs,
bytes: body.byteLength,
});
Run this in a Node.js version with global fetch. As with cURL and Python, it measures an HTTP client operation, not browser rendering or page readiness.
7. Or skip the browser setup
If you need a screenshot as well as a page capture workflow, ScreenshotNeo is a website screenshot API and MCP server for developers. One GET request takes a URL and returns PNG, JPEG, WebP, or PDF. It does not expose Puppeteer navigation timing fields, so use Puppeteer when the metric itself is the deliverable. Use ScreenshotNeo when the practical task is to obtain a clean visual capture without managing a browser instance. See the ScreenshotNeo API docs.

curl -G "https://api.screenshotneo.com/v1/shot" \
-d access_key=YOUR_API_KEY \
--data-urlencode url=https://example.com \
-o shot.webp
Python:
import requests
r = requests.get(
"https://api.screenshotneo.com/v1/shot",
params={"access_key": "YOUR_API_KEY", "url": "https://example.com"},
timeout=90,
)
open("shot.webp", "wb").write(r.content)
Node.js:
const q = new URLSearchParams({
access_key: 'YOUR_API_KEY',
url: 'https://example.com',
});
const res = await fetch(`https://api.screenshotneo.com/v1/shot?${q}`);
const bytes = new Uint8Array(await res.arrayBuffer());
await import('node:fs/promises').then((fs) => fs.writeFile('shot.webp', bytes));
ScreenshotNeo accepts cookie or consent banners as a visitor and removes 60+ known consent platforms, newsletter popups, and chat widgets before capture; each step can be turned off. Bot checks and CAPTCHAs, blank pages, timeouts, failed loads, and cache hits are not billed. The response indicates the page verdict and billing status in headers. An MCP server provides take_screenshot, get_page_info, and capture_pdf tools for Claude, Cursor, and other MCP clients.
The free plan includes 1,000 screenshots per month with no card. Paid plans start at $5 for 3,000 shots; Growth is $15 for 15,000, Pro $39 for 60,000, Scale $99 for 250,000, and Business $249 for 1,000,000. Yearly billing gives two months free, and every feature is on every plan. Sign up for 1,000 free screenshots a month, with no card.
8. Troubleshooting
| Symptom | Likely cause | Fix |
|---|---|---|
Navigation timeout |
The selected lifecycle condition never occurred before the timeout, the site is slow, or ongoing requests prevent network idle. | Use a condition tied to your question; increase timeout only when appropriate. For application readiness, wait for its selector or state instead of network idle. |
goto() completes but status is 404 or 500 |
HTTP error responses can still complete navigation. | Read response.status() and decide whether to record or reject the result. |
| Timing entry is missing | The evaluation may run in the wrong document context, or navigation did not create a new document. | Evaluate after the document navigation and handle a null entry. Same-document navigation can return a null response and may not yield a new navigation entry. |
loadEventMs is zero |
The event timestamp is not yet available or no useful value was recorded when sampled. | Await load if that is the metric; otherwise label the field unavailable and use the intended milestone. |
| Resource entry has no useful size or timing | Cache behavior or cross-origin timing restrictions can limit details. | Record cache/service-worker conditions and check whether the resource origin allows timing access. |
| Large differences between runs | Network, server state, cache, machine load, or page content varied. | Run repeated trials under controlled conditions, preserve observations, and report the summary method and environment. |
| Click wait times out despite a page change | The navigation wait was armed after the click, or the action updated the page without a document navigation. | Use Promise.all() to start waiting before the click; for in-page updates, wait for the resulting selector or state. |
9. Performance, reliability, and cost
Launching a browser has overhead, so a script that measures many URLs can reuse one browser process and create a fresh page or context for each independent run. Close pages and the browser in cleanup paths, including when navigation fails. Reuse can improve throughput, but be consistent about whether browser startup is included in the reported duration. The sample above excludes launch time because its timer begins immediately before navigation.
For repeatable results, isolate each trial’s state where practical and record whether the browser cache and service workers are warm or cold. Avoid running so many parallel pages that they compete for CPU, memory, or network capacity; the test runner can become the bottleneck. Set a navigation timeout and handle failures explicitly so a slow page does not stall a whole batch. A failed navigation is an observation to report, not a timing value to silently discard.
Puppeteer is open source, but operating a browser test still consumes compute, memory, network capacity, and engineering time. At scale, include browser startup, concurrency, retries, storage of results, and the cost of stable test infrastructure in the estimate. ScreenshotNeo can reduce browser setup for capture use cases, but its API returns captures rather than Puppeteer timing measurements. Choose based on whether you need a browser timing diagnostic or a screenshot artifact.
10. FAQ
Is page.goto() duration the same as page load time?
It is the elapsed time until the selected Puppeteer navigation condition is satisfied. Name that condition in the metric label; it is not a universal page-readiness measure.
Should I use networkidle0 or networkidle2?
Only when a quiet network window is part of the question. Polling and background requests can make those conditions misleading or slow; an application-specific ready signal is often more relevant.
Does TTFB tell me how long the page takes to load?
No. TTFB describes an early response point and includes connection and redirect phases. It does not include the complete browser rendering or application readiness process.
Can I compare my Puppeteer number with a field metric?
Only with care. A controlled browser automation run and measurements from real user visits use different conditions and populations. State the relationship and avoid presenting them as equivalent.


