A browser test fails when the page is slow: wait for a condition instead of pausing for a fixed time

Read the timeout as a question

A browser test that fails with a timeout is telling you that a condition was not met in time, not that time itself ran out. Look at the error first. If it names an action, such as a click on a button, Playwright was waiting for the target to pass its actionability checks. If it names an assertion, an expect was retrying until the condition held. Those are different questions: one is about whether the element could be used, the other is about whether the page reached the state you described. Write down the exact step, the locator and the last thing the error says it was waiting for.

• An action timeout points at the element: is it there, visible, still moving, covered or disabled?
• An assertion timeout points at the application: did the page reach the state at all?

Use the waiting that already exists

Before it acts, Playwright waits for the relevant checks and fails with a TimeoutError if they do not pass in time. For a click the checks are visible, stable, receives events and enabled. Stable means the element's bounding box has stayed the same for two animation frames, so a moving or animating button fails that check until it stops. Receives events means nothing covers the target at the click point, which is how an overlay or a cookie banner blocks a click. Enabled means the element is not disabled, which is how a button that waits for data fails. Web-first assertions work the same way: expect retries until the condition holds. A hand-written check such as isVisible returns at once with no waiting or retry, so a test built on it succeeds or fails depending on timing.

• Write expect on the locator, so the wait is part of the assertion.
• Use user-facing locators such as role and name; the best-practices page prefers them to CSS and XPath because the page structure changes.
• Do not add a force option to a click to get past a covered element. That removes the check that was telling you something.

Replace a fixed pause with a condition

A fixed pause is wrong in two ways at once. It is too short on a slow runner, so the test still fails, and too long everywhere else, so every run is slower. Martin Fowler's advice is never to use bare sleeps for asynchronous responses, and to use a callback or poll with a short interval and a generous limit. In a browser test the equivalent is to wait for what the user would wait for: the confirmation text, the enabled button, the changed row count. If nothing on the screen tells you the work has finished, that is an application question, and a visible signal for the user is also the signal the test needs.

• Search the tests for fixed waits and replace each with the visible result it was standing in for.
• If a wait is for a network call, wait for the response or for the screen state that depends on it.
• Keep one generous limit in the configuration instead of many hand-tuned numbers.

Raising a timeout is rarely the repair, and how the paid job is accepted

The defaults are 30 seconds for a test and 5 seconds for an expect, with no default for an action or navigation, and the documentation says that if tests are flaky the fix probably lies elsewhere. Longer limits make a failure take longer to appear without explaining it. If the waits are right and the test still fails on some runs, the cause is usually data, ordering or the environment, which the other guides in this series cover. For three critical flows, the browser smoke suite job writes each test around an observable end state, runs it repeatedly in CI without retries, and shows that a deliberate break in each flow makes its test fail. Start an enquiry with the flow names and the end state each should reach; no code or credentials are needed.