如何在 Next.js 中設定 Jest

Jest 和 React Testing Library 經常一起用於單元測試 (Unit Testing) 和快照測試 (Snapshot Testing)。本指南將展示如何在 Next.js 中設定 Jest 並撰寫您的第一個測試。

須知事項： 由於 async 伺服器元件 (Server Components) 對 React 生態系統來說是新功能，Jest 目前不支援它們。雖然您仍然可以對同步的伺服器元件和客戶端元件 (Client Components) 進行單元測試，但我們建議對 async 元件使用端到端測試 (E2E tests)。

快速開始

您可以使用 create-next-app 搭配 Next.js 的 with-jest 範例快速開始：

終端機

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

手動設定

自從 Next.js 12 發布後，Next.js 現在內建了對 Jest 的配置支援。

要設定 Jest，請安裝 jest 和以下套件作為開發依賴：

終端機

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

執行以下命令生成基本的 Jest 配置檔：

終端機

npm init jest@latest
# 或
yarn create jest@latest
# 或
pnpm create jest@latest

這將引導您完成一系列提示來為專案設定 Jest，包括自動建立 jest.config.ts|js 檔案。

更新您的配置檔以使用 next/jest。這個轉換器包含了 Jest 與 Next.js 協作所需的所有配置選項：

import type { Config } from 'jest'
import nextJest from 'next/jest.js'

const createJestConfig = nextJest({
  // 提供 Next.js 應用的路徑以在測試環境中載入 next.config.js 和 .env 檔案
  dir: './',
})

// 新增任何要傳遞給 Jest 的自定義配置
const config: Config = {
  coverageProvider: 'v8',
  testEnvironment: 'jsdom',
  // 在每個測試執行前新增更多設定選項
  // setupFilesAfterEnv: ['<rootDir>/jest.setup.ts'],
}

// 以這種方式匯出 createJestConfig 以確保 next/jest 可以載入非同步的 Next.js 配置
export default createJestConfig(config)

在底層，next/jest 會自動為您配置 Jest，包括：

使用 Next.js 編譯器 (Next.js Compiler) 設定 transform
自動模擬樣式表 (.css, .module.css 及其 scss 變體)、圖片匯入和 next/font
將 .env (及其所有變體) 載入到 process.env
忽略 node_modules 不進行測試解析和轉換
忽略 .next 不進行測試解析
載入 next.config.js 以啟用 SWC 轉換的標誌

須知事項：要直接測試環境變數，請在單獨的設定腳本或 jest.config.ts 檔案中手動載入它們。更多資訊請參閱測試環境變數 (Test Environment Variables)。

可選：處理絕對匯入和模組路徑別名

如果您的專案使用模組路徑別名 (Module Path Aliases)，您需要配置 Jest 以解析這些匯入，方法是將 jsconfig.json 檔案中的 paths 選項與 jest.config.js 檔案中的 moduleNameMapper 選項匹配。例如：

tsconfig.json 或 jsconfig.json

{
  "compilerOptions": {
    "module": "esnext",
    "moduleResolution": "bundler",
    "baseUrl": "./",
    "paths": {
      "@/components/*": ["components/*"]
    }
  }
}

jest.config.js

moduleNameMapper: {
  // ...
  '^@/components/(.*)$': '<rootDir>/components/$1',
}

可選：使用自定義匹配器擴展 Jest

@testing-library/jest-dom 包含一組方便的自定義匹配器 (custom matchers)，例如 .toBeInTheDocument()，使撰寫測試更容易。您可以透過在 Jest 配置檔中新增以下選項來為每個測試匯入這些自定義匹配器：

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

然後，在 jest.setup 中新增以下匯入：

import '@testing-library/jest-dom'

須知事項： extend-expect 在 v6.0 中被移除，因此如果您使用的是 @testing-library/jest-dom 6.0 之前的版本，您需要改為匯入 @testing-library/jest-dom/extend-expect。

如果您需要在每個測試之前新增更多設定選項，可以將它們新增到上述的 jest.setup 檔案中。

在 `package.json` 中新增測試腳本

最後，在您的 package.json 檔案中新增一個 Jest test 腳本：

package.json

{
  "scripts": {
    "dev": "next dev",
    "build": "next build",
    "start": "next start",
    "test": "jest",
    "test:watch": "jest --watch"
  }
}

jest --watch 會在檔案變更時重新執行測試。有關更多 Jest CLI 選項，請參閱 Jest 文件。

建立您的第一個測試

您的專案現在已準備好執行測試。在專案的根目錄中建立一個名為 __tests__ 的資料夾。

例如，我們可以新增一個測試來檢查 <Page /> 元件是否成功渲染了一個標題：

app/page.js

import Link from 'next/link'

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

__tests__/page.test.jsx

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()
  })
})

可選地，新增一個快照測試 (snapshot test) 來追蹤元件中的任何意外變更：

__tests__/snapshot.js

import { render } from '@testing-library/react'
import Page from '../app/page'

it('renders homepage unchanged', () => {
  const { container } = render(<Page />)
  expect(container).toMatchSnapshot()
})

執行您的測試

然後，執行以下命令來執行您的測試：

終端機

npm run test
# 或
yarn test
# 或
pnpm test

其他資源

如需進一步閱讀，您可能會發現這些資源有幫助：

Next.js with Jest 範例
Jest 文件
React Testing Library 文件
Testing Playground - 使用良好的測試實踐來匹配元素。

On this page