Command timeout vs assertion timeout in Cypress - Framework Approaches Compared

Framework Mode - Command timeout vs assertion timeout

Folder Structure of a Cypress Test Project

cypress/
├── e2e/                  # Test specs
│   ├── login.cy.js       # Example test file
│   └── dashboard.cy.js
├── fixtures/             # Test data files (JSON)
│   └── users.json
├── support/              # Custom commands and reusable code
│   ├── commands.js       # Custom Cypress commands
│   └── e2e.js            # Global support file
cypress.config.js         # Cypress configuration file
package.json             # Project dependencies and scripts

Test Framework Layers in Cypress

• Test Specs (cypress/e2e/): Contains the actual test scripts where commands and assertions run.
• Support Layer (cypress/support/): Holds reusable commands and setup code to keep tests clean.
• Fixtures (cypress/fixtures/): Stores test data like JSON files to use in tests.
• Configuration (cypress.config.js): Defines global settings like timeouts, base URL, and environment variables.

Configuration Patterns for Timeouts in Cypress

Cypress allows setting timeouts globally or per command/assertion:

• Command Timeout: Maximum time Cypress waits for a command to complete (like cy.get() or cy.click()).
• Assertion Timeout: Maximum time Cypress waits for an assertion to pass (like should('be.visible')).

Example cypress.config.js snippet:

export default defineConfig({
  e2e: {
    baseUrl: 'https://example.com',
    defaultCommandTimeout: 8000,    // 8 seconds for commands
    responseTimeout: 5000,          // 5 seconds for server responses
    pageLoadTimeout: 60000,         // 60 seconds for page load
    // Assertion timeout is controlled by 'timeout' option in assertions
  }
})

Override timeout in a test assertion example:

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

Test Reporting and CI/CD Integration

• Reporting: Use Cypress built-in reporter or plugins like mochawesome for detailed HTML reports showing passed/failed tests and timing.
• CI/CD: Integrate Cypress tests in pipelines (GitHub Actions, Jenkins) to run tests on code changes automatically.
• Timeout Failures: If command or assertion timeouts are exceeded, tests fail and report the timeout error clearly.

Best Practices for Handling Command and Assertion Timeouts in Cypress

1. Set sensible global timeouts: Use defaultCommandTimeout to cover most commands but avoid too long waits that slow tests.
2. Use assertion timeouts wisely: Override assertion timeout only when waiting for slow UI changes, like animations or API responses.
3. Avoid mixing timeouts: Understand that command timeout is for finding elements or running commands, assertion timeout is for waiting conditions to be true.
4. Fail fast: Keep timeouts short enough to detect problems quickly but long enough to avoid flaky tests.
5. Use retries carefully: Cypress retries assertions automatically until timeout; do not add manual retries that conflict.

Self Check Question

Where in the Cypress project folder structure would you configure the global command timeout setting?

Key Result

In Cypress, command timeout controls how long to wait for commands, while assertion timeout controls how long to wait for conditions to be true; both are configured in cypress.config.js and can be overridden per test.