Cypress is one of the options when it comes to end-to-end (E2E) testing. Cypress is an all-in-one testing framework focused on E2E testing, meaning that you don’t have to install 10 different things to get your test suite set up. You can write your first passing test in minutes without any configuration with the help of Cypress’ API, which is easy to read and understand. It runs tests as fast as your browser can render content, which also makes test-driven development possible. You’ll also profit from the time travel feature or the extensive debugging capabilities with Chrome DevTools. Of course you can also use it with Gatsby, and this guide will explain how.
In order to run Gatsby’s development server and Cypress at the same time you’ll use the little helper start-server-and-test. If you’re already using @testing-library/react for unit testing you might want to install @testing-library/cypress, too. This way you can use the exact same methods you used with
@testing-library/react in your Cypress tests. Install the following packages to your
We also want the URLs used by
cy.request() to be prefixed, hence you have to create the file
cypress.json at the root of your project with the following content:
Last but not least you add additional scripts to your
package.json to run Cypress:
npm run test:e2e in your command line and see Cypress running for the first time. A folder named
cypress will be created at the root of your project and a new application window will pop up. Cypress’ getting started guide is a good start to learn how to write tests!
Important note: If you are running Gatsby with the
--https flag, 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 do this by passing in an environmental variable:
START_SERVER_AND_TEST_INSECURE=1. start-server-and-test docs.
This means your
test:e2e script would look like this:
If you want to run Cypress in Continuous Integration (CI) you have to use
cypress run instead of
Please read the Cypress’ official documentation on CI if you want to know how to setup Travis or GitLab with Cypress.
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.
Then you add the
@testing-library/cypress commands in
Cypress right now will look for tests inside the
cypress/integration folder. It makes sense to create a new folder
cypress/e2e (end to end). You can use that folder for tests by adding the following in your
Create a new file inside
cypress/e2e folder and name it
You’ll use the
beforeEach hook to run some commands before each test. After cypress loads the homepage you’ll use the
checkA11y method from
cypress-axe to check for accessibility violations:
You can run
test:e2e to run the test. If you already have the development server open you can run
One thing to keep in mind is that you can’t always see the exact error message from the sidebar (command log). For that, you have to open the browser developer console and find the message in the output. You can see how an accessibility error looks in the cypress-axe GitHub page.
You don’t have to use the
checkA11y method only on page load. For example, you can perform a click on a button and check again. This is especially useful if that button opens a modal or a mobile menu for example.
The following test is for the gatsby-default-starter. Cypress visits the homepage and searches for the link that goes to page 2 with the
getByText command. Then, performs a click event on that link and checks for accessibility errors on the second page.
gatsby-default-starter homepage you can write another test that focuses on the footer link. Then you make some assertions on the item that’s currently focused:
Edit this page on GitHub