Automatic retry mechanism in Cypress - Framework Patterns

Framework Mode - Automatic retry mechanism

Folder Structure

cypress/
├── e2e/                  # Test specs
│   ├── login.cy.js       # Example test file
│   └── dashboard.cy.js
├── fixtures/             # Test data files (JSON, etc.)
│   └── users.json
├── support/              # Support files and commands
│   ├── commands.js       # Custom commands
│   ├── e2e.js            # Global setup
│   └── retry.js          # Retry logic implementation
cypress.config.js         # Cypress configuration file

Test Framework Layers

• Test Specs (cypress/e2e/): Contains the actual test cases written in Cypress syntax.
• Support Layer (cypress/support/): Holds reusable code like custom commands and retry logic to keep tests clean.
• Fixtures (cypress/fixtures/): Stores static test data used by tests.
• Configuration (cypress.config.js): Defines environment settings, base URLs, retries, and browser options.

Configuration Patterns

Automatic retry in Cypress is configured in cypress.config.js using the retries option:

export default defineConfig({
  e2e: {
    baseUrl: 'https://example.com',
    retries: {
      runMode: 2,      // Retry failed tests 2 times in CI runs
      openMode: 0      // No retries when running tests interactively
    },
    setupNodeEvents(on, config) {
      // Additional event listeners if needed
    }
  }
})

Custom retry logic can also be added in cypress/support/retry.js for commands or assertions that need special handling.

Test Reporting and CI/CD Integration

• Use Cypress built-in retries to reduce flaky test failures in CI pipelines.
• Integrate with CI tools (GitHub Actions, Jenkins, GitLab CI) to run tests with retries enabled.
• Use reporters like mochawesome to generate detailed reports showing retry attempts and final test status.
• Configure CI to fail the build only if tests fail after all retries.

Best Practices for Automatic Retry Mechanism

1. Use Cypress built-in retries: Configure retries in cypress.config.js instead of custom retry loops for simplicity and reliability.
2. Limit retries: Avoid too many retries to prevent hiding real issues and increasing test run time.
3. Retry only flaky tests: Use retries mainly for tests known to be flaky due to timing or network issues.
4. Combine with explicit waits: Use Cypress commands like cy.wait() or cy.intercept() to stabilize tests before retrying.
5. Log retry attempts: Use custom commands or event listeners to log retries for easier debugging.

Self Check

Where in this folder structure would you add a custom command to log retry attempts for failed tests?

Key Result

Use Cypress built-in retries configured in cypress.config.js combined with support layer utilities for stable automatic retry handling.