How to Emulate Network Conditions in Puppeteer

Use Puppeteer’s page.emulateNetworkConditions() with an exported preset such as PredefinedNetworkConditions['Slow 3G'] to simulate a constrained but online connection. To simulate disconnection, use page.setOfflineMode(true). They control separate things: offline mode does not replace the download, upload, or latency parameters configured by network emulation. [Puppeteer API: emulateNetworkConditions](https://pptr.dev/api/puppeteer.page.emulatenetworkconditions) and [Puppeteer API: setOfflineMode](https://pptr.dev/api/puppeteer.page.setofflinemode)

Install Puppeteer

This example uses the puppeteer package and its bundled compatible browser. Install it in a Node.js project:

npm install puppeteer

The puppeteer package downloads a compatible Chrome for Testing build and chrome-headless-shell by default. puppeteer-core does not download a browser; use it when you manage the browser yourself or connect to a remote browser. See the [official installation guide](https://pptr.dev/guides/installation).

Emulate a slow connection

Set the condition before the navigation or interaction you want to measure. Puppeteer documents the preset collection as PredefinedNetworkConditions; the example below uses its Slow 3G entry. The preset name is a profile label, not a numeric speed guarantee.

import puppeteer, {PredefinedNetworkConditions} from 'puppeteer';

const browser = await puppeteer.launch();
try {
  const page = await browser.newPage();
  await page.emulateNetworkConditions(
    PredefinedNetworkConditions['Slow 3G'],
  );
  await page.goto('https://example.com');

  // Interact with and inspect the page under the emulated conditions.
  console.log(await page.title());
} finally {
  await browser.close();
}

Run it with Node.js configured for ES modules, for example by saving it as network-test.mjs and running node network-test.mjs. The official API method accepts a NetworkConditions value or null. For custom profiles, consult the type and API reference shipped with your installed Puppeteer version for the supported fields and units; verify those details instead of copying an undocumented object.

Choose the right network state

What you need to exercise	Use	What it controls
A slower connection that remains online	page.emulateNetworkConditions(profile)	Emulated download, upload, and latency conditions from a preset or custom NetworkConditions.
A disconnected browser	page.setOfflineMode(true)	Offline state.
Stop network-condition emulation	page.emulateNetworkConditions(null)	Disables network-condition emulation.
Leave offline mode	page.setOfflineMode(false)	Turns off the offline state.

These are separate controls. In particular, Puppeteer says setting offline mode does not change download, upload, or latency parameters already set through emulateNetworkConditions(). Passing null disables network-condition emulation; do not treat it as a documented substitute for setOfflineMode(false).

Test offline behavior

Use offline mode for application behavior that depends on losing connectivity, such as an offline notice or a cached page. Apply it before the action under test:

import puppeteer from 'puppeteer';

const browser = await puppeteer.launch();
try {
  const page = await browser.newPage();
  await page.goto('https://example.com');

  await page.setOfflineMode(true);
  // Trigger the action that should handle a lost connection.
  // Inspect the page or application state here.

  await page.setOfflineMode(false);
} finally {
  await browser.close();
}

If the scenario needs both a constrained profile and offline state, configure the network conditions and offline mode independently. Offline mode does not erase the configured download, upload, or latency parameters.

Apply conditions at the right point in a test

1. Create the page you will use for the test.
2. Set a preset or verified custom network condition before the navigation or action whose behavior you want to measure.
3. Navigate or trigger the interaction, then inspect the outcome relevant to your test.
4. For an offline scenario, toggle offline mode separately and restore it when the scenario is finished.
5. Close the browser in a finally block so it is also closed when navigation or assertions fail.

The official example applies a profile before page.goto(). This is a useful sequence for testing navigation under that profile; it does not establish that conditions cannot be changed later.

Version and transport limitations

The current Puppeteer API reference documents PredefinedNetworkConditions as the exported preset collection. Older examples may use historical names: the Puppeteer v22.0.0 changelog records removal of networkConditions in favor of PredefinedNetworkConditions. Check the API for the version installed in your project, since the reference and package versions can change. See the [v22.0.0 changelog](https://github.com/puppeteer/puppeteer/releases/tag/puppeteer-v22.0.0).

Network-condition emulation does not affect WebSockets or WebRTC PeerConnections, according to the method reference. If your test depends on either transport, do not assume the preset reproduces a slow or disconnected connection for it. The cited API is a Page API; confirm behavior against the installed Puppeteer version and browser setup rather than extrapolating support across every browser or protocol combination.

Troubleshooting

Symptom	Likely cause	What to do
PredefinedNetworkConditions is missing	The installed version or import differs from the current documented API, or code uses an older name.	Check the Puppeteer version and its API reference. The v22 changelog documents the move from networkConditions to PredefinedNetworkConditions.
The browser is offline when you expected a slow online connection	Offline mode is enabled separately from network conditions.	Call page.setOfflineMode(false) for online behavior, then configure the desired network condition.
Passing null did not produce the state you expected	null disables network-condition emulation; it is not documented as the offline-mode toggle.	Use page.setOfflineMode(true) or false for offline state.
WebSocket or WebRTC traffic is unaffected	The documented emulation limitation excludes WebSockets and WebRTC PeerConnections.	Do not use this API as evidence of constrained behavior for those transports; select a test setup that exercises the transport under the conditions you need.
A custom profile is rejected or behaves unexpectedly	Its fields or units may not match the installed release’s NetworkConditions type.	Use the type reference for that release and confirm the custom object schema there; avoid copying properties from unrelated or outdated examples.
Navigation appears not to reflect the profile	The profile may have been applied after the navigation or after the behavior being measured.	Apply it before the navigation or interaction under test, following the official example’s sequence.

Performance, reliability, and cost

Throttling is useful for comparing application behavior under a selected profile, but a preset label does not guarantee a particular real-world connection or repeatable timing. Treat results as browser test observations under Puppeteer’s documented emulation, not as measurements of every network path. Keep the browser and Puppeteer version consistent when comparing runs, and verify custom profile details against that version’s API.

This approach runs a browser and performs the navigation in your own test environment, so account for the browser installation, runtime, and page work in your test budget. The dossier provides no benchmark or cost figures for Puppeteer network emulation. If your goal is to obtain a page screenshot rather than test your own browser’s slow or offline behavior, a screenshot API can avoid managing a browser in that workflow.

Or skip the browser setup

For a screenshot without running Puppeteer locally, [ScreenshotNeo](https://screenshotneo.com) is a website screenshot API and MCP server. It does not emulate slow or offline network conditions; use Puppeteer above when those conditions are the test. One GET request returns an image or PDF. See the [ScreenshotNeo API docs](https://screenshotneo.com/docs/) for options.

curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://example.com -o shot.webp

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)

const q = new URLSearchParams({
  access_key: 'YOUR_API_KEY',
  url: 'https://example.com',
});
const res = await fetch(`https://api.screenshotneo.com/v1/shot?${q}`);
if (!res.ok) throw new Error(`Screenshot request failed: ${res.status}`);
await Bun.write('shot.webp', res);

ScreenshotNeo removes cookie banners, popups, and chat widgets before capture. Bot checks, blank pages, and failed loads are never billed. Its MCP server lets AI agents take screenshots. The free plan includes 1,000 screenshots a month with no card; paid plans start at $5 for 3,000 screenshots. [Create a free ScreenshotNeo account](https://screenshotneo.com/account/sign-up/).

FAQ

Does a Slow 3G preset guarantee a particular speed?

No numeric speed guarantee is established by the cited material; the name identifies a preset. Consult the installed-version reference for its documented behavior.

Can I use network emulation to test WebRTC?

The documented emulation does not affect WebRTC PeerConnections, so do not rely on it to constrain that transport.

Where can I find the custom condition fields?

Check the NetworkConditions type and Page API reference corresponding to the Puppeteer version installed in your project.

Does ScreenshotNeo replace this test?

No. ScreenshotNeo captures pages as images or PDFs; Puppeteer network emulation is the relevant method when the test specifically needs slow or offline browser behavior.