Setting Up Cypress for End-to-End Testing in Next.js with TypeScript

Introduction

In the fast-changing world of web development, making sure your app works well is key. This blog post shows how to easily use Cypress, Next.js, and TypeScript together for solid testing. I'll walk you through setting up Cypress with Next.js and TypeScript in the best way possible, so you get a smooth and effective setup divided into actionable steps.

Prequisites

Before we get going, make sure you've got a project set up in Next.js with TypeScript, no matter when you first created it. No need to wait around—let's dive straight into the next steps.

Step 1: Install Dependencies

Let's level up our Cypress testing setup. Now, we're bringing in Cypress and its sidekick, concurrently, to the party. These tools are more backstage players(Dev Dependencies), not stealing the limelight in production. Think of concurrently as a helper, letting us run multiple npm commands at the same time. We'll put this to use when setting up scripts in the package.json file.

Install the required dependencies seamlessly with your favorite package manager. For npm, execute the command: npm install -D cypress concurrently. Similarly, for yarn or pnpm, pnpm install -D cypress concurrently , yarn add -D cypress concurrently

Step 2: TypeScript Configuration

When I set up Cypress for my TypeScript-based Next.js project, I hit a snag with the TypeScript configuration in the Cypress GUI. In case you too fins that error on opeing and setting up cypress through npx cypress open, you have the answer in this section. In case you do not run into any problems skip this section.

Now, despite my efforts to find a straightforward solution, I couldn't locate clear answers. After hours of research, I finally identified the issue. It was clear that the error traced back to the tsconfig.file, the maestro directing the TypeScript compiler. Specifically, the hiccup was tied to the moduleResolution option set to bundler. Next.js with TypeScript defaults to this setting for new projects, but it doesn't play nice with Cypress, leading to those pesky errors.

The solution? A simple switch of this option to node, and presto! The errors vanished into thin air. The moduleResolution property in a TypeScript tsconfig.json file pulls the strings on how the TypeScript compiler sorts out module names. It's a key player in the game of finding and importing modules in your TypeScript project. There are two main values for the moduleResolution property: node and bundler.

When set to node, TypeScript uses the Node.js-style module resolution algorithm. It means TypeScript goes hunting for modules in directories using Node.js's module resolution strategy, including a peek inside node_modules folders. This default setting suits projects following Node.js module resolution conventions.

On the flip side, when moduleResolution is set to bundler, TypeScript switches to a different module resolution strategy often linked with bundlers like Webpack. It's tailor-made for bundlers, letting them handle module resolution and bundling during the build process. Sounds good, but it can ruffle feathers with Cypress. Why? Well, Cypress, being a testing whiz, operates in a Node.js environment, and the clash with the bundler resolution can stir up errors.

So, the smart move? Flip the moduleResolution option from bundler to node in the tsconfig.json file. It won't harm your Next.js project and keeps things running smoothly with Cypress.

For your convenience, here's a snippet of my tsconfig.json for a Next.js TypeScript project ready to roll with Cypress.

{
  "compilerOptions": {
    "target": "es5",
    "lib": ["dom", "dom.iterable", "esnext"],
    "allowJs": true,
    "skipLibCheck": true,
    "strict": true,
    "forceConsistentCasingInFileNames": true,
    "noEmit": true,
    "esModuleInterop": true,
    "module": "esnext",
    "moduleResolution": "node",
    "resolveJsonModule": true,
    "isolatedModules": true,
    "jsx": "preserve",
    "incremental": true,
    "plugins": [
      {
        "name": "next"
      }
    ],
    "paths": {
      "@/*": ["./src/*"]
    }
  },
  "include": ["next-env.d.ts", "**/*.ts", "**/*.tsx", ".next/types/**/*.ts"],
  "exclude": ["node_modules"]
}

Step 3: Package.json Scripts

Enough talk, let’s now empower our Next.js TypeScript project with the robust testing capabilities of Cypress! In this section, I'll walk you through adding Cypress to your project by including some essential scripts. Below are the scripts I've cooked up for you to seamlessly integrate into your own project. Just toss them into the scripts section of your package.json file.

"e2e": "concurrently \"npm run dev\" \"cypress open --e2e\"",
"e2e:cli": "concurrently \"npm run dev\" \"cypress run --e2e\"",
"component": "cypress open --component",
"component:cli": "cypress run --component"

Step 4: Cypress Configuration

Now, let's make life easier with Cypress by setting up a configuration file, cypress.config.ts, right in your project's root. Below is a sample configuration ready for you to use. Feel free to tweak the baseUrl option to fit your project's unique needs and context. Keep things tailored to your liking!

import { defineConfig } from "cypress";

export default defineConfig({
  e2e: {
    // baseUrl: "http://localhost:3000",
  },
  component: {
    devServer: {
      framework: "next",
      bundler: "webpack",
    },
  },
});

Start using cypress with npx cypress open

Conclusion

Congrats on reaching the end of this guide! You've skillfully steered through the integration of Cypress into your Next.js TypeScript project. By fine-tuning TypeScript settings, injecting crucial scripts, and crafting a dedicated Cypress configuration file, you've paved the way for sturdy testing.

Feel the freedom to explore and tailor the provided configurations to match your project's unique demands. Now, go ahead and dive into testing bliss!