End-to-End Testing

Introduction

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.

Prerequisites

• An existing Gatsby site. (Need help creating one? Follow the Quick Start.)

• TypeScript as a devDependencies installed. You can install it like so:

• cypress, start-server-and-test, and gatsby-cypress installed. You can install them like so:

Initial setup

After creating the necessary Cypress configuration file you’ll set up start-server-and-test to run Gatsby’s development server and Cypress together.

1. 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 http://localhost:8000 by default.

2. Add a test:e2e script to your package.json so that you can more quickly run Cypress and Gatsby together:

   The CYPRESS_SUPPORT environment variable enables test utilities inside Gatsby. When you run test:e2e the develop script will be executed, the script waits until http://localhost:8000 is ready and then it executes cy:open.

3. Run the test:e2e script to initialize a Cypress project.

4. Setup the gatsby-cypress commands 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 gatsby build.

Using with --https flag

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: START_SERVER_AND_TEST_INSECURE=1

This means your test:e2e script would look like this:

Writing tests

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.

Testing accessibility

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.

To use cypress-axe, you have to install it and axe-core. You’ll also use some commands from @testing-library/cypress to select elements — see best practices for selecting elements.

1. Install the necessary packages:

2. Add their commands to cypress/support/e2e.ts:

3. You can now write a test like so:

Check out the cypress-axe documentation for more examples.

Continuous Integration

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 scripts inside 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.

Additional Resources

• Cypress documentation
• Playwright documentation
• gatsby-cypress
• cypress-axe