Waiting & Retry-ability

Retry-ability & Flake resistance

Retry-ability is a core feature of Cypress and having a proper understanding of it is incredibly important. While some other testing tools require you to add "hard" waits, where you tell the tool to wait for a specified amount of time, Cypress will automatically wait for you. Since Cypress runs in the browser, it understands everything that is happening within your application.

Cypress is notified the moment the page loads and the moment it unloads. It is also notified of any events that are fired. Cypress is smart enough to know how fast an element is animating and will wait for it to stop animating before acting upon it. It will also automatically wait until an element becomes visible, becomes enabled, or when another element is no longer covering it.

Cypress will pause executing any commands when a page transition happens until the new page has fully loaded.

Aliases

In Cypress, we use Aliases to reference elements, requests, or intercepts across our tests.

To create an alias use the .as() function, like so:

// Create an alias using the `as()` Cypress Command
cy.get("table").find("tr").as("rows")

This will get the <table> HTML element, find all of the <tr> elements, and allow us to reference them as @rows throughout our tests.

We can access our alias using cy.get() by adding the @ character before our alias name, like so:

// Reference Cypress Alias `rows`
cy.get("@rows")

@rows is now a reference to the collection of <tr> elements that can be chained off of and interacted with as you would any other elements with Cypress.

Explicit Waits

Even though Cypress is incredibly smart in handling automatic waiting, there are times when you explicitly want to wait for something. For example, you may want to wait on a specific network request to finish before moving forward. The best way to handle these waits is to wait on aliases. Anything that can be aliased can be waited upon, like elements, intercepts, requests, etc.

Let's take a look at an example of what this looks like in practice.

describe("User Sign-up and Login", () => {
  beforeEach(() => {
    cy.request("POST", "/users").as("signup") // creating the signup alias
  })

  it("should allow a visitor to sign-up, login, and logout", () => {
    cy.visit("/")
    // ...

    cy.wait("@signup") // waiting upon the signup alias

    // ...
  })
})

In this example, we are creating an alias called signup for the POST request to the /users endpoint. Then within our test, we tell Cypress to wait upon the signup alias to complete before continuing on with our test.

The Real World App is full of examples of waiting upon aliases, and we go over several examples within the "Real World Examples" section later on.

To learn more about waiting and retry-ability, please check out the following sections of our docs:

Retry-ability

Flake resistant