Assertion timeout customization in Cypress

Introduction

Sometimes, tests need more time to check if something is true. Customizing assertion timeout helps wait longer or shorter for conditions to pass.

When a web page loads slowly and elements take time to appear.

When waiting for animations or transitions to finish before checking.

When testing features that depend on external data loading.

When default wait time is too short and causes false test failures.

When you want faster tests by reducing wait time for quick responses.

Syntax

Cypress

cy.get('selector', { timeout: milliseconds }).should('assertion')

The timeout option sets how long Cypress waits for the element or condition.

Timeout is in milliseconds (1000 ms = 1 second).

Examples

Waits up to 10 seconds for the submit button to be visible.

Cypress

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

Waits up to 5 seconds for the loading spinner to disappear.

Cypress

cy.get('.loading-spinner', { timeout: 5000 }).should('not.exist')

Waits up to 8 seconds for the text 'Welcome' to appear.

Cypress

cy.contains('Welcome', { timeout: 8000 }).should('be.visible')

Sample Program

This test opens a page and waits up to 7 seconds for an element with id 'delayed-element' to become visible before passing.

Cypress

describe('Assertion timeout example', () => {
  it('waits longer for element to appear', () => {
    cy.visit('https://example.cypress.io')
    // Wait up to 7 seconds for the element with id 'delayed-element' to be visible
    cy.get('#delayed-element', { timeout: 7000 }).should('be.visible')
  })
})

Important Notes

Use assertion timeout customization only when necessary to avoid slowing tests.

Timeouts help reduce flaky tests caused by slow loading or animations.

Summary

Customizing assertion timeout lets tests wait the right amount of time for conditions.

Use the timeout option in Cypress commands like cy.get() or cy.contains().

Adjust timeout based on how fast or slow your app responds to avoid false failures.