Aliasing and Waiting on

A fixed timer fires on a guess; an aliased wait resolves exactly when the named request completes.

Root cause #

cy.wait(<number>) encodes an assumption about timing that the network does not honor. The duration of an XHR or fetch depends on payload size, backend load, and CI contention, none of which are constant. Pick a number too small and the test asserts on the DOM before data arrives, producing an intermittent failure. Pick a number too large and every run pays the full cost whether or not the request was fast. Worse, a fixed wait masks ordering: two requests in flight may resolve in either order, and a blind timer cannot tell which.

Aliasing replaces the guess with a fact. cy.intercept(...).as('getUsers') binds the matched route to a name, and Cypress records each matching request. cy.wait('@getUsers') then blocks until that specific request has been issued and resolved, returning the interception object so you can assert on its status, body, or request payload. Because the wait is keyed to the real event, it self-adjusts to whatever latency the run actually produces — fast when the response is fast, patient when it is slow, and never racy.

The alias resolves on the real event, so it is fast when the response is fast and patient when it is slow.

Step-by-step fix #

1. Alias the interception before the action #

// Name the route so we can wait on this exact request later.
cy.intercept('GET', '/api/v1/users').as('getUsers');
cy.visit('/users');
// Blocks until the named request resolves — no fixed timer, no guessing.
cy.wait('@getUsers');
cy.get('[data-cy=user-row]').should('have.length.greaterThan', 0);

2. Assert on the interception, not just the DOM #

cy.wait yields the interception so you can verify status and payload, catching backend regressions the UI might hide.

cy.wait('@getUsers').then(({ request, response }) => {
  // Asserting on the response status catches a 500 the DOM might render as "empty".
  expect(response.statusCode).to.eq(200);
  expect(request.headers).to.have.property('authorization');
});

3. Wait on multiple requests deterministically #

Pass an array to synchronize on several aliases regardless of resolution order.

cy.intercept('GET', '/api/v1/users').as('users');
cy.intercept('GET', '/api/v1/roles').as('roles');
cy.visit('/admin');
// Resolves only when BOTH have completed, in any order — no ordering assumptions.
cy.wait(['@users', '@roles']);

4. Wait on a specific occurrence #

When the same route fires repeatedly (pagination, polling), index the alias.

cy.intercept('GET', '/api/v1/feed*').as('feed');
cy.get('[data-cy=load-more]').click();
cy.get('[data-cy=load-more]').click();
// Waits for the SECOND feed request specifically, not just any one.
cy.wait('@feed.2');

For matcher precision that keeps these aliases from catching unintended traffic, see Cypress cy.intercept() Best Practices for Flaky Tests.

Arrays and indexed aliases remove ordering and occurrence assumptions from multi-request flows.

Pitfalls #

Aliasing after the triggering action. Mitigation: always register cy.intercept().as() before the click or visit.
Replacing fixed waits with cy.wait('@alias') but then adding another cy.wait(500) “just in case”. Mitigation: trust the alias and remove every numeric wait.
A matcher so broad the alias resolves on an unrelated request. Mitigation: scope method and URL tightly so the alias maps to one logical call.
Waiting once on a route that fires multiple times. Mitigation: use indexed aliases (@feed.2) for the specific occurrence.
Forgetting that cy.wait only confirms the request happened, not that rendering finished. Mitigation: follow the wait with a DOM .should() assertion.

Asserting on the yielded interception catches backend regressions the DOM would hide.

Reliability targets #

Target	Goal
Fixed `cy.wait(<ms>)` calls remaining	0 in the suite
Timing-related flakiness	< 0.5% of runs
Median spec runtime change	faster (no padded waits)
CI pass rate	≥ 99.5%

Zero numeric waits is the target that collapses timing flakiness.

Frequently Asked Questions #

Q: Why is cy.wait('@alias') better than cy.wait(3000)? A: The alias resolves exactly when the named request completes, so it adapts to real latency. A numeric wait either fires too early and flakes or too late and wastes time on every run.

Q: Can I assert on the request body that was sent? A: Yes. cy.wait('@alias') yields the full interception, so you can inspect request.body, request.headers, and response to validate both directions of the call.

Q: How do I wait for several requests that resolve in any order? A: Pass an array of aliases to cy.wait(['@a', '@b']). It completes only when all of them have resolved, with no assumption about ordering.

Aliases as Documentation #

An alias name is read far more often than it is written, and choosing it well makes a spec self-explanatory. A name describing the operation — createOrder, invoiceList, refreshToken — tells a reader what the wait is for; a name describing the mechanism, such as postRequest or apiCall, tells them nothing and becomes ambiguous the moment a second request appears.

The same principle applies to aliasing requests nobody waits on. Registering an alias costs one argument and makes the command log attributable, which turns “why did this request return that” from an investigation into a glance. In a spec with several intercepts, unaliased ones are the reason a surprising response takes minutes rather than seconds to explain.

A useful convention is one alias per logical operation rather than per route pattern, so a paginated endpoint fetched twice with different parameters yields two names a reader can distinguish. That mapping — operation to alias — is also what makes a later refactor safe: when the URL changes, the alias does not, and every spec that referenced it keeps expressing the same intent.

Waiting for the Request Is Not Waiting for the Render #

An alias resolves when the response arrives, and the interface has not necessarily changed at that point. Between the response and the rendered result sit a promise callback, a state update, a framework’s scheduling pass and a paint — any of which can leave an assertion a frame early.

That gap is the source of the most common disappointment with request waiting: a test waits on the alias, asserts immediately, and fails intermittently on slower machines. The waiting was not wrong; it was insufficient, because the condition the assertion depends on is a rendered consequence rather than a network event.

The reliable pattern is to wait for the request when the request itself matters — asserting on its payload, or ensuring it happened at all — and then to assert on the rendered result with a retrying assertion that spans the remaining boundaries. In many tests the second alone is enough, and the alias is needed only when the test cares about what was sent.

// Wait on the request when the request matters; assert on what the user sees.
// Trade-off: two conditions rather than one, and it removes the one-frame gap
// that produces machine-speed-dependent failures.
cy.wait('@invoices').its('response.statusCode').should('eq', 200);
cy.findAllByRole('row').should('have.length', 25);      // retries until true

Counting Requests Without Coupling to Implementation #

Waiting on an alias several times is a common way to synchronise with a component that fetches more than once, and it couples the test to a detail that is free to change. Adding caching, deduplication or a prefetch alters the number of requests without altering behaviour, and every test that counted them breaks.

The safer default is to wait once and then assert on the rendered outcome, which is what the user actually depends on. Where the count is genuinely the subject — verifying that a debounce issues one request rather than five, or that a retry policy makes exactly three attempts — asserting on it is correct, and it should be stated explicitly so a reader understands that the number is intentional rather than incidental.

There is a related trap with cy.wait on an alias that matches broadly: it resolves on the first matching request, which may not be the one the test means. Narrowing the matcher by method, path and the query parameters that change the response removes the ambiguity, and giving each variant its own alias makes the command log show which one answered.

The general principle is that an alias is a handle on a specific exchange. Used that way it removes fixed waits entirely; used as a general-purpose synchronisation device, it introduces a different fragility in place of the one it removed.

Where several requests must all complete before an assertion is meaningful, waiting on each alias in turn is clearer than a single broad wait, because the command log then shows exactly which one was slow when the spec fails on a loaded runner.

Aliases also make a failing spec cheaper to read months later, because the log names the operation rather than a URL that may since have changed shape.