Learning center

"Only on slow connections": add latency where it changes the outcome

When a bug only appears on a slow connection, the maintainer's fast network hides it. Network throttling slows every request down so the slow path runs. Know what throttling changes and what it does not, and give the maintainer the throttling settings, not a description of the reporter's Wi-Fi.

What browser throttling does#

Chrome DevTools' Network panel has a throttling menu with presets and custom profiles, set by download speed, upload speed and latency. The same settings are available to scripts through the Chrome DevTools Protocol's Network.emulateNetworkConditions. Chrome DevTools: Throttle the network ยท Protocol: Network.emulateNetworkConditions

We timed a fetch to a local fixture that answers after 50 ms. Without throttling it took 56 ms. With latency: 1500 and no throughput limit, it took 1,504 ms.

This is emulation inside the browser. It adds delay and caps throughput for each request. It does not drop or reorder packets, and it does not change how the operating system's network behaves. Conditions such as packet loss on a mobile network need a tool at the operating-system or network level.

Throttle from a script#

In Playwright with Chromium, open a DevTools Protocol session for the page:

const cdp = await page.context().newCDPSession(page);
await cdp.send('Network.enable');
await cdp.send('Network.emulateNetworkConditions', {
  offline: false,
  latency: 400,                          // ms added
  downloadThroughput: (400 * 1024) / 8,  // bytes per second
  uploadThroughput: (400 * 1024) / 8,
});

Throughput values are bytes per second; -1 disables the limit. This works only in Chromium-based browsers. Playwright's context.setOffline(true) works in every engine and covers the offline case. Playwright: Offline emulation

Find which setting matters#

Slow-connection bugs usually come from one of three mechanisms. Change one setting at a time to see which.

MechanismSetting that triggers itExample
A timeoutHigh latency, or low throughput on a large responseA client timeout of 10 s on an API call
A loading state that the code assumes is shortAny delay long enough for the user to actA user clicks Pay again during a slow response
Order between requestsDelay on one request but not anotherTested more reliably by holding one response

When you have found it, report the smallest setting that triggers it: "fails with 3 s latency, passes with 2 s" tells the maintainer there is a threshold near 2.5 s.

Report the reporter's real conditions too#

Throttling numbers are a reproduction, not a measurement of the reporter's network. If you have the reporter's actual timings, include them: the failing request's Timing tab shows queueing, connection setup, waiting for the server and download. A long Waiting for server response on the reporter's machine points at the server, not the connection.

Worked example: an upload progress bar that froze#

This example is fictional. A user on a train reports that the photo upload's progress bar stops partway and nothing else happens. On office Wi-Fi it works.

The developer throttles uploads to 400 kbps, about 50 KB per second, and uploads a 1.5 MB photo. Sending it takes about 30 seconds. At 20 seconds the progress bar stops at about two thirds. The client gave each upload request a 20-second timeout, and its error handler ignored aborted requests, so the page showed neither progress nor an error. On office Wi-Fi the same upload finished in under a second. Throttling made the slow path run, and the request's Timing tab showed it was cut off while still sending.

Questions#

Can I throttle only one domain?

DevTools throttling applies to the whole page. To slow one host, delay its requests in a Playwright route handler instead.

Should I also throttle the CPU?

When the reporter's device is slower as well, yes. CPU throttling is a separate setting, and a slow device and a slow network can each cause a different bug. Change one at a time.

Return to reproducing what someone else saw for the other layers a replay needs.

One month of free code review.

New organizations get one calendar month of hosted code review for private and public GitHub repositories. No card or cloud connection required. Eligibility and fair-use terms.

Start free with GitHub

Related reading