In a Playwright test, why does page.waitForLoadState() after a click often fail to make the test wait?

`page.waitForLoadState(state)` resolves when the page reaches a load state, `'load'` by default, and accepts `'load'`, `'domcontentloaded'` or the discouraged `'networkidle'`. Two sentences in its documentation explain nearly every misuse: **the navigation must have been committed when the method is called**, and **if the current document has already reached the required state, it resolves immediately**. ## Why the call becomes a no-op Consider clicking *Create issue* on the board and expecting the issue detail page. 1. The click returns as soon as Playwright has dispatched it. The browser may not have received the response headers yet, so no navigation has been committed. 2. `page.waitForLoadState()` runs and looks at the **current** document - still the board, which fired `load` seconds ago. 3. The condition is already satisfied, so the call resolves immediately. 4. The next assertion runs against the board, sees the old row set, and either fails confusingly or, worse, passes for the wrong reason. Nothing about this is intermittent in an obvious way: it is a race, so it passes on a fast local machine and fails on a loaded CI runner, which is exactly the profile of the flake people spend an afternoon on. ## The single-page case A modern issue tracker usually does not create a new document at all. Clicking a row calls `history.pushState()`, the router swaps the view, and the browser fires **no** `load` and **no** `DOMContentLoaded`. There is nothing for `waitForLoadState()` to wait on in either direction - the current document reached `load` at the initial `page.goto()` and never leaves that state. The call is pure decoration, and removing it changes nothing. ## What to use instead | Signal | Waits for | Good for | |---|---|---| | `page.waitForURL(pattern)` | The main frame to reach a matching URL | A click that routes, client-side or not | | `expect(page).toHaveURL(pattern)` | The same, as a retrying assertion | When the URL is the thing being verified | | `expect(locator).toBeVisible()` | The new view's own content | Almost everything else | | `page.waitForLoadState()` | The current document's lifecycle | A popup you just obtained, and little else | `page.waitForURL()` takes a glob string, a `RegExp`, a `URLPattern` or a predicate over the `URL`; a plain string with no wildcards means exact equality. It accepts its own `waitUntil`, defaulting to `'load'`, and it explicitly counts a History API URL change as a navigation - which is what makes it work where a load state does not. It also replaces the deprecated `page.waitForNavigation()`, which the docs describe as inherently racy for the very reason above: it had to be started before the action that triggered the navigation. ## The remaining honest use `waitForLoadState()` is genuinely useful on a page handle you have just received rather than one you navigated. When a click on the issue detail screen opens a popup, you get the new `Page` object and its document may still be blank; `await popup.waitForLoadState('domcontentloaded')` before reading its title is exactly what the method is for. There the navigation *has* been committed - the popup exists because it was - so the precondition holds. ## Diagnosing it in a real suite - Read the trace: a `waitForLoadState` step that takes **0 ms** is the tell. Real waits show duration. - Look at what the failing assertion actually saw. Old content after a click that should have navigated means the wait resolved against the old document. - Check whether the app routes client-side. If the URL changes without a network document fetch, no load-state wait can ever help. - Replace, do not stack. Adding a second `waitForLoadState('networkidle')` on top is the classic wrong fix; it changes the failure mode rather than the race. The general lesson is that a load state describes a **document**, while the test cares about a **view**. Wait for the URL when routing is the point, and assert on rendered content when it is not.