Next.js 中文网

主题

Jest ​

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

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

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

¥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

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

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

bash
npx create-next-app@latest --example with-jest with-jest-app

手动设置 ​

¥Manual setup

自 Next.js 12 发布以来，Next.js 现在具有 Jest 的内置配置。

¥Since the release of Next.js 12, Next.js now has built-in configuration for Jest.

要设置 Jest，请安装 jest 和以下软件包作为开发依赖：

¥To set up Jest, install jest and the following packages as dev dependencies:

bash
npm install -D jest jest-environment-jsdom @testing-library/react @testing-library/dom @testing-library/jest-dom ts-node @types/jest
# or
yarn add -D jest jest-environment-jsdom @testing-library/react @testing-library/dom @testing-library/jest-dom ts-node @types/jest
# or
pnpm install -D jest jest-environment-jsdom @testing-library/react @testing-library/dom @testing-library/jest-dom ts-node @types/jest

通过运行以下命令生成基本的 Jest 配置文件：

¥Generate a basic Jest configuration file by running the following command:

bash
npm init jest@latest
# or
yarn create jest@latest
# or
pnpm create jest@latest

这将引导你完成一系列提示，为你的项目设置 Jest，包括自动创建 jest.config.ts|js 文件。

¥This will take you through a series of prompts to setup Jest for your project, including automatically creating a jest.config.ts|js file.

更新你的配置文件以使用 next/jest。该转换器具有 Jest 与 Next.js 配合使用所需的所有配置选项：

¥Update your config file to use next/jest. This transformer has all the necessary configuration options for Jest to work with Next.js:

ts
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)

在后台，next/jest 会自动为你配置 Jest，包括：

¥Under the hood, next/jest is automatically configuring Jest for you, including:

  • 使用 Next.js 编译器 设置 transform。

    ¥Setting up transform using the Next.js Compiler.

  • 自动模拟样式表（.css、.module.css 及其 scss 变体）、图片导入和 next/font。

    ¥Auto mocking stylesheets (.css, .module.css, and their scss variants), image imports and next/font.

  • 将 .env（和所有变体）加载到 process.env 中。

    ¥Loading .env (and all variants) into process.env.

  • 忽略 node_modules 中的测试解析和转换。

    ¥Ignoring node_modules from test resolving and transforms.

  • 忽略 .next 中的测试解析。

    ¥Ignoring .next from test resolving.

  • 加载 next.config.js 以获取启用 SWC 转换的标志。

    ¥Loading next.config.js for flags that enable SWC transforms.

需要了解：要直接测试环境变量，请在单独的安装脚本或 jest.config.ts 文件中手动加载它们。欲了解更多信息，请参阅 测试环境变量。

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

设置 Jest（使用 Babel） ​

¥Setting up Jest (with Babel)

如果你选择退出 Next.js 编译器 并使用 Babel，则除了上述软件包外，你还需要手动配置 Jest 并安装 babel-jest 和 identity-obj-proxy。

¥If you opt out of the Next.js Compiler and use Babel instead, you will need to manually configure Jest and install babel-jest and identity-obj-proxy in addition to the packages above.

以下是为 Next.js 配置 Jest 的推荐选项：

¥Here are the recommended options to configure Jest for Next.js:

你可以在 Jest 文档 中了解有关每个配置选项的更多信息。我们还建议你查看 next/jest 配置，了解 Next.js 如何配置 Jest。

¥You can learn more about each configuration option in the Jest docs. We also recommend reviewing next/jest configuration to see how Next.js configures Jest.

处理样式表和图片导入 ​

¥Handling stylesheets and image imports

测试中不会使用样式表和图片，但导入它们可能会导致错误，因此需要对它们进行模拟。

¥Stylesheets and images aren't used in the tests but importing them may cause errors, so they will need to be mocked.

创建上述配置中引用的模拟文件 - fileMock.js 和 styleMock.js - __mocks__ 目录中：

¥Create the mock files referenced in the configuration above - fileMock.js and styleMock.js - inside a __mocks__ directory:

有关处理静态资源的更多信息，请参阅 Jest 文档。

¥For more information on handling static assets, please refer to the Jest Docs.

处理字体 ​

¥Handling Fonts

要处理字体，请在 __mocks__ 目录中创建 nextFontMock.js 文件，并添加以下配置：

¥To handle fonts, create the nextFontMock.js file inside the __mocks__ directory, and add the following configuration:

可选的：处理绝对导入和模块路径别名 ​

¥Optional: Handling Absolute Imports and Module Path Aliases

如果你的项目使用 模块路径别名，则需要配置 Jest 以通过将 jsconfig.json 文件中的 paths 选项与 jest.config.js 文件中的 moduleNameMapper 选项匹配来解析导入。例如：

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

可选的：使用自定义匹配器扩展 Jest ​

¥Optional: Extend Jest with custom matchers

@testing-library/jest-dom 包括一组方便的 自定义匹配器（例如 .toBeInTheDocument()），使编写测试变得更容易。你可以通过将以下选项添加到 Jest 配置文件来为每个测试导入自定义匹配器：

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

ts
setupFilesAfterEnv: ['<rootDir>/jest.setup.ts']

然后，在 jest.setup 内添加以下导入：

¥Then, inside jest.setup, add the following import:

ts
import '@testing-library/jest-dom'

需要了解：extend-expect 于 v6.0 被删除，因此如果你在版本 6 之前使用 @testing-library/jest-dom，则需要导入 @testing-library/jest-dom/extend-expect。

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

如果你需要在每次测试前添加更多设置选项，可以将它们添加到上面的 jest.setup 文件中。

¥If you need to add more setup options before each test, you can add them to the jest.setup file above.

向 package.json 添加测试脚本 ​

¥Add a test script to package.json

最后，将 Jest test 脚本添加到 package.json 文件中：

¥Finally, add a Jest test script to your package.json file:

当文件更改时，jest --watch 将重新运行测试。有关更多 Jest CLI 选项，请参阅 Jest 文档。

¥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

你的项目现在已准备好运行测试。在项目的根目录中创建一个名为 __tests__ 的文件夹。

¥Your project is now ready to run tests. Create a folder called __tests__ in your project's root directory.

例如，我们可以添加一个测试来检查 <Home /> 组件是否成功渲染标题：

¥For example, we can add a test to check if the <Home /> component successfully renders a heading:

（可选）添加 快照测试 来跟踪组件中的任何意外更改：

¥Optionally, add a snapshot test to keep track of any unexpected changes in your component:

需要了解：测试文件不应包含在 Pages 路由中，因为 Pages 路由内的任何文件都被视为路由。

¥Good to know: Test files should not be included inside the Pages Router because any files inside the Pages Router are considered routes.

运行你的测试 ​

¥Running your tests

然后，运行以下命令来运行测试：

¥Then, run the following command to run your tests:

bash
npm run test
# or
yarn test
# or
pnpm test

其他资源 ​

¥Additional Resources

为了进一步阅读，你可能会发现这些资源很有帮助：

¥For further reading, you may find these resources helpful: