Next.jsでJestをセットアップする
JestとReact Testing Libraryはユニットテストとスナップショットテストでよく一緒に使用されます。このガイドでは、Next.jsでJestを設定し、最初のテストを作成する方法を紹介します。
補足:
async
Server Componentsは React エコシステムにおいて新しいものであるため、現在Jestはそれらをサポートしていません。同期的なサーバーコンポーネントとクライアントコンポーネントに対してユニットテストを実行することは可能ですが、async
コンポーネントにはE2Eテストを使用することをお勧めします。
クイックスタート
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
# or
yarn add -D jest jest-environment-jsdom @testing-library/react @testing-library/dom @testing-library/jest-dom ts-node
# or
pnpm install -D jest jest-environment-jsdom @testing-library/react @testing-library/dom @testing-library/jest-dom ts-node
次のコマンドを実行して、基本的なJest設定ファイルを生成します:
npm init jest@latest
# or
yarn create jest@latest
# or
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.config.jsと.envファイルを読み込むためにNext.jsアプリのパスを提供します
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 Compilerを使用して
transform
を設定します。 - スタイルシート(
.css
、.module.css
およびそのscssバリアント)、画像インポート、next/font
を自動的にモック化します。 .env
(およびすべてのバリアント)をprocess.env
に読み込みます。- テストの解決とトランスフォームから
node_modules
を除外します。 - テストの解決から
.next
を除外します。 - SWCトランスフォームを有効にするフラグのために
next.config.js
を読み込みます。
補足: 環境変数を直接テストするには、別のセットアップスクリプトまたは
jest.config.ts
ファイルで手動で読み込む必要があります。詳細については、テスト環境変数を参照してください。
Jestの設定(Babelを使用)
Next.js CompilerをオプトアウトしてBabelを使用する場合は、Jestを手動で設定し、上記のパッケージに加えてbabel-jest
とidentity-obj-proxy
をインストールする必要があります。
Next.jsでJestを設定するための推奨オプションは以下の通りです:
module.exports = {
collectCoverage: true,
// Node 14.xではカバレッジプロバイダーv8が良好な速度と十分なレポートを提供します
coverageProvider: 'v8',
collectCoverageFrom: [
'**/*.{js,jsx,ts,tsx}',
'!**/*.d.ts',
'!**/node_modules/**',
'!<rootDir>/out/**',
'!<rootDir>/.next/**',
'!<rootDir>/*.config.js',
'!<rootDir>/coverage/**',
],
moduleNameMapper: {
// CSSインポートの処理(CSSモジュール使用時)
// https://jestjs.io/docs/webpack#mocking-css-modules
'^.+\\.module\\.(css|sass|scss)$': 'identity-obj-proxy',
// CSSインポートの処理(CSSモジュール未使用時)
'^.+\\.(css|sass|scss)$': '<rootDir>/__mocks__/styleMock.js',
// 画像インポートの処理
// https://jestjs.io/docs/webpack#handling-static-assets
'^.+\\.(png|jpg|jpeg|gif|webp|avif|ico|bmp|svg)$': `<rootDir>/__mocks__/fileMock.js`,
// モジュールエイリアスの処理
'^@/components/(.*)$': '<rootDir>/components/$1',
// @next/fontの処理
'@next/font/(.*)': `<rootDir>/__mocks__/nextFontMock.js`,
// next/fontの処理
'next/font/(.*)': `<rootDir>/__mocks__/nextFontMock.js`,
// server-onlyを無効化
'server-only': `<rootDir>/__mocks__/empty.js`,
},
// 各テスト実行前に追加のセットアップオプションを追加
// setupFilesAfterEnv: ['<rootDir>/jest.setup.js'],
testPathIgnorePatterns: ['<rootDir>/node_modules/', '<rootDir>/.next/'],
testEnvironment: 'jsdom',
transform: {
// babel-jestを使用してnext/babelプリセットでテストをトランスパイル
// https://jestjs.io/docs/configuration#transform-objectstring-pathtotransformer--pathtotransformer-object
'^.+\\.(js|jsx|ts|tsx)$': ['babel-jest', { presets: ['next/babel'] }],
},
transformIgnorePatterns: [
'/node_modules/',
'^.+\\.module\\.(css|sass|scss)$',
],
}
各設定オプションの詳細については、Jestのドキュメントで確認できます。また、Next.jsがJestをどのように設定しているかを確認するために、next/jest
の設定も参照することをお勧めします。
スタイルシートと画像インポートの処理
スタイルシートと画像はテストでは使用されませんが、インポートするとエラーが発生する可能性があるため、モック化する必要があります。
上記の設定で参照されているモックファイル(fileMock.js
とstyleMock.js
)を__mocks__
ディレクトリ内に作成します:
module.exports = 'test-file-stub'
module.exports = {}
静的アセットの処理の詳細については、Jestのドキュメントを参照してください。
フォントの処理
フォントを処理するには、__mocks__
ディレクトリ内にnextFontMock.js
ファイルを作成し、以下の設定を追加します:
module.exports = new Proxy(
{},
{
get: function getter() {
return () => ({
className: 'className',
variable: 'variable',
style: { fontFamily: 'fontFamily' },
})
},
}
)
オプション:絶対インポートとモジュールパスエイリアスの処理
プロジェクトがモジュールパスエイリアスを使用している場合は、jsconfig.json
ファイルのpaths
オプションとjest.config.js
ファイルのmoduleNameMapper
オプションを一致させて、Jestがインポートを解決できるように設定する必要があります。例:
{
"compilerOptions": {
"module": "esnext",
"moduleResolution": "bundler",
"baseUrl": "./",
"paths": {
"@/components/*": ["components/*"]
}
}
}
moduleNameMapper: {
// ...
'^@/components/(.*)$': '<rootDir>/components/$1',
}
オプション:カスタムマッチャーでJestを拡張する
@testing-library/jest-dom
には、.toBeInTheDocument()
のような便利なカスタムマッチャーのセットが含まれており、テストの記述が容易になります。Jest設定ファイルに以下のオプションを追加することで、すべてのテストでカスタムマッチャーをインポートできます:
setupFilesAfterEnv: ['<rootDir>/jest.setup.ts']
次に、jest.setup
内に以下のインポートを追加します:
import '@testing-library/jest-dom'
補足:
extend-expect
はv6.0
で削除されました。そのため、バージョン6以前の@testing-library/jest-dom
を使用している場合は、代わりに@testing-library/jest-dom/extend-expect
をインポートする必要があります。
各テスト前に他のセットアップオプションを追加する必要がある場合は、上記のjest.setup
ファイルに追加できます。
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__
というフォルダを作成します。
たとえば、<Home />
コンポーネントが見出しを正常にレンダリングするかどうかを確認するテストを追加できます:
export default function Home() {
return <h1>Home</h1>
}
import '@testing-library/jest-dom'
import { render, screen } from '@testing-library/react'
import Home from '../pages/index'
describe('Home', () => {
it('renders a heading', () => {
render(<Home />)
const heading = screen.getByRole('heading', { level: 1 })
expect(heading).toBeInTheDocument()
})
})
オプションで、コンポーネントの予期しない変更を追跡するためのスナップショットテストを追加できます:
import { render } from '@testing-library/react'
import Home from '../pages/index'
it('renders homepage unchanged', () => {
const { container } = render(<Home />)
expect(container).toMatchSnapshot()
})
補足: テストファイルはPages Router内に含めるべきではありません。Pages Router内のすべてのファイルはルートとして扱われるためです。
テストを実行する
次に、以下のコマンドを実行してテストを実行します:
npm run test
# or
yarn test
# or
pnpm test
追加リソース
さらに詳しく学ぶために、以下のリソースが役立つでしょう:
- Next.js with Jestの例
- Jestのドキュメント
- React Testing Libraryのドキュメント
- Testing Playground - 適切なテスト手法を使用して要素をマッチさせる