Waits and Synchronization

Why it matters

Timing is a common cause of flaky UI tests: the test passes on a fast laptop and fails on a busy CI runner, or fails once in twenty runs. Each false failure costs someone an investigation, and a team that sees many of them starts re-running red builds instead of reading them. That is how a real defect gets waved through.

Bad waits also cost time on every run, and a slow suite gets run less often. Good waits make a suite faster and more trustworthy at once: it moves at the application’s pace, and when it fails, the message names the state that never arrived.

Test timing and application timing

A test and the application run on two clocks. A command such as a click returns as soon as the browser has performed it, and the test moves on to its next line. Whatever the click started finishes later, on the application’s schedule: as the lesson on JavaScript basics for testers showed, fetch() returns a pending promise, and the page changes only when the response arrives.

To synchronize, a test needs a condition it can check: something on the page, in the URL or on the network that is true only when the application is ready for the next step. Typical delays to plan for:

• Network requests: loading, saving and searching finish when the server answers.
• Rendering: a list or a total appears after its data arrives, sometimes in two steps (a placeholder first, the values later).
• Animations: a dialog that slides in, a button that moves while the layout settles.
• Timers: a search box that waits 300 ms after the last keystroke (debounce), a message that disappears after 5 seconds.
• Navigation: a redirect after sign-in, a new tab, a download.

Why a fixed sleep is never the fix

The quickest way to make an early test pass is a pause: Thread.sleep(3000), time.sleep(3), cy.wait(3000) or page.waitForTimeout(3000). A sleep does not know what it is waiting for; it waits a fixed time and continues, ready or not. The Playwright documentation calls tests that wait for time inherently flaky, and the Cypress best practices list waiting for arbitrary time periods as an anti-pattern.

You can watch the problem with a slow endpoint: the API Status Code Simulator answers after a delay you choose, up to 10 seconds. A sleep goes wrong in three ways:

• Too short on a slow run: on a busy CI runner the payment response arrives after 3.4 seconds, the test reads at 3.0 and fails, but only on some runs, so the test is flaky.
• Too long on a fast run: when the response takes 0.3 seconds, the test still waits 3. Two hundred tests with one such sleep each spend a combined 10 minutes per run doing nothing.
• No intent: sleep(3000) does not say what the author was waiting for, so neither the next reader nor the failure message can tell which condition mattered.

Try it: API Status Code Simulator

Implicit and explicit waits

Every condition-based wait has three parts: the condition, a timeout that ends the wait with an error, and a polling interval, which is how often the condition is checked. Selenium WebDriver offers two kinds.

An implicit wait is one session-wide setting: every element lookup retries until the element is present in the DOM or the timeout ends (the default is 0, which fails at once). It waits for presence only, and an element can be present yet hidden, disabled or covered. It also slows lookups that should find nothing: checking with findElements that an error message is absent costs the full implicit timeout.

An explicit wait is written at the step that needs it: a WebDriverWait with a timeout and a condition. ExpectedConditions (expected_conditions in Python) provides common ones, such as visible, clickable, invisible, text present and URL contains, and you can pass your own function: d -> … in Java or lambda d: … in Python, the same idea as a JavaScript arrow function, where d is the driver. By default WebDriverWait checks every 500 milliseconds and returns as soon as the condition holds. The Selenium documentation warns against mixing implicit and explicit waits: the timeouts interact, and a step can fail later than either value suggests.

// A) Implicit wait: one session-wide setting, used by every findElement call.
//    It waits until the element is present in the DOM, not visible or clickable.
driver.manage().timeouts().implicitlyWait(Duration.ofSeconds(5));

// B) Explicit wait: a condition at the step that needs it. Use B instead of A,
//    never both in the same session.
WebDriverWait wait = new WebDriverWait(driver, Duration.ofSeconds(10));
wait.until(ExpectedConditions.textToBePresentInElementLocated(
    By.cssSelector("[data-testid=payment-status]"), "Paid"));
wait.until(ExpectedConditions.elementToBeClickable(
    By.cssSelector("[data-testid=download-receipt]"))).click();

// Your own condition: a function the wait calls until it returns true
wait.until(d -> d.findElements(By.cssSelector("[data-testid=result-row]")).size() == 1);

Auto-waiting in Playwright and Cypress

Playwright runs actionability checks before every action. For click() the element must be visible, stable (not moving), able to receive events (not covered by another element) and enabled; for fill() it must be visible, enabled and editable. The checks repeat until they pass or the timeout ends. The retrying assertions from the lesson on assertions wait for an expected state in the same way. A locator is resolved again on every use, so a re-rendered element cannot leave the test holding an outdated reference, the StaleElementReferenceException that Selenium users know.

Cypress retries queries such as cy.get() and cy.contains() together with the assertion chained to them, for 4 seconds by default, and waits for an element to be actionable before .click() or .type(). To wait for the server, give the request an alias with cy.intercept() and wait for the alias, never for a number.

Auto-waiting checks that an element can be used, not that the application is ready. A "Pay now" button may be enabled before the order total has loaded, and Playwright will click it. When a step depends on data, assert that data first. To wait for a response, start listening before the action that sends the request, or a fast response can arrive before the wait begins. The Playwright documentation also discourages waiting for the networkidle state in tests.

// Playwright: click() waits until the button is visible, stable, receives
// events and is enabled; toHaveText() retries until it matches (5 s default).
await page.getByRole('button', { name: 'Pay now' }).click();
await expect(page.getByTestId('payment-status')).toHaveText('Paid');

// Playwright: to wait for the server, start listening before the click.
const response = page.waitForResponse('**/api/payments');
await page.getByRole('button', { name: 'Pay now' }).click();
expect((await response).status()).toBe(201);

// Cypress: queries retry with their assertion (4 s default);
// an intercept alias waits for the request instead of a number.
cy.intercept('POST', '/api/payments').as('pay');
cy.contains('button', 'Pay now').click();
cy.wait('@pay');
cy.get('[data-testid=payment-status]').should('have.text', 'Paid');

Worked example: fixing a flaky payment test

A Playwright test of the payment page fails in about one pipeline run in ten with Expected: "Paid", Received: "Processing"; on its author’s laptop it always passes. The trace shows the status read 3.0 seconds after the click and the payment response at 3.4. The page also loads the order total after the page itself, which is what the first sleep was covering.

The fix replaces each sleep with the condition it was guessing at. The team measured the payment step on the shared staging environment: usually under one second, at worst about 8 seconds. That measurement sets the one longer timeout. For a publicly reachable endpoint, the Response Time Analyzer gives the same kind of data: median, maximum and p95 (the time 95% of the samples stayed within) over several samples.

• [1] The first sleep becomes an assertion on the visible total, 172.50 SAR. It says what "loaded" means and also catches a wrong total.
• [2] and [3] become one retrying assertion. On a normal run it continues within a second of the click; only this step may take up to 15 seconds, and the comment records why.
• The last click needs no wait of its own: Playwright waits until "Download receipt" is enabled.
• If the payment later needs more than 15 seconds, report it as a performance problem with the timings instead of raising the timeout again.

// BEFORE: always passes locally, fails in about one CI run in ten
await page.goto('/orders/1042/pay');
await page.waitForTimeout(2000);                    // [1] "let the total load"
await page.getByRole('button', { name: 'Pay now' }).click();
await page.waitForTimeout(3000);                    // [2] "let the payment finish"
const status = await page.getByTestId('payment-status').textContent();
expect(status).toBe('Paid');                        // [3] reads once
await page.getByRole('button', { name: 'Download receipt' }).click();

// AFTER: each sleep replaced by the condition it was guessing at
await page.goto('/orders/1042/pay');
await expect(page.getByTestId('order-total')).toHaveText('172.50 SAR');       // [1]
await page.getByRole('button', { name: 'Pay now' }).click();
// [2] + [3]: payment sandbox measured at up to 8 s on shared staging
await expect(page.getByTestId('payment-status'))
  .toHaveText('Paid', { timeout: 15_000 });
await page.getByRole('button', { name: 'Download receipt' }).click();   // auto-waits

Try it: Response Time Analyzer

Frequently asked questions

References

• Waiting Strategies — SeleniumSelenium ProjectWhy browser tests race the page, and how implicit and explicit waits synchronise a WebDriver script with the application.
• Auto-waiting — PlaywrightMicrosoft (Playwright)The actionability checks Playwright runs before each action — visible, stable, enabled, receiving events — which remove most hand-written waits.
• Best Practices — CypressCypress.ioCypress guidance on selecting elements with dedicated attributes, avoiding fixed waits and keeping tests independent.
• WebDriver (W3C)W3C · 2026The W3C protocol browsers implement for remote control by automation tools such as Selenium (the Level 2 edition is a Working Draft).