Cypress is one of the options when it comes to end-to-end (E2E) testing. With Cypress, you can easily create tests for your modern web applications, debug them visually, and automatically run them in your continuous integration builds. Another popular alternative is Playwright which also works great with Gatsby.
This guide will focus on Cypress though.
An existing Gatsby site. (Need help creating one? Follow the Quick Start.)
TypeScript as a
devDependenciesinstalled. You can install it like so:
gatsby-cypressinstalled. You can install them like so:
After creating the necessary Cypress configuration file you’ll set up
start-server-and-test to run Gatsby’s development server and Cypress together.
Create a Cypress configuration file at the root of your project called
cypress.config.ts. You can use it to e.g. preface the URLs used by
cy.visit()as well as set the folder the tests are in by adding the following:
With this setup all
cy.visit()calls will be prefixed with
test:e2escript to your
package.jsonso that you can more quickly run Cypress and Gatsby together:
CYPRESS_SUPPORTenvironment variable enables test utilities inside Gatsby. When you run
developscript will be executed, the script waits until
http://localhost:8000is ready and then it executes
test:e2escript to initialize a Cypress project.
gatsby-cypresscommands like so:
This initial setup enables you to iterate quickly on your tests as you’re using
gatsby develop. If you want to ensure that your production deployment is also passing your tests, read the Continuous Integration section on how to use Cypress with
If you are running
gatsby develop with the
--https flag enabled, whether using your own or automatically generated certificates, you will also need to tell
start-server-and-test to disable HTTPS certificate checks.
Otherwise it will wait forever and never actually launch Cypress. You can do this by passing in an environmental variable:
This means your
test:e2e script would look like this:
Explaining Cypress in detail is beyond the scope of this guide. Please read Cypress’ documentation, especially Writing your first E2E test to learn more.
We recommend installing
@testing-library/cypress for additional useful matchers.
A good use case for writing automated end-to-end tests is asserting accessibility with
cypress-axe, a Cypress plugin that incorporates the axe accessibility testing API. While some manual testing is still required to ensure good web accessibility, automation can ease the burden on human testers.
Install the necessary packages:
Add their commands to
You can now write a test like so:
Check out the cypress-axe documentation for more examples.
In order to run Cypress inside a Continuous Integration (CI) environment like GitHub Actions, CircleCI, etc. you have to use
cypress run instead of
cypress open. Additionally, you should also use
gatsby build and
gatsby serve to best imitate the production environment of your live website.
One option is to configure your
package.json like so:
You would then run the
test:e2e:ci script inside your CI.
Read the CI Introduction to learn more about all the different options. For example, if you don’t want to use the
CYPRESS_baseUrl environment variable to change the
baseUrl you could also define a separate Cypress config and use it instead of the default one.