Assertion timeout customization in Cypress - Framework Patterns

Framework Mode - Assertion timeout customization

Folder Structure

  cypress/
  ├── e2e/                  # Test specs
  │   ├── login.cy.js       # Example test file
  │   └── dashboard.cy.js
  ├── support/              # Support files
  │   ├── commands.js       # Custom commands
  │   └── e2e.js            # Global setup
  ├── fixtures/             # Test data files
  │   └── user.json
  cypress.config.js         # Main Cypress config file
  package.json              # Project dependencies and scripts
  

Test Framework Layers

• Test Specs (cypress/e2e/): Contains test files where assertions with customized timeouts are written.
• Support Layer (cypress/support/): Holds reusable commands and global configurations, including timeout overrides.
• Fixtures (cypress/fixtures/): Stores static test data used in tests.
• Configuration (cypress.config.js): Central place to set default assertion timeouts and environment variables.

Configuration Patterns

Customize assertion timeouts in cypress.config.js using defaultCommandTimeout or responseTimeout. Override timeouts per assertion in test code using options like { timeout: 10000 }.

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

  export default defineConfig({
    e2e: {
      baseUrl: 'https://example.com',
      defaultCommandTimeout: 8000,  // default timeout for commands and assertions
      env: {
        username: 'testuser',
        password: 'password123'
      }
    }
  })
  

Example of overriding timeout in a test assertion:

  cy.get('#submit-button', { timeout: 10000 }).should('be.visible')
  

Test Reporting and CI/CD Integration

Use Cypress built-in reporters or plugins like mochawesome for detailed reports including assertion timeout failures.

Integrate Cypress tests in CI/CD pipelines (GitHub Actions, Jenkins) to run tests with customized timeouts ensuring flaky tests are minimized.

  // Example GitHub Actions snippet
  name: Cypress Tests
  on: [push, pull_request]
  jobs:
    test:
      runs-on: ubuntu-latest
      steps:
        - uses: actions/checkout@v3
        - name: Install dependencies
          run: npm ci
        - name: Run Cypress tests
          run: npx cypress run
  

Best Practices

• Set a reasonable global default timeout in cypress.config.js to avoid tests failing too quickly.
• Override timeouts only when necessary for slow-loading elements or external resources.
• Use explicit timeout options in assertions rather than increasing global timeouts to keep tests fast.
• Keep timeout values consistent and documented to help team members understand test behavior.
• Monitor flaky tests caused by timeouts and adjust selectors or application performance instead of just increasing timeouts.

Self Check

Where in this folder structure would you add a custom command to globally apply a longer timeout for a specific assertion?

Key Result

Customize assertion timeouts in Cypress via config and per-assertion options for reliable, fast tests.