
_This post is part of the [E2E Testing Series](/blog/e2e-testing-series).  If you haven't already, I suggest reading previous posts before continuing._ 

## Process Overview

We're going to walk through a sample process for how to write E2E tests and touch on some best practices along the way.  Here's an overview of the general process I tend to follow:

1. Create a test file and add pending tests for all the feature requirements.
2. Write the minimum code needed to get each test to pass.
3. With the test runner in watch mode, go back and refactor and clean up code as needed.

If you're familiar with [Test-Driven Development](https://en.wikipedia.org/wiki/Test-driven_development) (TDD), the above might look familiar.  I've found that writing E2E tests is a great opportunity to put TDD into practice.

As our sample feature, we'll be walking through writing the tests for the Newsletter signup form I discussed in the series intro.
 ![newsletter form](/images/blog/e2e-testing/newsletter-signup-form.jpg)
I picked it because it's a small but still complete feature, so a great basis for conveying the E2E test-writing process.

To get started, we'll create our main test file.


## Create the test file and add pending tests
If possible, I suggest collecting all tests for each feature in the same test file, and then match the name of file to the test title.  Let's do that now.

(I'm assuming you've already [set up your local environment](/blog/e2e-series-setting-up-your-local-environment).)

Create a new file at `cypress/e2e/newsletterSignup.cy.ts`.

Note that in [version 10 of Cypress](https://www.cypress.io/blog/2022/06/01/cypress-10-release/) E2E test files are placed in the directory `cypress/e2e` and use the `.cy` extension in the file name, which replaces the previous `.spec` extension for E2E tests.

Add the following code to this file:

<CodeBlock 
code={`// cypress/e2e/newsletterSignup.cy.ts

describe("Newsletter signup", () => {  // ** 1 **
  beforeEach(() => {  // ** 2 **
    cy.visit("/newsletter");
  });
   
  it("displays a message explaining the form's purpose");  // ** 3 **

  it("allows for completing a newsletter signup");

  it("allows for submitting the form by using the enter key");

  it("displays an error message if input value is not a valid email address");

  it("displays an error message if the input field is empty");

  it("clears the email input if signup is successful");

  it("persists the email input value if there is an error");
});`}
/>

### Code notes
1. This is the `describe` block, which is the method used to group test specs.  I recommend matching the name of this block (_e.g._ here the name is "Newsletter signup") to the name of the test file and, if possible, also to what this feature is named elsewhere, eg in a User Story. This is a convention I like to follow to encourage only having one set of feature tests per file and also to create less confusion when trying to locate a test.  The value of this will become more apparent when you start to have large numbers of tests.
2. The `beforeEach` block will run before every test in the describe block.  This is a great place to tell the test runner where it should navigate to.  Also, when applicable it can be a good place to place the app in desired state, eg using a login command. 
3. This is our list of [pending tests](https://glebbahmutov.com/blog/cypress-test-statuses/#pending-tests). The test descriptions for these tests should together make up the requirements for this feature.  If you are working off a User Story, the list of tests should match your [acceptance criteria](https://en.wikipedia.org/wiki/User_story#Acceptance_criteria). 

## Using your E2E tests as your "live" todo list
At this point, your Cypress console should look something like this:

<Image src="/images/blog/e2e-testing/e2e-testing-console-with-test-added.jpg" alt="E2E Testing console with newsletter test added" />

Go ahead and click on "newsletterSignup" and you should now see the test runner with a list of pending tests.

<Image src="/images/blog/e2e-testing/cypress-runner-with-pending-tests.jpg" alt="Cypress runner with the pending tests" />

With the test runner now in watch mode, as you update your tests and source code, our tests will re-run automatically updates tests to passing or failing.

I personally find it to be a great approach to have this type of "live" todo list, helping me remain assured that I am fully aligned and building what actually is being requested, and having a clear sense of my progress.

## Adding our first test 
We're going to start by getting the first pending test to pass, which also happens to be fairly basic. 

In `cypress/e2e/newsletterSignup.cy.ts`, go ahead and replace the first pending test with the following code:

<CodeBlock 
code={`it("displays a message explaining the form's purpose", () => {
  cy.get('[data-test="newsletter"]').contains("Sign up for our newsletter");
});`}
/>


Cypress tests allow for [chaining of methods](https://www.w3schools.com/jquery/jquery_chaining.asp), which means they often are one-liners like the one above.

The test divides into two parts:
- The [`cy.get`](https://docs.cypress.io/api/commands/get) part, which is where we select the element we want to test.
- The [`.contains`](https://docs.cypress.io/api/commands/contains) part which is one of many types of assertions.  In this case, we are asserting that we will find a specific text block in the previously selected element.

(At the risk of causing some confusion, `.get` is also an assertion that an element exists, and `.contains` can also be used to select an element, for use in other assertions.)

You might have noticed the use of `'[data-test="newsletter"]'` to identify our newsletter DOM element, which might look a bit odd.  We'll talk about that in more detail in a bit, but first let's get the above test to pass.

## Getting our first test to pass
If we look at our test runner, we see that the test we added above is failing.

<Image src="/images/blog/e2e-testing/first-failing-test.jpg" alt="E2E Testing console with first failing test" />

This is expected, since we haven't yet added the code to make it pass.  Let's do that now.

Add a new file at `src/pages/newsletter.tsx`.  Since we are placing a file in the special `pages` directory, NextJS will create the new corresponding route `/newsletter`.

Add the following code to the new file:

<CodeBlock 
code={`// src/pages/newsletter.tsx

import type { NextPage } from "next";

const Newsletter: NextPage = () => {
  return (
    <form data-test="newsletter">
      <h3>Sign up for our newsletter!</h3>
    </form>
  );
};

export default Newsletter;`}
/>

If you now go back to the test runner, you should see that there is a green checkmark next to your first test, which means it's passing!  <Emoji symbol="🎉" label="celebrate emoji" />

<Image src="/images/blog/e2e-testing/first-passing-test.jpg" alt="First passing test!" />

## Making tests more resilient with Test IDs 
Note the `data-test="newsletter"` attribute added to the `form` tag above. 

<CodeBlock code={`<form data-test="newsletter">`}/>

`"newsletter"` is our "test id" and what we use to select this element in our test with the selector `[data-test="newsletter"]`.

<CodeBlock 
code={`cy.get('[data-test="newsletter"]')...`}
/>

This is a fairly common pattern in E2E testing, where we make use of a [custom data attribute](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/data-*) to identify the element(s) we want to test.  Note that you can put whatever you want after the `data-` part, but I prefer using `test`.

Why would we want to do this?

I think the easiest way to understand the benefits of using test ids, is to look at the alternatives to identifying elements on a page:

- Use a DOM selector, such as maybe adding an ID to the element, eg `<form id="signupForm">`.
- Using a class name, eg `<form class="signup-form">`.
- Create a selector based on the current DOM structure, such as `main form h3`.

The main issue with these approaches is that they're all fragile.

Every time a developer touches this code, it is possible they might modify any of these due to some implementation need, and unknowingly cause a false negative test failure.

Use of test ID allows us to separate test-specific code and implementation code, making tests more resilient to unrelated code changes.

## Adding the main user flow test 
Next, let's add a test for the main user flow: completing and submitting the signup form.

This test will be a bit more advanced.  Go ahead and update the next pending test to be as follows:

<CodeBlock 
code={`// cypress/e2e/newsletterSignup.cy.ts

it("allows for completing a newsletter signup", () => {
  const testEmail = "test@email.com";

  cy.intercept("POST", "/api/newsletter", (req) => { // ** 1 **

    expect(req.body.email).to.contain(testEmail); // ** 2 **

    req.reply({  // ** 3 **
      statusCode: 200,
      body: {
        success: true,
        message: "Success message",
      },
    });
  });

  cy.get('[data-test="emailInput"]').type(testEmail); // ** 4 **
  cy.get('[data-test="formSubmit"]').click(); // ** 5 **
  cy.get('[data-test="successMessage"]').should("exist"); // ** 6 **
});`}
/>

The goal of this test is to ensure that a "happy path" newsletter signup flow works as expected.

### Code Notes
There's quite a bit going on in this test. Let's walk through it step by step:

1. `cy.intercept("POST"...` - here, we are telling Cypress to [intercept](https://docs.cypress.io/api/commands/intercept) a network request that will happen later in the test. With the intercept feature, Cypress basically masquerades as the given endpoint we defined and returns the response we expect.  The intercept feature is truly powerful and I highly recommend reading more about it in their docs. In our case, it allows us to fully test our client side form by actually submitting an email address without having to worry about clogging up some database with fake test email addresses.
2. This is where we assert that the client side sent the payload we expected to the back-end.
3. If the previous assertion passes, we send the expected success response.
2. `cy.get('[data-test="emailInput...` - this is where we type in the test email address.
3. `cy.get('[data-test="formSubmit"]').click();` - here, we click the form submit button and, which results in an API call, that then is intercepted as per step 1 above.
4. `cy.get('[data-test="successMessage"]')...` - assuming our form submit was successful, we expect a success response from the server.

## Getting the main user flow test to pass

Let's add the code needed to get the above test to pass. Update `src/pages/newsletter.tsx` with the following:

<CodeBlock code={`import type { NextPage } from "next";
import { useState } from "react";
import { ServerResponse } from "../pages/api/newsletter";

const Newsletter: NextPage = () => {
  const [emailInput, setEmailInput] = useState("");
  const [confirmMessage, setConfirmMessage] = useState("");

  const handleSubmit = async (e: React.FormEvent<HTMLFormElement>) => {
    setConfirmMessage("");
    e.preventDefault();

    const raw = await fetch("/api/newsletter", {
      method: "POST",
      headers: {
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        email: emailInput,
      }),
    });

    const response: ServerResponse = await raw.json();

    if (response.success) {
      setConfirmMessage(response.message);
      setEmailInput("");
      return;
    }
  };

  return (
     <form data-test="newsletter" onSubmit={handleSubmit}>
        {confirmMessage && (
          <div data-test="successMessage">{confirmMessage}</div>
        )}
        <h3>Sign up for our newsletter!</h3>
        <input
          type={"email"}
          value={emailInput}
          onChange={(e) => setEmailInput(e.target.value)}
          data-test="emailInput"
          id="emailInput"
          formNoValidate
        />
        <input type={"submit"} data-test="formSubmit" />
    </form>
  );
};

export default Newsletter;`}/>

We also need to add an API endpoint for submitting our form data.  Create a new file at `src/pages/api/newsletter.ts` and add the following:

<CodeBlock code={`import type { NextApiRequest, NextApiResponse } from "next";

export type ServerResponse = {
  message: string;
  success: boolean;
};

export default function handler(
  req: NextApiRequest,
  res: NextApiResponse<ServerResponse>
) {
  const { email } = req.body;

  res.status(200).json({
    message: \`\"\$\{email\}\" was added to the mailing list. Thanks for signing up!\`,
    success: true,
  });
}`}/>

(I won't be going through this code in detail, as this is not a post about TS or React.)

Note that this API endpoint doesn't actually store the submitted email in a data store. However, if this were a real newsletter signup, the place to do it would likely be in the above file.

If we now check our test runner, we should see that the main user flow test ("allows for completing a newsletter signup") test is passing.

<Image src="/images/blog/e2e-testing/main-user-flow-passing.jpg" alt="Main user flow test passing." /> 
 
## Getting remaining tests to pass
We've written the minimum code needed to get the current tests to pass. However, there are still several requirements that need to be fulfilled, such as ensuring that emails are validly formed. You'll find the completed tests and the corresponding code to get them to pass in the [github repo](https://github.com/andersr/e2e-testing-tutorial).

## Refactor and clean up your code with confidence
Now that we have passing tests for all the feature requirements, we can reap the benefits of our efforts when refactoring.

For example, we may want to DRY up our code, which, at least in my experience, can often lead to unintentionally breaking things.  Additionally, I haven't added much in the way to styling, and that is also something we now can do with far less concern about breaking something.

## Next Up: Ensuring tests run automatically on every code push
Now that we've written some tests, let's be sure and put them to work.   In the next post, we'll show how to make sure your full test suite runs every time you push new code, and why that matters. [Continue to the next post in the series](/blog/e2e-series-ensure-tests-run-on-every-push).

Part of the E2E testing series.  A lot of tutorials focus on configuring and running E2E tests. Here we focus on how to approach writing the actual tests.

A Suggested Process For Writing E2E Tests


_This post is part of the [E2E Testing Series](/blog/e2e-testing-series). If you haven't already, I suggest going back and reading previous posts before continuing._

## Writing tests is only the beginning

We've walked through the process of how to write E2E tests. We showed the benefits of writing tests even before you write any code. And we showed the value of having your E2E tests running in watch mode to get quick feedback.

While this is all great, it's unfortunately not enough. While we're doing a great job of writing our tests we're still not going to get quick feedback on a general app regression. (Remember, when you are running tests in watch mode, that is only covering the current feature you are working on, and not on the full test suite.)

To achieve that, we need to ensure that our full test suite runs when we add new code and that we are notified about any failures before we merge the code.

These are the three main steps we'll complete in this post to achieve that goal:

1. Enable running the full test suite against a production build.
2. Automatically run the full suite when we push new code.
3. Prevent merge of code into the main branch unless all tests pass.

There are a number of tools and techniques we can use to achieve the above. In our case, we're going to use a combination of npm scripts, [Github Actions](https://docs.github.com/en/actions), and [Github branch protection](https://docs.github.com/en/repositories/configuring-branches-and-merges-in-your-repository/defining-the-mergeability-of-pull-requests/about-protected-branches).

Let's get started!

## Enable running the full test suite against a production build

Up until now, we've only been running the specific tests associated with the feature we are working on, and we've been running them against the development server. However, to prevent regression, we need to run all the tests, and run them against a production build. This is the version of your code that is served to users on the live site, and that is what we want to run our full test suite against.

### Add full test suite scripts

Most of what we need to do is to add the necessary scripts to run the full suite. Go ahead and make the following updates to `scripts` in your `package.json` file:

1. **Rename the `"build"` script to `"prestart"`.** This leverages a [scripts feature](https://docs.npmjs.com/cli/v8/using-npm/scripts) in npm, in which adding `pre` to another script will run that script first. In this case, we want to run a build before we run the `start` script, which is what is run to start the production server.
2. **Update the `start` script to use a different port:** Add ` -p 8080` to the end of the `"start"` script. This will allow for running the production server locally while also running the dev server, eg for debugging purposes. (Port 8080 is just my personal preference, you can pick a different port if you wish.)
3. **Add a script for running the full Cypress test suite:** `"cy:run": "cypress run --e2e --browser chrome --config baseUrl=http://localhost:8080"`. In contrast to the `"cy:open"` script, this will run the full test suite in [headless](https://www.softwaretestinghelp.com/headless-browser-testing/) mode, and we can use it both for local debugging and to run in a deployed environment. Note that the port used in `baseUrl` has to match what we use in the `start` script.
4. **Add a single command E2E script**: ` "e2e": "start-test start 8080 cy:run"`. This script pulls together all the other scripts above. We are first running the `start` script (which in turn will be preceded by the `prestart` build script), then waiting for a server to be listening on port 8080, and finally running the full test suite against that port. As before, this port has to match the two other ports you set previously.

Your `scripts` section should now include the following scripts:

<CodeBlock
  code={`"scripts": {
     ...
    "prestart": "next build",
    "start": "next start -p 8080",
     ...
    "cy:run": "cypress run --e2e --browser chrome --config baseUrl=http://localhost:8080",
    "e2e": "start-test start 8080 cy:run"
  },`}
/>

To make sure everything is working as expected, go ahead and run the `e2e` script, and you should see the entire above sequence being run, concluding with an 'All specs passed!' message in your terminal:

![Run all E2E tests locally with all tests passing](/images/blog/e2e-testing/e2e-run-all-tests-passing.jpg)

We'll be using this last script in the next section when pushing our code, but you can also use it locally for debugging purposes, such as when you are getting a test failure only when pushing code, but not seeing an error when running in watch mode.

## Automatically run the full suite when we push new code

As a reminder, this and the next step in this tutorial assumes you are using [github](https://github.com/) to store your code. There are many other options out there for achieving the same goal.

To ensure our `e2e` script runs on all new code that we push, we're going to add a [github action](https://docs.github.com/en/actions). Add the following to `.github/workflows/e2e.yml` (You must place the file in this directory, though the name `e2e` is my personal preference.)

<CodeBlock 
lang="bash"
code={`name: E2E Tests

on: [push] # ** 1 **

jobs:
cypress-run:
runs-on: ubuntu-20.04 # ** 2 **
steps: - name: Checkout
uses: actions/checkout@v2 - name: Cypress run
uses: cypress-io/github-action@v2 # ** 3 **
with:
command: npm run e2e # ** 4 **`}
/>

This code will be triggered when we push to a github repo.

### Code Notes

1. This is telling github to run this action every time we push new code.
2. This is the OS and version used for the virtual environment in which run our tests. I recommend always using a specific version, such as the latest stable version, rather than `latest`, which is risky because you may then suddenly start to see test failures caused by a version update that has nothing to do with your tests. See [virtual-enviroments](https://github.com/actions/virtual-environments) for the latest stable version.
3. We are using a ready-made [action](https://github.com/marketplace/actions/cypress-io) created by Cypress to run our tests.
4. This script name needs to match the `e2e` script we created earlier.

Go ahead and commit this code and [push it to a github repo](https://docs.github.com/en/get-started/importing-your-projects-to-github/importing-source-code-to-github/adding-locally-hosted-code-to-github).

Open up your repo in your browser and click on the ["Actions"](https://github.com/andersr/e2e-testing-tutorial/actions) tab, and you should see your action running.

![Github action running](/images/blog/e2e-testing/gh-e2e-action.jpg)

You can click into the action and see a detailed log of all the action steps.

## Prevent merge of code into the main branch unless all tests pass.

Just one more step to go!

Now that we've got our test running automatically on push, we want ensure that we don't merge code with failing tests. Similar to above, these instructions are specific to Github, but the general principles should be applicable regardless of the service you are using.

Achieving this requires setting up a branch protection rule.

### Protecting the main branch

The main branch (ie the branch containing code that will be pushed to production) is the one we need to protect from any code that contains regressions.

In github, we can add this protection by creating a branch rule, which should:

1. Not allow pushing code directly to the main branch, but instead require a pull request.
2. Require that all checks, in our case just the E2E tests, pass before merge is allowed.

You can find instructions for how to do add branch rules in the [github docs](https://docs.github.com/en/repositories/configuring-branches-and-merges-in-your-repository/defining-the-mergeability-of-pull-requests/about-protected-branches), but very briefly, in your repo, click on Settings > Branches > Add Rule.

In "Branch name pattern", enter the name of your main branch, eg "main" and check the box "Require a pull request before merging". (I'll also uncheck "Require reviews" for the purposes of this tutorial, but it's proabably a good idea to leave it checked.)

Next,check off "Require status check to pass before merging", which will prompt you to "search for status checks". Somewhat confusingly, a "status check" corresponds to the name of _job_ within an action rather than the name of the action itself. In our case, the name is `cypress-run` (which you'll see under `jobs:` in `.github/workflows/e2e.yml`.) Go ahead and type that in and you should see the job name to select.

Your form should look something like this:
![Adding main branch protection rule](/images/blog/e2e-testing/main-branch-protection-rule.jpg)

Scroll down and click on "Create".

## Testing that everything works

Let's make sure that our new branch rule works as expected. Go ahead and make a change to a test that you know will cause a failure, eg by adding an extra character to a test id.

To confirm that your test will fail, run your test suite locally using the `e2e` script.

Next, go ahead and commit the change and push your branch and [create a pull request](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-a-pull-request).

You should now see a message showing your checks have failed with the merge button disabled.

![Github message showing merges blocked](/images/blog/e2e-testing/gh-merges-blocked.jpg)

Now, undo the change you made and push again and this time you should (eventually) see all green checkmarks.

![Github PR all green checkmarks](/images/blog/e2e-testing/gh-pr-all-green-checks.jpg)

You've now set up a basic E2E testing system for writing tests and preventing code regressions! <Emoji symbol="🎉" label="celebrate" /> <Emoji symbol="🎉" label="celebrate" /> <Emoji symbol="🎉" label="celebrate" />

## Final Thoughts

This wraps up the E2E Testing Series. I hope you found it useful. If you want to keep learning, I recommend watching [this video](https://www.youtube.com/watch?v=5XQOK0v_YRE), in which the founder of Cypress talks about E2E testing best practices.


To help prevent regression, we want to make sure we run our full test every time we push our code.

Ensuring Your E2E Tests Run On Every Code Push


_This post is part of the [E2E Testing Series](/blog/e2e-testing-series).  If you haven't already, I suggest going back and reading previous posts before continuing._ 

<CalloutBox>
## Just give me the code...
Here is the "tl;dr" version of the article below, with just the commands to run and the code you'll need to add.  If anything isn't clear, I suggest reading the full post.

1. Install the sample app:
   <CodeBlock paddingRightOnly code={ `npx create-next-app e2e-testing --ts --use-npm`} />
1. Create a `src` directory and move the `pages` and `styles` directories into it.
2. Install these packages:
   <CodeBlock paddingRightOnly code={`npm i -D cypress cypress-watch-and-reload start-server-and-test`} />
2. Rename the `dev` script in your `package.json` to `dev:next`.
2. Add these scripts to your `package.json`:
   <CodeBlock paddingRightOnly code={`"cy:e2e": "cypress open --e2e --browser chrome --config baseUrl=http://localhost:3000",
   "dev": "start-test dev:next 3000 cy:e2e"`} />
3. Run `npm run dev` to initialize Cypress.
3. Update/add these files (click on the file link to view the code):
    - [`cypress.config.ts`](https://github.com/andersr/e2e-testing-tutorial/blob/main/cypress.config.ts)
    - [`cypress/support/e2e.js`](https://github.com/andersr/e2e-testing-tutorial/blob/main/cypress/support/e2e.ts)
    - [`cypress/tsconfig.json`](https://github.com/andersr/e2e-testing-tutorial/blob/main/cypress/tsconfig.json)
    - [`tsconfig.json`](https://github.com/andersr/e2e-testing-tutorial/blob/main/tsconfig.json)
4. Run the `dev` script to enable E2E test development with hot reloading of test and source files. 
</CalloutBox>

## Introduction: Keeping E2E tests front and center
One of most common anti-patterns I see relating to E2E testing is that, while a test suite has been set up and some tests have been written, it is almost never run locally and new tests are only rarely added for new features. This obviously is not a good thing, since we effectively are wasting all the effort that went into setting up the test suite.

But why would we let such a valuable resource go to waste?

One simple answer is that it is out of sight, out of mind.  In other words, while the command to run the E2E test locally does exist, it's something you have to remember to do, and it's kind of a hassle, since you usually have to first fire up the dev environment, and then starte the E2E runner in a second terminal.

One way to address this problem is to automate running of the E2E test suite whenever you start up your development environment.  As we'll see, this can have a significant positive impact on your E2E practice.

## Add a single command for starting both dev environment and test runner
To help ensure E2E tests get written, we want to make it is easy to have both our app running and the test runner in a hot-reloading state. In other words, as we write tests, we want to be able to get quick feedback on if tests are passing or not.

When we are done with the steps below, you'll be able to just run `npm run dev` to both start you dev environment and also start up your E2E test runner in dev mode, meaning that it will rerun tests automatically if changes are made either to the tests or your code. As an added bonus, it will reduce the amount of terminal windows you have open in your IDE.

## Setting up our sample app

We'll be using [NextJS](https://nextjs.org/) as the basis for our sample app. One reason for this is that our newsletter feature will require an API endpoint, and NextJS makes it super easy to add that.

To get started, go ahead and run the following to install the sample app:

<CodeBlock code={`npx create-next-app e2e-testing --ts --use-npm`}/>

You can replace `e2e-testing` with any app name you prefer. Both the `--ts` and `--use-npm` are optional.  NPM is just my personal preference, and I am a strong proponent of using TypeScript.


## Install the E2E test runner and utility packages
For this tutorial, we're going to use [Cypress](https://www.cypress.io/), which in my opinion currently is the best end-to-end testing solution. (My one gripe with Cypress is the [lack of support](https://github.com/cypress-io/cypress/issues/6423) for testing of older browsers, which are the ones often causing regressions.)

Let's install all the packages we'll need, as development dependencies: 
<CodeBlock 
code={`npm i -D cypress cypress-watch-and-reload start-server-and-test`}
/>

### Add the dev scripts
Next, let's update the `scripts` section of our `package.json` as follows:

First, rename the `dev` script to `dev:next`.  Then, add the following scripts:

<CodeBlock 
code={`"scripts": {
    ...
    "cy:e2e": "cypress open --e2e --browser chrome --config baseUrl=http://localhost:3000",
    "dev": "start-test dev:next 3000 cy:e2e"
    ...
}`}
/>

## Configuring Cypress 
We need to configure Cypress to use TypeScript and also to hot reload when our source files change.

### Add Typescript support
Cypress has built-in [Typescript support](https://docs.cypress.io/guides/tooling/typescript-support). To enable it, and allow for writing TS-based tests, we need to add a `tsconfig.json` to the root of the `cypress` folder.

Add the following code to `cypress/tsconfig.json` and you should now be able to create test files using Typescript.

<CodeBlock 
code={`{
  "compilerOptions": {
    "target": "es5",
    "lib": ["es5", "dom"],
    "types": ["cypress"]
  },
  "include": ["**/*.ts"]
}`}
/>

Also, update the main `tsconfig.json` in the root directory to exclude the cypress directory, so we do not compile test files as part of compiling the main source code. 

<CodeBlock code={`{
  ...
  "exclude": ["node_modules", "cypress"]
}
`}/>


### Get Cypress to hot reload if your source files change
By default, the Cypress runner will only re-run if you modify test files.  However, we really also want it to restart when we make changes to our code.  To achieve this, we need to make the following updates:

First, update `cypress.config.ts` as follows:

<CodeBlock code={`import Cypress, { defineConfig } from "cypress";

interface Config extends Cypress.UserConfigOptions<any> {
  "cypress-watch-and-reload": {
    watch: string | string[]
  }
}

const config: Partial<Config> = {
  "cypress-watch-and-reload": {
    watch: ["src/**/*"],
  },
  e2e: {
    setupNodeEvents(on, config) {
      return require("cypress-watch-and-reload/plugins")(on, config);
    },
  },
}

export default defineConfig(config);`}/>

Next, add the following to the end of the file `cypress/support/e2e.ts`.

<CodeBlock code={`require("cypress-watch-and-reload/support");`}/>

Your local environment and `dev` command should now be set up.

Go ahead and run `npm run dev` and you should see the dev server first start up, then the test runner will start. The first time you run Cypress, you may be asked to click through their startup wizard.

Btw, a huge shout-out to [Gleb Bahmutov](https://glebbahmutov.com/) who is the author of both the utility packages we are using here! <Emoji symbol="👏" label="clap emoji" /> <Emoji symbol="👏" label="clap emoji" /> <Emoji symbol="👏" label="clap emoji" />

## Next Up: A Suggested Process for writing E2E tests
Since we haven't written any tests, Cypress will prompt you to add some.

![Newsletter signup form](/images/blog/e2e-testing/cypress-runner-no-specs.jpg)

In the [next part in the series](/blog/e2e-series-a-process-for-writing-tests), we'll be focusing on exactly that.


Ensure E2E tests get written by running both your dev environment and your E2E test runner with a single command. Also, learn about writing resilient tests using test ids.

How to set up a local E2E test development environment


## Introduction
This is a series of posts I've written about the process and benefits of writing and using End to End Tests (E2E). We'll walk through how to set up your system to write them, how to use the tests you've created to stay focused, and,last not least, how to use E2E tests to prevent [code regression](https://www.google.com/search?q=code+regression).

I've broken the series into the following parts:

1. **Series intro and prerequisites (current post).**
2. [Setting up your local environment for writing E2E tests](/blog/e2e-series-setting-up-your-local-environment).
2. [A suggested process for writing tests](/blog/e2e-series-a-process-for-writing-tests).
2. [Ensuring your test suite runs every time you push code](/blog/e2e-series-ensure-tests-run-on-every-push).

In this post, I'll offer a general intro to E2E testing and assumed prerequisites. I hope you find it useful.  Please feel free to post feedback in the comments.

## What are E2E tests and why should you care?
One good way to understand E2E testing is to look at what can happen without it.

### A project without E2E testing
You're working on a project that doesn't have any formal E2E testing in place.

Let's say you're adding a newsletter signup form to your web app. 

![Newsletter signup form](/images/blog/e2e-testing/newsletter-form-styled.jpg)

To keep your code [DRY](https://en.wikipedia.org/wiki/Don%27t_repeat_yourself), you re-use existing input and form submit components to implement your form. You test the form locally and everything is working great. You also click around your web app and everything else seems to be working great as well.

However, after deploying your code, you start getting notices that users no longer can reset their passwords. <Emoji symbol="😱" label="horror emoji" />  <Emoji symbol="😱" label="horror emoji" />  <Emoji symbol="😱" label="horror emoji" /> 

But wait, you were working on newsletter signup, how could that possibly break password reset?

Actually, as it turns out, the password reset form uses some of the same components that you used when implementing newsletter signup.

![Password reset form](/images/blog/e2e-testing/password-reset-form.jpg)

When you made some tweaks to those components (maybe you decided to rename a prop) while adding the newsletter feature, you unintentionally broke the reset feature.  Worse, since that feature is out of sight, out of mind, you didn't think to test it before shipping newsletter signup.

This is an example of what we call a [code regression](https://en.wikipedia.org/wiki/Software_regression), where something that previously worked unexpectedly stops working, and it is one of the main reasons we write E2E tests.

### E2E testing to the rescue
If you'd had an E2E testing system in place, such as the one we'll be creating, and you had good feature coverage in your tests, after modifying the components being used in password reset, you'd have received a test failure notification, and then be able to quickly address the problem, preventing a reset password failure in production.

As apps get more complex and more feature-rich, and as we get better at re-using code across our apps, the risk of regression increases, so writing these types of tests and ensuring we run them regularly becomes increasingly important.

In this series, we're going to walk through the process of setting yourself up for success by enabling quickly and effectively writing these types of tests, running them locally against your development environment to get quick feedback on possible issues, and then automatically running the full suite of tests every time you push code, to prevent merging in code that will lead to regressions.

We'll also discuss how integrating E2E tests into your development process can you help you write better code overall and help ensure that you remain focused on your goals.

In my opinion, E2E tests are the most valuable test type, because they simulate actual end users and are focused on outcomes rather than implementation details. However, while valuable, these types of tests can also be costly, in that setting up your system to run them and writing the tests themselves can be complex and time-consuming. And as your test suite grows in size, they can take a long time to run.

But here's the thing: if done right, you can overcome these challenges, and get the best of both worlds. Achieving that is one of the top goals of this series.
<CalloutBox>
## A quick note about terminology
I am using the term "E2E" or End to End Testing a bit loosely here. Some might call the types of tests we are writing a functional test, or you may have a different name.  There are countless names and nuances for different types of tests, such as smoke test, integration test, regression test, and more, many of them overlapping.

It's easy to get caught up in the terminology and lose sight of the actual goals, such as writing higher quality code and preventing stuff from breaking.  I prefer just using E2E as an umbrella term for any type of test that simulates a user using the app and which treats the app itself as a black box, just as a real user would. (I.e. they don't know and don't care about the inner workings of the app.)
</CalloutBox>


## Prerequisites
- I am assuming you already have some experience with JavaScript generally and specifically with React and Node.
- I'm also assuming you already have the latest stable version of Node and npm installed on your machine.
- I'll be writing the sample code mostly in Typescript so I am assuming you are familiar with that as well.
- Finally, I am assuming you have some experience using git, as we'll be using that in the last part of the series, to create branches, pull requests, and more.

However, to be clear, many of the principles we discuss will be agnostic to whatever language or tool you're using.

## Code Repo
You can find all the source code we'll be walking through below [in this repo](https://github.com/andersr/e2e-testing-tutorial).  I recommend writing your own code rather than just copying from the repo, but you might find it to be a good reference in case you get stuck.

## Next up: Setting up your local testing environment
To get started, we'll install a sample app and set up our development environment for testing.  [Continue to the next post in the series](/blog/e2e-series-setting-up-your-local-environment).


A series of posts on how to configure and write valuable E2E tests.

Hi, I'm Anders Ramsay.
I designing and building digital products.

Hi, I'm Anders Ramsay.
I designing and building digital products.

Recent Posts

A Suggested Process For Writing E2E Tests

Ensuring Your E2E Tests Run On Every Code Push

How to set up a local E2E test development environment

E2E Testing Series

Previous Blog Posts

Hi, I'm Anders Ramsay. I love designing and building digital products.

Hi, I'm Anders Ramsay. I love designing and building digital products.

Recent Posts

A Suggested Process For Writing E2E Tests

Ensuring Your E2E Tests Run On Every Code Push

How to set up a local E2E test development environment

E2E Testing Series

Previous Blog Posts

Hi, I'm Anders Ramsay.
I designing and building digital products.

Hi, I'm Anders Ramsay.
I designing and building digital products.