Skip to main content

使用 Next.js 设置 Vitest

Vite 和 React 测试库经常一起用于单元测试。本指南将向你展示如何使用 Next.js 设置 Vitest 并编写你的第一个测试。

¥Vite 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.

很高兴知道：由于 async 服务器组件对于 React 生态系统来说是新的，Vitest 目前不支持它们。虽然你仍然可以对同步服务器和客户端组件运行单元测试，但我们建议对 async 组件使用 E2E 测试。

¥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 an E2E tests for async components.

快速开始​

¥Quickstart

你可以将 create-next-app 与 Next.js with-vitest 示例结合使用来快速入门：

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

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

手动设置​

¥Manual Setup

要手动设置 Vitest，请安装 vitest 和以下软件包作为开发依赖：

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

npm install -D vitest @vitejs/plugin-react jsdom @testing-library/react @testing-library/dom
# or
yarn add -D vitest @vitejs/plugin-react jsdom @testing-library/react @testing-library/dom
# or
pnpm install -D vitest @vitejs/plugin-react jsdom @testing-library/react @testing-library/dom
# or
bun add -D vitest @vitejs/plugin-react jsdom @testing-library/react @testing-library/dom

在项目的根目录中创建一个 vitest.config.ts|js 文件，并添加以下选项：

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

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

export default defineConfig({
  plugins: [react()],
  test: {
    environment: 'jsdom',
  },
})
import { defineConfig } from 'vitest/config'
import react from '@vitejs/plugin-react'

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

有关配置 Vitest 的更多信息，请参阅 维测试配置 文档。

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

然后，将 test 脚本添加到 package.json 中：

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

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

当你运行 npm run test 时，Vitest 将默认监视你项目中的更改。

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

创建你的第一个 Vitest 单元测试​

¥Creating your first Vitest Unit Test

通过创建一个测试来检查 <Page /> 组件是否成功渲染标题来检查一切是否正常：

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

import Link from 'next/link'

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

export default function Page() {
  return (
    <div>
      <h1>Home</h1>
      <Link href="/about">About</Link>
    </div>
  )
}
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()
})
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__ 约定，但测试文件也可以位于 app 路由内部。

¥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:

npm run test
# or
yarn test
# or
pnpm test
# or
bun test

其他资源​

¥Additional Resources

你可能会发现这些资源很有帮助：

¥You may find these resources helpful: