How to set up Vitest with Next.js | Next.js 简体中文

Vitest and React Testing Library are frequently used together for Unit Testing. This guide will show you how to setup Vitest with Next.js and write your first tests.

Good to know

Since async Server Components are new to the React ecosystem, Vitest currently does not support them. While you can still run unit tests for synchronous Server and Client Components, we recommend using E2E tests for async components.

Quickstart

You can use create-next-app with the Next.js with-vitest example to quickly get started:

pnpm

npm

yarn

bun

pnpm create next-app --example with-vitest with-vitest-app

npx create-next-app@latest --example with-vitest with-vitest-app

yarn create next-app --example with-vitest with-vitest-app

bun create next-app --example with-vitest with-vitest-app

Manual Setup

To manually set up Vitest, install vitest and the following packages as dev dependencies:

pnpm

npm

yarn

bun

# Using TypeScript
pnpm add -D vitest @vitejs/plugin-react jsdom @testing-library/react @testing-library/dom vite-tsconfig-paths
# Using JavaScript
pnpm add -D vitest @vitejs/plugin-react jsdom @testing-library/react @testing-library/dom

# Using TypeScript
npm install -D vitest @vitejs/plugin-react jsdom @testing-library/react @testing-library/dom vite-tsconfig-paths
# Using JavaScript
npm install -D vitest @vitejs/plugin-react jsdom @testing-library/react @testing-library/dom

# Using TypeScript
yarn add -D vitest @vitejs/plugin-react jsdom @testing-library/react @testing-library/dom vite-tsconfig-paths
# Using JavaScript
yarn add -D vitest @vitejs/plugin-react jsdom @testing-library/react @testing-library/dom

# Using TypeScript
bun add -D vitest @vitejs/plugin-react jsdom @testing-library/react @testing-library/dom vite-tsconfig-paths
# Using JavaScript
bun add -D vitest @vitejs/plugin-react jsdom @testing-library/react @testing-library/dom

Create a vitest.config.mts|js file in the root of your project, and add the following options:

TypeScript

JavaScript

vitest.config.mts

import { defineConfig } from 'vitest/config'
import react from '@vitejs/plugin-react'
import tsconfigPaths from 'vite-tsconfig-paths'

export default defineConfig({
  plugins: [tsconfigPaths(), react()],
  test: {
    environment: 'jsdom',
  },
})

vitest.config.js

import { defineConfig } from 'vitest/config'
import react from '@vitejs/plugin-react'

export default defineConfig({
  plugins: [react()],
  test: {
    environment: 'jsdom',
  },
})

For more information on configuring Vitest, please refer to the Vitest Configuration docs.

Then, add a test script to your package.json:

package.json

{
  "scripts": {
    "dev": "next dev",
    "build": "next build",
    "start": "next start",
    "test": "vitest"
  }
}

When you run npm run test, Vitest will watch for changes in your project by default.

Creating your first Vitest Unit Test

Check that everything is working by creating a test to check if the <Page /> component successfully renders a heading:

TypeScript

JavaScript

app/page.tsx

import Link from 'next/link'

export default function Page() {
  return (
    <div>
      <h1>Home</h1>
      <Link href="/about">About</Link>
    </div>
  )
}

app/page.jsx

import Link from 'next/link'

export default function Page() {
  return (
    <div>
      <h1>Home</h1>
      <Link href="/about">About</Link>
    </div>
  )
}

TypeScript

JavaScript

__tests__/page.test.tsx

import { expect, test } from 'vitest'
import { render, screen } from '@testing-library/react'
import Page from '../app/page'

test('Page', () => {
  render(<Page />)
  expect(screen.getByRole('heading', { level: 1, name: 'Home' })).toBeDefined()
})

__tests__/page.test.jsx

import { expect, test } from 'vitest'
import { render, screen } from '@testing-library/react'
import Page from '../app/page'

test('Page', () => {
  render(<Page />)
  expect(screen.getByRole('heading', { level: 1, name: 'Home' })).toBeDefined()
})

Good to know

The example above uses the common __tests__ convention, but test files can also be colocated inside the app router.

Running your tests

Then, run the following command to run your tests:

pnpm

npm

yarn

bun

pnpm test

npm run test

yarn test

bun run test

Additional Resources

You may find these resources helpful: