gatsby-cypress

This package provides additional Cypress commands for testing Gatsby websites.

Please note: This package is not required to use Gatsby and Cypress together. It only exists to add extra commands for convenience.

If you want to find elements (e.g. by test ID or by text/label/etc.), consider using @testing-library/cypress.

Installation

To use these commands, first install the necessary packages:

npm install gatsby-cypress --save-dev

Adding custom Gatsby testing commands

Next, add a new file located at cypress/support/e2e.ts and add the Gatsby-specific Cypress commands:

import "gatsby-cypress/commands"

If you're using TypeScript, add its types to Cypress' tsconfig.json file:

{
  "compilerOptions": {
    // highlight-next-line
    "types": ["cypress", "gatsby-cypress"]
  },
  "include": ["."]
}

Once imported, the following additional commands are available:

• cy.waitForRouteChange(): Waits for Gatsby to finish the route change, in order to ensure event handlers are properly setup. Example:

  cy.visit(`/page-2`).waitForRouteChange()

• cy.waitForAPI('api-name'): Waits for a specific Gatsby API to finish. Example:

  cy.waitForAPI(`onRouteUpdate`).get(`#element-with-event-handler`).click()

• cy.waitForAPIorTimeout('api-name'): Waits for a specific Gatsby API to finish. It timeouts if it doesn't finish. Example:

  cy.waitForAPIorTimeout(`onRouteUpdate`)

Running Cypress tests in Gatsby

Read the End-to-End Testing documentation to learn how to use Cypress and Gatsby together.