Skip to main content

Cypress Actions and Actionability

To continue from the previous posts on querying, filtering and traversing the DOM, this post looks at how you act on an element.

An example form to be used in the following examples:

<form class="contact-form">
  <input name="fullName" />
  <select name="topic">
    <option value="cypress">Cypress</option>
    <option value="playwright">Playwright</option>
  </select>
  <input type="checkbox" name="subscribe" />
  <button type="submit">Send</button>
</form>

What are Actions?

Action commands interact with an element the way a real user would. They are commands like .click(), .type(), .clear(), .check(), .select() and .trigger().

cy.get('[name="fullName"]')
  .type("Aaron Williams");
 
// Select by option text, value or index
cy.get('[name="topic"]')
  .select("Cypress");
 
cy.get('[name="subscribe"]')
  .check();
 
cy.contains("button", "Send")
  .click();

ℹ️ .clear() is a shortcut for .type("{selectall}{del}").

ℹ️ .trigger() fires any DOM event you name, for example .trigger("mouseover").

Actions Need a Subject

An action does not query the DOM. It acts on the yielded subject of the chain before it, so it must be chained off a command that yields an element (a query command).

❌ Below will fail because there is no subject:

cy.click("button");

✅ This works:

cy.get("button")
  .click();

Most actions also expect a single element. .type(), .select() and .trigger() fail if the subject contains more than one. So does .click(), unless you pass { multiple: true } to click each element in turn.

Actionability

Before an action is performed Cypress checks that a real user could perform it. For a .click() these checks are:

  • The element is still attached to the DOM
  • It is not disabled
  • It is scrolled into view (to the top of the viewport by default)
  • It is visible
  • It is not animating
  • It is not covered by another element at the point being clicked (its centre by default)

A child of the element at that point does not count as covering it. The child will receive the click action.

For typing commands (.type() and .clear()) one extra check is done to ensure the element is not readonly.

Tip! Query commands only check that an element exists. Visibility is checked when you act on it.

Checks Retry but Actions Do Not

If any check fails, Cypress waits and tries again until the checks pass or the timeout is reached.

On every retry the query chain is re-run from the beginning, so the checks always run against a newly fetched element. This matters when your website may update the page while Cypress is waiting.

cy.get(".contact-form")
  .find("button")
  .click();

If the button above is covered by a loading overlay Cypress keeps re-running .get() and .find() then checking again until the overlay is gone.

Once every check passes the click is performed straight away and only once.

This is also true when an assertion follows the action:

cy.get('[name="subscribe"]')
  .check()
  .should("be.checked");

If the assertion fails Cypress just retries the assertion. It does not go back and check the box again.

Forcing an Action

Passing { force: true } skips all of the actionability checks, including scrolling the element into view. The click event is dispatched straight at the element, even if it is hidden, covered or disabled.

cy.get(".contact-form")
  .find("button")
  .click({ force: true });

Keep in mind that a real user cannot click a hidden or covered button. A forced action can pass on a page that is broken.

If a problem causing your test to fail is related to an animation then you can switch off that check:

cy.get(".contact-form")
  .find("button")
  .click({ waitForAnimations: false });

Changing the Timeout

Actions accept a timeout option which is how long Cypress waits for the element to become actionable. Assertions chained straight after the action use the same timeout.

cy.contains("button", "Send")
  .click({ timeout: 10000 });

Enjoying this post?