Setting up Jest with Next.js
Jest and React Testing Library are frequently used together for Unit Testing and Snapshot Testing . This guide will show you how to set up Jest with Next.js and write your first tests.
Good to know:
Since
async
Server Components are new to the React ecosystem, Jest currently does not support them. While you can still run
unit tests
for synchronous Server and Client Components, we recommend using an
E2E tests
for
async
components.
Quickstart
You can use
create-next-app
with the Next.js
with-jest
example to quickly get started:
npx create-next-app@latest --example with-jest with-jest-appManual setup
Since the release of Next.js 12 , Next.js now has built-in configuration for Jest.
To set up Jest, install
jest
and the following packages as dev dependencies:
npm install -D jest jest-environment-jsdom @testing-library/react @testing-library/dom @testing-library/jest-dom ts-node
yarn add -D jest jest-environment-jsdom @testing-library/react @testing-library/dom @testing-library/jest-dom ts-node
pnpm install -D jest jest-environment-jsdom @testing-library/react @testing-library/dom @testing-library/jest-dom ts-nodeGenerate a basic Jest configuration file by running the following command:
npm init jest@latest
yarn create jest@latest
pnpm create jest@latest
This will take you through a series of prompts to setup Jest for your project, including automatically creating a
jest.config.ts|js
file.
Update your config file to use
next/jest
. This transformer has all the necessary configuration options for Jest to work with Next.js:
import type { Config } from 'jest'
import nextJest from 'next/jest.js'
const createJestConfig = nextJest({
// Provide the path to your Next.js app to load next.config.js and .env files in your test environment
dir: './',
// Add any custom config to be passed to Jest
const config: Config = {
coverageProvider: 'v8',
testEnvironment: 'jsdom',
// Add more setup options before each test is run
// setupFilesAfterEnv: ['<rootDir>/jest.setup.ts'],
// createJestConfig is exported this way to ensure that next/jest can load the Next.js config which is async
export default createJestConfig(config)
Under the hood,
next/jest
is automatically configuring Jest for you, including:
transform
using the
Next.js Compiler
.css
,
.module.css
, and their scss variants), image imports and
next/font
.env
(and all variants) into
process.env
node_modules
from test resolving and transforms
.next
from test resolving
next.config.js
for flags that enable SWC transforms
Good to know
: To test environment variables directly, load them manually in a separate setup script or in your
jest.config.ts
file. For more information, please see
Test Environment Variables
.
Optional: Handling Absolute Imports and Module Path Aliases
If your project is using
Module Path Aliases
, you will need to configure Jest to resolve the imports by matching the paths option in the
jsconfig.json
file with the
moduleNameMapper
option in the
jest.config.js
file. For example:
{
"compilerOptions": {
"module": "esnext",
"moduleResolution": "bundler",
"baseUrl": "./",
"paths": {
"@/components/*": ["components/*"]
jest.config.jsmoduleNameMapper: {
// ...
'^@/components/(.*)$': '<rootDir>/components/$1',
Optional: Extend Jest with custom matchers
@testing-library/jest-dom includes a set of convenient custom matchers such as .toBeInTheDocument() making it easier to write tests. You can import the custom matchers for every test by adding the following option to the Jest configuration file:
jest.config.tssetupFilesAfterEnv: ['<rootDir>/jest.setup.ts']
Then, inside jest.setup.ts, add the following import:
jest.setup.tsimport '@testing-library/jest-dom'
Good to know:extend-expect was removed in v6.0, so if you are using @testing-library/jest-dom before version 6, you will need to import @testing-library/jest-dom/extend-expect instead.
If you need to add more setup options before each test, you can add them to the jest.setup.js file above.
Add a test script to package.json:
jest --watch will re-run tests when a file is changed. For more Jest CLI options, please refer to the Jest Docs.
Creating your first test:Your project is now ready to run tests. Create a folder called __tests__ in your project's root directory.
For example, we can add a test to check if the <Page /> component successfully renders a heading:
import Link from 'next/link'
export default function Page() {
return (
<h1>Home</h1>
<Link href="/about">About</Link>
</div>
}
__tests__/page.test.jsximport '@testing-library/jest-dom'
import { render, screen } from '@testing-library/react'
import Page from '../app/page'
describe('Page', () => {
it('renders a heading', () => {
render(<Page />)
const heading = screen.getByRole('heading', { level: 1 })
expect(heading).toBeInTheDocument()
Optionally, add a snapshot test to keep track of any unexpected changes in your component:
__tests__/snapshot.jsimport { render } from '@testing-library/react'
import Page from '../app/page'
it('renders homepage unchanged', () => {
const { container } = render(<Page />)
expect(container).toMatchSnapshot()
Running your tests