Retry-ability of commands in Cypress - Framework Patterns

Framework Mode - Retry-ability of commands

Folder Structure

  cypress/
  ├── e2e/                  # Test specs
  │   ├── login.cy.js       # Example test file
  │   └── dashboard.cy.js
  ├── fixtures/             # Test data files (JSON)
  │   └── users.json
  ├── support/              # Custom commands and utilities
  │   ├── commands.js       # Custom Cypress commands
  │   └── e2e.js            # Support file loaded before tests
  └── cypress.config.js     # Cypress configuration file
  

Test Framework Layers

• Test Specs (e2e/): Contains test files that use Cypress commands. These commands automatically retry until they pass or timeout.
• Support Layer (support/): Defines custom commands and utilities. Custom commands inherit Cypress's retry-ability when built properly.
• Fixtures (fixtures/): Holds test data used by tests to keep tests clean and data-driven.
• Configuration (cypress.config.js): Sets global timeouts and retry options for commands and tests.

Configuration Patterns

Retry-ability in Cypress is controlled via configuration and command design:

• Global Retries: Set retries for tests and hooks in cypress.config.js using retries option.
• Command Timeout: Adjust defaultCommandTimeout to control how long Cypress retries commands before failing.
• Custom Command Design: Write custom commands using Cypress commands inside so retry-ability is preserved.
• Environment Variables: Use env in config to toggle retries or timeouts per environment (e.g., CI vs local).

  // cypress.config.js example
  import { defineConfig } from 'cypress';

  export default defineConfig({
    e2e: {
      retries: 2, // retry failed tests twice
      defaultCommandTimeout: 8000, // 8 seconds retry per command
      env: {
        baseUrl: 'https://example.com'
      }
    }
  })
  

Test Reporting and CI/CD Integration

• Retry Reporting: Cypress reports retries in the test runner UI and in CI logs, showing which attempts passed or failed.
• CI/CD Integration: Configure CI pipelines (GitHub Actions, Jenkins, etc.) to run Cypress tests with retries enabled to reduce flaky failures.
• Test Reports: Use reporters like Mochawesome to generate detailed HTML reports showing retries and test outcomes.
• Flake Reduction: Retries help reduce false failures caused by temporary issues like network delays or slow UI rendering.

Best Practices for Retry-ability in Cypress

1. Use Cypress Built-in Retries: Enable retries in cypress.config.js instead of custom retry logic.
2. Write Idempotent Tests: Ensure tests can safely run multiple times without side effects to benefit from retries.
3. Leverage Cypress Command Retry: Use Cypress commands for actions and assertions to get automatic retry support.
4. Keep Custom Commands Simple: Build custom commands from Cypress commands to inherit retry-ability.
5. Adjust Timeouts Wisely: Set command timeouts to balance between waiting for UI and test speed.

Self Check

Where in this folder structure would you add a new custom command that retries clicking a button until it becomes enabled?

Key Result

Cypress commands automatically retry until success or timeout, enabling stable and reliable test execution.