Stop Using cy.wait(ms): Fix Flaky Cypress Tests

Your suite has a line everyone recognizes: cy.wait(3000) sitting after a click like a nervous habit. It was added at 6 PM on a Friday to stop a flake, it worked that evening, and it has been quietly taxing every run since. Now the suite takes 40 minutes, the flake is back anyway, and someone just bumped the sleep to 5000.

Fixed sleeps fail in both directions at once. When the network is fast, the test sits idle burning CI minutes for nothing. When the network is slow — a cold CI runner, a throttled staging API — the response arrives after the sleep ends and the test fails exactly as if the sleep were never there. You pay the cost on every run and still lose the race on bad days. It is the worst of both worlds, formalized as a testing strategy.

There is a better wait, and it has been in Cypress all along: tell Cypress which network request you expect with cy.intercept(), then wait for that request with cy.wait(@alias). The test pauses precisely until the app's real work finishes — 200 milliseconds on good days, 9 seconds on bad ones — then proceeds the instant it can. This article converts every sleep in your suite into that pattern.

Why cy.wait(ms) Makes Tests Flaky

A fixed sleep makes a promise it cannot keep: that the app's work will finish within exactly N milliseconds on every machine, every run, forever. Latency is not constant — it shifts with CI load, cold caches, throttled staging APIs, and payload sizes. When the work finishes early, the sleep burns idle time. When the work finishes late, the test fails as though the sleep never existed. One line of code, failures in both directions.

The damage compounds at suite scale. Two hundred sleeps averaging three seconds inject ten minutes of dead air into every CI run — runs that still flake, because averages never cover the slow tail. Teams respond by raising the numbers, which lengthens every run while merely moving the failure threshold to a rarer slow day. The flake rate feels slightly better for a week, the suite gets permanently slower, and the underlying race is untouched.

Worst of all, sleeps hide the real synchronization point. A reader seeing cy.wait(3000) learns nothing about what the test waits for — a request, a render, an animation? The knowledge lives in the original author's head and rots there. Event-based waits document themselves: cy.wait('@getUsers') followed by a row-count assertion tells the next reader exactly which work must finish before the test proceeds.

// The double tax of fixed sleeps
cy.get('[data-testid="load-users"]').click()
cy.wait(3000) // fast day: 2.8s wasted idle. slow day: response takes
               // 4.1s -> assertion runs too early -> FAIL. Paid AND failed.
cy.get('[data-testid="user-row"]').should('have.length', 5)

// Scale that across a suite: 200 sleeps x 3s avg x every CI run
// = 10 minutes of blind waiting per run, and the flakes survive.

cy.intercept(): Teaching Cypress About Your Network

The cy.intercept() command teaches Cypress about your app's network contract: which method and URL pattern to watch, and what to call it. Registered with .as('getUsers'), the intercept listens for matching traffic while letting it flow to the real backend untouched — observation is the default, stubbing is opt-in. Your test gains a named event it can wait on instead of a guessed duration.

Matching is where intercepts succeed or fail. Match on the HTTP method plus a stable path fragment ('GET', '/api/users*'), deliberately ignoring volatile query strings, pagination params, and cache-busters. Full-URL patterns rot the first time the frontend adds a query param; method-plus-fragment survives normal API evolution. The Cypress runner's Routes panel shows every hit per alias — check it before trusting any green run.

Registration order is the whole game. An intercept only sees requests fired after it starts listening, so it must precede the click, the visit, or the keystroke that triggers the traffic. For page-load requests, that means intercepting before cy.visit(). Get the order right and the alias becomes a faithful record of the app's real work; get it wrong and you will chase timeout ghosts for an afternoon.

// cy.intercept(): name the traffic you expect
// Register BEFORE the action that triggers the request
cy.intercept('GET', '/api/users*').as('getUsers')
cy.intercept('POST', '/api/users').as('createUser')
cy.intercept('GET', '/api/teams/*').as('getTeam')

// Observing (default): request still hits the real backend,
// Cypress just notifies your test when it completes.
cy.visit('/users') // page-load requests are caught too,
                    // because the intercept was registered first

cy.wait(@alias): Wait for the Request, Not the Clock

The replacement pattern has four beats — intercept, act, wait, assert — and runs at the speed of the app rather than the speed of your guess. cy.wait('@getUsers') pauses the test until the matching request completes or the command timeout expires, whichever comes first. Fast backend, 200-millisecond pause. Slow CI day, nine-second pause. Either way the test proceeds the instant the work is done, not a millisecond before or after.

The wait also yields the interception object, so you can assert on the traffic itself: status codes, response bodies, request payloads. cy.wait('@createUser').its('response.statusCode').should('eq', 201) proves the backend accepted the write, not merely that something happened. For parallel loads, pass an array of aliases and wait for the whole set before asserting the composed UI.

Keep the default command timeout in mind as the backstop: an alias wait that never matches fails loudly at the timeout instead of hanging forever. That loud failure is a feature — it points at the missing request (wrong pattern, wrong order, dead backend) instead of letting the test wander into unrelated assertions. A timed-out alias wait is Cypress telling you exactly which expected work never happened.

// The core replacement pattern: intercept -> act -> wait -> assert
cy.intercept('GET', '/api/users*').as('getUsers')
cy.get('[data-testid="load-users"]').click()
cy.wait('@getUsers') // pauses exactly until the response lands
cy.get('[data-testid="user-row"]').should('have.length', 5)

// Waiting on several requests at once
cy.intercept('GET', '/api/users*').as('getUsers')
cy.intercept('GET', '/api/teams*').as('getTeams')
cy.visit('/dashboard')
cy.wait(['@getUsers', '@getTeams'])
cy.get('[data-testid="dashboard-ready"]').should('be.visible')

// Inspecting what came back (optional, powerful)
cy.wait('@getUsers').its('response.statusCode').should('eq', 200)

Network-Aware Assertions Instead of Fixed Sleeps

Network completion is not render completion, and tests that stop at the alias wait still flake. The response lands, Cypress resumes, and the assertion runs while React is mid-render — rows still mounting, totals still computing. The fix is a network-aware assertion: follow every alias wait with a check on the rendered outcome the user would see, and let that assertion's retry loop absorb the paint lag.

Choose assertions that prove the pipeline finished end to end. Row counts (should('have.length', 5)), expected text (should('contain', 'Ada')), computed totals — each verifies data arrived and rendered. Avoid asserting loading-state absence alone; a spinner can unmount before the rows mount, passing your check during the gap. Assert presence of the finished UI, not absence of the busy UI.

When a step is genuinely slow — a report endpoint that takes twelve seconds — resist the sleep reflex and extend that assertion's timeout instead ({ timeout: 15000 }). Timeouts widen the patient window while keeping the instant-pass behavior on fast days; sleeps charge the maximum on every day. Comment the bump with the reason (slow endpoint name, data volume) so the next reader knows it is measured patience, not another guess.

Timeouts Done Right: When Waiting Longer Is Correct

Timeouts and sleeps look similar — both involve milliseconds — but behave oppositely. A sleep always consumes its full duration: cy.wait(10000) burns ten seconds on a run where the app answered in one. A timeout consumes nothing when things are fast: an assertion with { timeout: 15000 } passes in one second on good days and waits up to fifteen only when the app genuinely needs it. One charges the maximum always; the other charges the actual.

Apply timeouts surgically to the steps that earned them. The report endpoint that aggregates for twelve seconds gets a longer assertion timeout with a comment naming the endpoint. The suite-wide defaultCommandTimeout stays modest so genuinely stuck tests still fail fast instead of hanging the pipeline. Blanket timeout inflation is just sleeps with better branding — same cost, vaguer responsibility.

Measure before and after. Record the suite's p50 and p95 step durations from the Cypress dashboard, bump only the steps whose p95 exceeds the default, and note the reason beside each bump. Timeout policy driven by measured latency converges; timeout policy driven by vibes recreates the sleep sprawl under a new name. Patience should be budgeted, documented, and reviewed — never sprinkled.

// Timeouts: widen the patient window, don't add blind delay
// Slow report endpoint? Extend THIS assertion's timeout...
cy.get('[data-testid="report-total"]', { timeout: 15000 })
  .should('contain', '$42,000')

// ...not a sleep before it. Compare:
// BAD:  cy.wait(10000); cy.get('[data-testid="report-total"]')...
//        charges 10s on EVERY run, fast or slow
// GOOD: { timeout: 15000 } passes in 1s on fast days,
//        waits up to 15s only when the app needs it

// Suite-level backstop in config (raise thoughtfully)
// cypress.config.js: e2e: { defaultCommandTimeout: 8000 }

Removing Every cy.wait(ms) From Your Suite

Migration is a loop, not a flag day: convert, verify, delete, repeat — flakiest specs first. For each sleep, identify the covered work, add the intercept and alias wait plus UI assertion, and run the spec several times across different hours (latency varies by time of day on shared CI). Only when the replacement is green repeatedly does the sleep get deleted. Proof before removal keeps every intermediate state shippable.

Rank the backlog by impact: sleep milliseconds multiplied by executions per day. A five-second sleep in a smoke spec run hourly outranks a one-second sleep in a nightly spec — convert where CI minutes and developer attention concentrate. Publish the running total of deleted sleep-seconds; watching suite time fall sprint by sprint keeps the cleanup funded against feature pressure.

Lock the gains with automation. An eslint rule (eslint-plugin-cypress supports no-unnecessary-waiting) flags new bare cy.wait(ms) in review, and a periodic grep over the suite counts remaining instances for the team dashboard. Suites regrow sleeps under deadline pressure unless the guardrail is mechanical. Convert deliberately, verify rigorously, and make the fixed state the path of least resistance.