Name the order first#
From the reporter's evidence, write down the two requests and the order that produced the bug. A Network panel waterfall or a Playwright trace shows each request's start and end. For a search box, for example:
GET /api/search?q=a started 0 ms finished 640 ms
GET /api/search?q=ab started 90 ms finished 210 ms
The second request finished first. If the page rendered whichever response arrived last, it showed results for a under the query ab. Search shows results for an earlier query covers diagnosing this; this guide covers replaying it.
Hold the response in a route#
In Playwright, a route handler can wait before letting a request continue. Release it once the other response has arrived:
let release;
const gate = new Promise(resolve => (release = resolve));
await page.route('**/api/search?q=a', async route => {
await gate; // hold the first query
await route.continue();
});
const results = page.getByRole('list', { name: 'Results' });
await page.getByRole('searchbox').pressSequentially('ab');
await expect(results).toContainText('ab'); // the newer results are on screen
const older = page.waitForResponse('**/api/search?q=a');
release(); // only now is the first query sent
await (await older).finished();
await page.waitForTimeout(500); // settle time, taken from a failing run's trace
expect(await results.textContent()).toContain('ab'); // fails while the bug is present
Two details make the script honest. The held request is released only after the page shows the newer results, so the older response cannot be handled first. And the final check runs once, after the older response has finished and a settle time has passed. A correct page does nothing when the stale response arrives, so there is no event to wait for; the settle time has to cover the page's own handling, such as parsing and a debounce. Read it from the trace of a failing run and leave a margin. A retrying assertion such as toContainText at the end could pass on the newer results before the stale response overwrote them. On a fixture search page that renders whichever response arrives last, this script read results for a at the check, so the assertion fails as it should.
We ran this pattern against a fixture with two fetch calls, for q=a and q=ab. In five runs without the hold, they completed in the order sent. With the hold on q=a, the completion order was ab, then a, on every run. Playwright: page.route() ยท route.continue()
route.continue() sends the held request to the server when you release it. To hold the response after the server has answered, use route.fetch() first and route.fulfill({ response }) after the gate, which keeps the server's timing out of the result. In our fixture, that form also completed ab before a.
Choose what to hold#
| The bug needs | Hold |
|---|---|
| An older response to arrive after a newer one | The older request, until the newer response arrives |
| A response to arrive after the user acts again | The response, until the script's next click or keypress |
| A response to arrive after navigation | The response, until page.waitForURL() resolves |
| Two writes to reach the server in a particular order | The first write, until the second has been sent |
Hold the smallest thing that creates the order. A script that holds every request is harder to read and may introduce orders that never happen in production.
Report the order, not the delay#
"Add a 600 ms delay" is a guess that works on one machine. "The response for q=a arrives after the response for q=ab" is a condition the maintainer can create anywhere. Write the order in the report, and include the script.
Worked example: a saved form that reverted#
This example is fictional. A tester reports that a settings form sometimes reverts to old values after Save. It happens about one time in ten.
The trace from a failing run shows PUT /api/settings finishing at 380 ms and a GET /api/settings, started by a background refresh 50 ms before the save, finishing at 420 ms with the old values. The page rendered the GET's response after the PUT's. The developer holds the GET until the PUT's response arrives and the form reverts every run. The fix ignored responses from requests that started before the latest save, and the same script then passed every run.
Questions#
Is throttling ever the better tool?
Yes, when the bug depends on slowness itself, such as a timeout or a loading state, rather than on order. Only on slow connections covers that case.
Can I do this without Playwright?
DevTools' Sources panel can pause on an XHR or fetch breakpoint, which holds the code that sends a request, not the response. A local proxy with breakpoints can hold responses. A test framework's network mocking is usually the simplest way.
What about WebSocket messages?
The same idea applies: hold a message until another event. Playwright's page.routeWebSocket() lets a script decide when to forward each message.
Return to reproducing what someone else saw for the other layers a replay needs.