Cypress Test Timeout Retry Fix

In this tutorial, you'll learn about Cypress Test Timeout Retry Fix. We cover key concepts, practical examples, and best practices.

Your Cypress test times out waiting for an element: Timed out retrying after 4000ms: cy.type() failed because the element is not visible — Cypress retries commands automatically but eventually gives up.

The Problem

// WRONG — trying to interact with an animated element
cy.visit('/dashboard');
cy.get('[data-cy=modal]').find('[data-cy=save]').click();

Timed out retrying after 4000ms: Expected to find element: [data-cy=save], but never found it.

The modal has a 500ms transition animation. Cypress checks immediately, retries every 100ms for 4 seconds, but the element might not be visible yet or might be covered by an overlay.

Step-by-Step Fix

1. Wait for specific conditions

// RIGHT — wait for animation to complete
cy.visit('/dashboard');
cy.get('[data-cy=modal]', { timeout: 10000 }).should('be.visible');
cy.get('[data-cy=save]').should('be.enabled').click();

Use explicit should() assertions with individual timeouts for elements that take longer to appear.

2. Increase default timeout globally

// cypress.config.js
const { defineConfig } = require('cypress');

module.exports = defineConfig({
  e2e: {
    defaultCommandTimeout: 10000,
    requestTimeout: 10000,
    responseTimeout: 30000
  }
});

3. Use cy.intercept to wait for API responses

// RIGHT — wait for data to load before interacting
cy.intercept('GET', '/api/users').as('getUsers');
cy.visit('/users');
cy.wait('@getUsers');

cy.get('[data-cy=user-list]').should('be.visible');
cy.get('[data-cy=user-row]').should('have.length.at.least', 1);

Waiting for network responses ensures the page state is settled before your test proceeds.

4. Fix flaky selectors

// WRONG — fragile CSS class selector
cy.get('.btn-primary.save-button.submit');

// RIGHT — data attribute selector
cy.get('[data-cy=save-button]');

CSS class selectors break when developers rename classes. Data attributes (data-cy, data-testid) are stable across styling changes and refactors.

5. Debug with cy.pause() and screenshots

cy.get('[data-cy=modal]').should('be.visible');
cy.pause(); // Manually inspect the state
cy.get('[data-cy=save]').click();

Expected output:

  ✓ saves form data (5432 ms)
  ✓ waits for API response (2100 ms)

Prevention Tips

• Use data-cy attributes for all interactive elements
• Wait for API responses with cy.intercept() + cy.wait()
• Set defaultCommandTimeout: 10000 in Cypress config
• Use { timeout: 15000 } per assertion for slow-loading elements
• Run tests with --headed to see what happens during failure

Common Mistakes with test timeout

1. Forgetting that lazy evaluation defers computation until the value is forced, causing space leaks with unevaluated thunks
2. Using return to exit a function early instead of wrapping a pure value in the monad
3. Mixing let bindings with <- bindings in do notation, producing type errors

These mistakes appear frequently in real-world CYPRESS code. DodaTech's contributors have identified these patterns through analysis of open-source projects and production systems.

Practice Exercise

Write a pure function that safely divides two integers using Maybe, then test it with edge cases like division by zero and negative numbers.

This exercise reinforces the concepts covered in this guide. Try implementing it before checking online solutions.

FAQ