testing-next-stack

Next Stack のテスト

最新のテストツールを使用して、Next.js アプリケーション向けの包括的なテスト環境を構築します。

概要

Next.js アプリケーション向けに包括的なテスト環境を作成するには、このスキルを使用して以下を生成します。

• 高速なユニットテスト用の Vitest 設定
• コンポーネントテスト用の React Testing Library セットアップ
• E2E テスト用の Playwright 設定
• axe-core によるアクセシビリティテスト
• テストユーティリティとヘルパー
• ベストプラクティスを示すテストファイルの例

使用するタイミング

以下の場合にこのスキルを使用します。

• テスト環境が必要な新しい Next.js プロジェクトを開始するとき
• Jest から Vitest に移行するとき
• Playwright による E2E テストを追加するとき
• アクセシビリティテストの要件を実装するとき
• ワールドビルディングアプリの機能（エンティティ、関係性、タイムライン）用のテストユーティリティを作成するとき
• プロジェクト間でテストパターンを標準化するとき

セットアップ手順

1. プロジェクト構成を分析する

プロジェクトの構成を把握するため、以下を確認します。

• 既存の依存関係を確認する Package.json
• Next.js のバージョンと設定
• TypeScript または JavaScript のセットアップ
• 既存のテスト環境
• コンポーネントのアーキテクチャ

2. 依存関係をインストールする

scripts/generate_test_deps.py を使用して、package.json に追加する内容を生成します。

python scripts/generate_test_deps.py --nextjs-version <version> --typescript

必要なパッケージをインストールします。

• vitest - 高速なユニットテストランナー
• @testing-library/react - コンポーネントテスト用ユーティリティ
• @testing-library/jest-dom - カスタムマッチャー
• @testing-library/user-event - ユーザー操作のシミュレーション
• @playwright/test - E2E テスト用フレームワーク
• @axe-core/playwright - アクセシビリティテスト
• @vitejs/plugin-react - Vite React プラグイン
• jsdom - Vitest 用の DOM 実装

3. 設定ファイルを生成する

assets/ のテンプレートを使用して設定ファイルを作成します。

Vitest の設定（vitest.config.ts）：

• assets/vitest.config.ts のテンプレートを使用する
• Next.js と一致するパスエイリアスを設定する
• テスト環境（jsdom）を設定する
• カバレッジレポートを設定する

Playwright の設定（playwright.config.ts）：

• assets/playwright.config.ts のテンプレートを使用する
• ブラウザー（chromium、firefox、webkit）を設定する
• 開発サーバーの baseURL を設定する
• スクリーンショットと動画の記録を設定する
• テスト成果物のディレクトリを設定する

テストのセットアップ（test/setup.ts）：

• assets/test-setup.ts のテンプレートを使用する
• @testing-library/jest-dom をインポートする
• グローバルのテストユーティリティを設定する
• モック実装を設定する

4. テストユーティリティを作成する

test/utils/ にユーティリティ関数を生成します。

レンダー用ユーティリティ（test/utils/render.tsx）：

• プロバイダーでラップするカスタムレンダー関数
• コンテキストプロバイダー（認証、テーマ、データ）
• Next.js 用のルーターのモック
• React Query 用のクエリークライアントのセットアップ

モックファクトリー（test/utils/factories.ts）：

• エンティティのモックデータジェネレーター
• 関係性のモックデータ
• ユーザーのモックデータ
• API レスポンスのモック

テストヘルパー（test/utils/helpers.ts）：

• 非同期テスト用ユーティリティ
• DOM クエリーのショートカット
• アクセシビリティテスト用ヘルパー
• カスタムマッチャー

5. テストの例を生成する

パターンを示すテストファイルの例を作成します。

ユニットテストの例（test/unit/example.test.ts）：

• assets/examples/unit-test.ts のテンプレートを使用する
• 純粋関数のテスト方法を示す
• 非同期関数のテスト方法を示す
• エッジケースのテストを含める

コンポーネントテストの例（test/component/example.test.tsx）：

• assets/examples/component-test.tsx のテンプレートを使用する
• レンダリングとアサーションの方法を示す
• ユーザー操作のテスト方法を示す
• axe によるアクセシビリティチェックを含める

E2E テストの例（test/e2e/example.spec.ts）：

• assets/examples/e2e-test.ts のテンプレートを使用する
• ユーザーフローのテスト方法を示す
• 認証フローを示す
• アクセシビリティスキャンを含める

6. package.json のスクリプトを更新する

package.json にテストスクリプトを追加します。

{
  "scripts": {
    "test": "vitest",
    "test:ui": "vitest --ui",
    "test:coverage": "vitest --coverage",
    "test:e2e": "playwright test",
    "test:e2e:ui": "playwright test --ui",
    "test:e2e:debug": "playwright test --debug"
  }
}

テストパターン

Vitest によるユニットテスト

ユーティリティ関数とビジネスロジックをテストするには、以下を使用します。

import { describe, it, expect } from 'vitest'
import { validateEntityRelationship } from '@/lib/validation'

describe('validateEntityRelationship', () => {
  it('validates valid relationship', () => {
    const result = validateEntityRelationship({
      sourceId: '1',
      targetId: '2',
      type: 'BELONGS_TO'
    })
    expect(result.isValid).toBe(true)
  })

  it('rejects self-referential relationship', () => {
    const result = validateEntityRelationship({
      sourceId: '1',
      targetId: '1',
      type: 'BELONGS_TO'
    })
    expect(result.isValid).toBe(false)
  })
})

RTL によるコンポーネントテスト

React コンポーネントをテストするには、以下を使用します。

import { render, screen } from '@/test/utils/render'
import { userEvent } from '@testing-library/user-event'
import { axe } from '@axe-core/playwright'
import EntityCard from '@/components/EntityCard'

describe('EntityCard', () => {
  it('renders entity information', () => {
    render(<EntityCard entity={mockEntity} />)
    expect(screen.getByText(mockEntity.name)).toBeInTheDocument()
  })

  it('handles edit action', async () => {
    const onEdit = vi.fn()
    render(<EntityCard entity={mockEntity} onEdit={onEdit} />)

    await userEvent.click(screen.getByRole('button', { name: /edit/i }))
    expect(onEdit).toHaveBeenCalledWith(mockEntity.id)
  })

  it('has no accessibility violations', async () => {
    const { container } = render(<EntityCard entity={mockEntity} />)
    const results = await axe(container)
    expect(results.violations).toHaveLength(0)
  })
})

Playwright による E2E テスト

ユーザーフロー全体をテストするには、以下を使用します。

import { test, expect } from '@playwright/test'
import { injectAxe, checkA11y } from '@axe-core/playwright'

test('user creates new entity', async ({ page }) => {
  await page.goto('/entities')

  // Inject axe for accessibility testing
  await injectAxe(page)

  // Navigate to create form
  await page.getByRole('button', { name: /create entity/i }).click()

  // Fill form
  await page.getByLabel(/name/i).fill('New Character')
  await page.getByLabel(/type/i).selectOption('character')
  await page.getByLabel(/description/i).fill('A mysterious traveler')

  // Submit
  await page.getByRole('button', { name: /save/i }).click()

  // Verify success
  await expect(page.getByText('New Character')).toBeVisible()

  // Check accessibility
  await checkA11y(page)
})

アクセシビリティテスト

コンポーネントレベルのアクセシビリティ

コンポーネントテストにアクセシビリティのアサーションを追加するには：

import { render } from '@/test/utils/render'
import { axe, toHaveNoViolations } from 'jest-axe'

expect.extend(toHaveNoViolations)

it('meets accessibility standards', async () => {
  const { container } = render(<MyComponent />)
  const results = await axe(container)
  expect(results).toHaveNoViolations()
})

E2E アクセシビリティスキャン

ページ全体のアクセシビリティの問題をスキャンするには：

import { test } from '@playwright/test'
import { injectAxe, checkA11y, getViolations } from '@axe-core/playwright'

test('homepage accessibility', async ({ page }) => {
  await page.goto('/')
  await injectAxe(page)

  // Check entire page
  await checkA11y(page)

  // Or check specific element
  await checkA11y(page, '#main-content')

  // Or get violations for custom reporting
  const violations = await getViolations(page)
  expect(violations).toHaveLength(0)
})

カバレッジの設定

コードカバレッジレポートを生成するには、vitest.config.ts で Vitest のカバレッジを設定します：

export default defineConfig({
  test: {
    coverage: {
      provider: 'v8',
      reporter: ['text', 'json', 'html'],
      exclude: [
        'node_modules/',
        'test/',
        '**/*.config.{ts,js}',
        '**/*.d.ts'
      ],
      thresholds: {
        lines: 80,
        functions: 80,
        branches: 80,
        statements: 80
      }
    }
  }
})

リソース

詳細については、以下のリソースを参照してください：

• references/vitest-setup.md - Vitest の設定に関する詳細
• references/rtl-patterns.md - React Testing Library のベストプラクティス
• references/playwright-setup.md - Playwright の設定ガイド
• references/a11y-testing.md - アクセシビリティテストのガイドライン
• assets/vitest.config.ts - Vitest 設定テンプレート
• assets/playwright.config.ts - Playwright 設定テンプレート
• assets/test-setup.ts - テストセットアップのテンプレート
• assets/examples/ - テストファイルの例

次のステップ

テストインフラストラクチャのスキャフォールディングが完了したら：

1. npm install を実行して依存関係をインストールします
2. npm test を実行して Vitest のセットアップを確認します
3. npm run test:e2e を実行して Playwright のセットアップを確認します
4. 設定ファイルを確認し、カスタマイズします
5. 既存のコンポーネントと機能にテストを追加します
6. テストを実行する CI/CD パイプラインを設定します
7. CI でカバレッジレポートを設定します
8. チーム向けのテストガイドラインを文書化します