Assertions

Implicit Assertions

.should()

To make an assertion about the current subject, use the .should() command.

cy.get('.assertion-table')
  .find('tbody tr:last').should('have.class', 'success')
  .find('td')
  .first()
  // checking the text of the  element in various ways
  .should('have.text', 'Column content')
  .should('contain', 'Column content')
  .should('have.html', 'Column content')
  // chai-jquery uses "is()" to check if element matches selector
  .should('match', 'td')
  // to match text content against a regular expression
  // first need to invoke jQuery method text()
  // and then match using regular expression
  .invoke('text')
  .should('match', /column content/i)

// a better way to check element's text content against a regular expression
// is to use "cy.contains"
// https://on.cypress.io/contains
cy.get('.assertion-table')
  .find('tbody tr:last')
  // finds first  element with text content matching regular expression
  .contains('td', /column content/i)
  .should('be.visible')

Note: find even more examples of matching element's text content in this FAQ answer.

.and()

To chain multiple assertions together, use the .and() command.

cy.get('.assertions-link')
  .should('have.class', 'active')
  .and('have.attr', 'href')
  .and('include', 'cypress.io')

Explicit Assertions

expect

To make a BDD assertion about a specified subject, use expect.

expect(true).to.be.true
const o = { foo: 'bar' }
expect(o).to.equal(o)
expect(o).to.deep.equal({ foo: 'bar' })
// matching text using regular expression
expect('FooBar').to.match(/bar$/i)

assert

To make a TDD assertion about a specified subject, use assert.

const person = {
  name: 'Joe',
  age: 20,
}
assert.isObject(person, 'value is object')

Should with callback function

You can write your own complicated checks using .should(cb) function if included assertions are not enough. Pass a function to should() with any number of explicit assertions within it. The callback function will be retried until it passes all your explicit assertions or times out.

cy.get('.assertions-p').find('p')
  .should(($p) => {
    // return an array of texts from all of the p's
    let texts = $p.map((i, el) => // https://on.cypress.io/$
      Cypress.$(el).text())

    // jquery map returns jquery object
    // and .get() convert this to simple array
    texts = texts.get()

    // array should have length of 3
    expect(texts).to.have.length(3)

    // use second argument to expect(...) to provide clear
    // message with each assertion
    expect(texts, 'has expected text in each paragraph').to.deep.eq([
      'Some text from first p',
      'More text from second p',
      'And even more text from third p',
    ])
  })

Assert that element's class includes heading-.

cy.get('.docs-header').find('div')
  // .should(cb) callback function will be retried
  .should(($div) => {
    expect($div).to.have.length(1)

    const className = $div[0].className

    expect(className).to.match(/heading-/)
  })
  // .then(cb) callback is not retried,
  // it either passes or fails
  .then(($div) => {
    expect($div).to.have.text('Introduction')
  })

You can throw any error from the callback function. The callback will be retried, but the assertions will not be shown as nicely in the Command Log UI as Chai assertions.

cy.get('.docs-header').find('div')
  .should(($div) => {
    if ($div.length !== 1) {
      // you can throw your own errors
      throw new Error('Did not find 1 element')
    }

    const className = $div[0].className

    if (!className.match(/heading-/)) {
      throw new Error(`Could not find class "heading-" in ${className}`)
    }
  })

We strongly recommend that your tests are deterministic. But sometimes you might need to match text between two elements, and you do not know what that text should be. Save the value from the first element, then compare it from a should(cb) callback.

let text
/**
* Normalizes passed text,
* useful before comparing text with spaces and different capitalization.
* @param {string} s Text to normalize
*/
const normalizeText = (s) => s.replace(/\s/g, '').toLowerCase()

cy.get('.two-elements')
.find('.first')
.then(($first) => {
  // save text from the first element
  text = normalizeText($first.text())
})

cy.get('.two-elements')
.find('.second')
.should(($div) => {
  // we can massage text before comparing
  const secondText = normalizeText($div.text())
  expect(secondText, 'second text').to.equal(text)
})

Remember that Cypress only retries the very last command, if it allows retrying. If you need to perform additional steps before running an assertion, you can use .should(callbackFn) to retry multiple operations.

cy.get('#random-number')
  .should(($div) => {
    // retries getting the element
    // while the "🎁" is converted into NaN
    // and only passes when a number is set
    const n = parseFloat($div.text())
    expect(n).to.be.gte(1).and.be.lte(10)
  })