Why Cypress auto-retries reduce flakiness - Framework Benefits

Framework Mode - Why Cypress auto-retries reduce flakiness

Folder Structure of a Cypress Test Project

cypress/
├── e2e/                  # Test files (end-to-end tests)
│   ├── login.cy.js       # Example test for login
│   └── dashboard.cy.js   # Example test for dashboard
├── fixtures/             # Test data files (JSON, etc.)
│   └── users.json
├── support/              # Custom commands and reusable code
│   ├── commands.js       # Custom Cypress commands
│   └── e2e.js            # Support file loaded before tests
cypress.config.js         # Cypress configuration file
package.json              # Project dependencies and scripts

Test Framework Layers in Cypress

• Test Layer (cypress/e2e): Contains test scripts that describe user actions and assertions.
• Support Layer (cypress/support): Holds reusable commands and setup code to keep tests clean.
• Fixtures Layer (cypress/fixtures): Stores test data like user info or mock responses.
• Configuration Layer (cypress.config.js): Defines environment settings, base URLs, and browser options.
• Driver Layer: Cypress itself acts as the driver controlling the browser and retrying commands automatically.

Configuration Patterns for Cypress Auto-Retries

Cypress automatically retries commands and assertions until they pass or a timeout is reached. You can configure retry behavior in cypress.config.js or test-specific options.

// cypress.config.js
export default {
  e2e: {
    baseUrl: 'https://example.com',
    defaultCommandTimeout: 4000,  // Time Cypress waits before failing a command
    retries: {
      runMode: 2,    // Retry failed tests twice in CI runs
      openMode: 1    // Retry once when running locally
    }
  }
}

This setup helps tests recover from temporary delays or slow loading elements, reducing false failures.

Test Reporting and CI/CD Integration

• Test Reports: Cypress generates detailed HTML reports showing which tests passed, failed, and retried.
• CI/CD Integration: Configure your CI pipeline (GitHub Actions, Jenkins, etc.) to run Cypress tests with retries enabled to reduce flaky failures.
• Flakiness Reduction: Auto-retries help avoid flaky test failures caused by network delays or slow UI rendering.

Best Practices for Using Cypress Auto-Retries

1. Use Explicit Assertions: Write clear assertions so Cypress knows exactly what to retry.
2. Set Reasonable Timeouts: Adjust defaultCommandTimeout to balance test speed and reliability.
3. Limit Retries: Use retries sparingly to avoid hiding real bugs.
4. Use Custom Commands: Encapsulate retry logic in commands for reuse and clarity.
5. Monitor Flaky Tests: Track tests that often retry and investigate root causes.

Self-Check Question

In the folder structure shown, where would you add a new custom command that implements a retryable login action?

Key Result

Cypress auto-retries commands and assertions to reduce flaky test failures caused by temporary delays.