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 forasync
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-app
Manual 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/jest-dom
# or
yarn add -D jest jest-environment-jsdom @testing-library/react @testing-library/jest-dom
# or
pnpm install -D jest jest-environment-jsdom @testing-library/react @testing-library/jest-dom
Generate a basic Jest configuration file by running the following command:
npm init jest@latest
# or
yarn create jest@latest
# or
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:
- Setting up
transform
using the Next.js Compiler - Auto mocking stylesheets (
.css
,.module.css
, and their scss variants), image imports andnext/font
- Loading
.env
(and all variants) intoprocess.env
- Ignoring
node_modules
from test resolving and transforms - Ignoring
.next
from test resolving - Loading
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/*"]
}
}
}
moduleNameMapper: {
// ...
'^@/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:
setupFilesAfterEnv: ['<rootDir>/jest.setup.ts']
Then, inside jest.setup.ts
, add the following import:
import '@testing-library/jest-dom'
Good to know:
extend-expect
was removed inv6.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
:
Finally, add a Jest test
script to your package.json
file:
{
"scripts": {
"dev": "next dev",
"build": "next build",
"start": "next start",
"test": "jest",
"test:watch": "jest --watch"
}
}
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 Home() {
return (
<div>
<h1>Home</h1>
<Link href="/about">About</Link>
</div>
)
}
import '@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:
import { render } from '@testing-library/react'
import Page from '../app/page'
it('renders homepage unchanged', () => {
const { container } = render(<Page />)
expect(container).toMatchSnapshot()
})
Running your tests
Then, run the following command to run your tests:
npm run test
# or
yarn test
# or
pnpm test
Additional Resources
For further reading, you may find these resources helpful:
- Next.js with Jest example
- Jest Docs
- React Testing Library Docs
- Testing Playground - use good testing practices to match elements.
Was this helpful?