Cypress Assertions

An assertion checks whether a condition on the page matches what you expect. Assertions form the actual "test" part of a test, since commands alone only perform actions. This topic explains how assertions work in Cypress.

The should Command

The should command attaches a condition to a previously selected element.

cy.get('.success-message').should('be.visible')

This line checks that an element with the class success-message appears visibly on the page.

A Simple Way to Picture It

Think of an assertion as a checkpoint on a road trip. At each checkpoint, someone checks whether your car has enough fuel or the right tire pressure. The trip only continues smoothly if every checkpoint passes its check.

Common Assertion Types

Cypress supports many built-in assertion phrases, each checking a different condition.

cy.get('#header').should('exist')
cy.get('#header').should('be.visible')
cy.get('#header').should('have.text', 'Welcome')
cy.get('#header').should('have.class', 'active')
cy.get('.item').should('have.length', 3)

Checking Text Content

The have.text assertion checks for an exact text match. The contain.text assertion checks that a partial phrase exists inside the element.

cy.get('.title').should('contain.text', 'Welcome')

Partial matches suit cases where surrounding text might change slightly over time.

Assertion Flow Diagram

Select Element
     |
     v
Attach Assertion (should)
     |
     v
Cypress checks the condition repeatedly
     |
     v
Condition met -> Pass
Condition not met within timeout -> Fail

Automatic Retrying

Cypress retries an assertion automatically until it passes or a timeout period ends. This behavior helps with pages that load content slightly after the initial page render. A test does not fail immediately just because content has not appeared yet.

Why Retrying Matters

Older testing tools often failed instantly if an element was not ready at the exact check moment. Cypress avoids this problem by rechecking the condition multiple times within a short window. This reduces false failures caused by normal page loading delays.

Checking Element State

Assertions can check whether an element is enabled, disabled, checked, or selected.

cy.get('#submit').should('be.disabled')
cy.get('#terms').should('be.checked')

Negative Assertions

Adding "not" before a condition reverses its meaning.

cy.get('.error').should('not.be.visible')
cy.get('#submit').should('not.be.disabled')

Negative assertions confirm that unwanted elements or states do not appear on the page.

Chaining Multiple Assertions

A single element can carry more than one assertion in a single line.

cy.get('.status')
  .should('be.visible')
  .and('have.text', 'Active')

The and keyword joins assertions together without repeating the selector.

Asserting on Values Instead of Elements

The expect function checks plain JavaScript values instead of page elements.

const total = 10 + 5
expect(total).to.equal(15)

This pattern helps when a test needs to check calculated values rather than page content.

Writing Readable Assertions

Clear assertions describe expected behavior without extra complexity. A single focused assertion is easier to debug than a long chain covering multiple unrelated checks. Breaking complex checks into separate lines improves readability for future readers.

Key Points

• The should command attaches a condition to a selected element.
• Cypress retries assertions automatically until they pass or time out.
• Assertions can check visibility, text, state, and element count.
• Adding "not" reverses the meaning of an assertion.
• The expect function checks plain values outside of page elements.