Communityコーディング&開発github.com

テストガイドライン

テスト駆動開発(TDD)の原則に従い、新機能、バグ修正、リファクタリングにおいてテストファースト開発と80%以上のカバレッジ(単体テスト、結合テスト、E2Eテスト)を強制します。

テストガイドライン とは?

このスキルは、AIエージェント(Claude Code、Cursor、Codexなど)がTDDワークフローを厳格に実行するための包括的なガイドラインを提供します。主な目的は、コード開発において常にテストファーストのアプローチを適用し、新機能開発、バグ修正、リファクタリングのすべての段階で高いテスト品質を維持することです。スキルは、テストランナーの自動検出(npm、pnpm、yarn、Bun、pytest、go testなど)、テストケースの生成、コード実装、カバレッジ検証を含む7ステップのワークフローを定義しています。これにより、開発者は80%以上のコードカバレッジを達成し、単体テスト、結合テスト、E2Eテスト(Playwright)を適切に組み合わせることができます。スキルは、Jest/Vitest、Bunネイティブテスト、API統合テスト、Playwright E2Eテストの具体的なパターンを提供し、外部サービス(Supabase、Redis、OpenAI)のモック方法も示しています。また、テストのベストプラクティス(テスト分離、意味論的セレクタ、実装詳細ではなくユーザー可視動作のテスト)と、CI/CDパイプラインへの統合手順も含まれています。

対応✓Claude Code✓Codex CLI~Cursor
npx skills add https://github.com/orenatobr/tests-guidelines/tree/HEAD/skills/tests-guidelines

Installed? Explore more コーディング&開発 skills: steipete/bluebubbles, steipete/eightctl, steipete/blucli · View all 6 →

お気に入りのAIに質問する

このエージェントスキルを事前に読み込んだ状態で新しいチャットを開きます。

ドキュメント

テスト駆動開発ワークフロー

このスキルは、すべてのコード開発がTDDの原則に従い、包括的なテストカバレッジを確保することを保証します。

アクティブ化するタイミング

  • 新機能や機能の作成
  • バグや問題の修正
  • 既存コードのリファクタリング
  • APIエンドポイントの追加
  • 新しいコンポーネントの作成

基本原則

1. テストはコードより先に

常に最初にテストを書き、その後テストをパスするコードを実装します。

2. カバレッジ要件

  • 最低80%のカバレッジ(単体テスト + 結合テスト + E2E)
  • すべてのエッジケースをカバー
  • エラーシナリオのテスト
  • 境界条件の検証

3. テストタイプ

単体テスト

  • 個々の関数とユーティリティ
  • コンポーネントロジック
  • 純粋関数
  • ヘルパーとユーティリティ

結合テスト

  • APIエンドポイント
  • データベース操作
  • サービス間の相互作用
  • 外部API呼び出し

E2Eテスト(Playwright)

  • 重要なユーザーフロー
  • 完全なワークフロー
  • ブラウザ自動化
  • UI操作

TDDワークフローステップ

ステップ 0: テストランナーを検出する

npm testを前提としないでください。以下の手順と例のコマンドでは、プロジェクトの実際のランナーのプレースホルダーとして<test>、<test-watch>、<coverage>を使用しています。開始する前に一度解決してください。

  1. プロジェクトのランナーを見つける。 package.json(packageManager、scripts.test)、ロックファイル、pyproject.toml / pytest.ini、go.mod、Cargo.tomlを読み取ります。最初に一致したものが優先されます。npm testを前提としないでください。

  2. パッケージマネージャーとテストランナーを区別する。これらは同じではありません。 プロジェクトは依存関係のインストールにBunを使用しながらも、JestやVitestを実行することがあります。package.jsonのscripts.testとテストファイルを検査します。

    • scripts.testがjest / vitestを呼び出す場合 -> 検出されたPM(npm test、pnpm test、yarn test、またはbun run test)を介して実行します。
    • scripts.testがbun testである、またはテストファイルがimport { test, expect } from "bun:test"である、またはJest/vitest設定がないがBunが存在する場合 -> Bunのネイティブランナー(bun test)を使用します。下記のBunネイティブテストパターンを参照してください。
    • Python: <test> = pytest、<coverage> = pytest --cov --cov-fail-under=80。Go: go test ./... and go test -cover ./...。Rust: cargo test。

ランナーコマンド行列:

ランナー<test><test-watch><coverage><lint>
npmnpm testnpm test -- --watchnpm run test:coveragenpm run lint
pnpmpnpm testpnpm test --watchpnpm test:coveragepnpm lint
yarnyarn testyarn test --watchyarn test:coverageyarn lint
Bun(スクリプトがjest/vitestを実行)bun run testbun run test --watchbun run test:coveragebun run lint
Bun(ネイティブbun:test)bun testbun test --watchbun test --coveragebun run lint

bun test(Bunのビルドインランナー)はbun run test(package.jsonのtestスクリプトを実行)とは同じではありません。間違った方を選ぶことは一般的な失敗です。例えば、ESMのみのプロジェクトでnpx/bun runを介してJestを呼び出すと壊れる一方で、bun testはスイートをネイティブに実行します。プロジェクトがREDゲートの前にどちらを期待するかを確認し、以下のnpm testが現れる箇所すべてに<test> / <coverage>を代入してください。

ステップ 1: ユーザージャーニーを書く

[ロール]として、[アクション]を実行したい、理由は[利益]

例:
ユーザーとして、意味的にマーケットを検索したい、
正確なキーワードがなくても関連するマーケットを見つけられるように。

ステップ 2: テストケースを生成する

各ユーザージャーニーに対して、包括的なテストケースを作成します。

describe('セマンティック検索', () => {
  it('クエリに関連するマーケットを返す', async () => {
    // テスト実装
  })

  it('空のクエリを適切に処理する', async () => {
    // エッジケースのテスト
  })

  it('Redisが利用できない場合、部分文字列検索にフォールバックする', async () => {
    // フォールバック動作のテスト
  })

  it('類似度スコアで結果をソートする', async () => {
    // ソートロジックのテスト
  })
})

ステップ 3: テストを実行する(失敗するはず)

<test>
# まだ実装していないため、テストは失敗するはずです

ステップ 4: コードを実装する

テストをパスするための最小限のコードを書きます。

// テストに導かれた実装
export async function searchMarkets(query: string) {
  // ここに実装
}

ステップ 5: テストを再度実行する

<test>
# テストはパスするはずです

ステップ 6: リファクタリングする

テストがグリーンのままコード品質を向上させます。

  • 重複を除去
  • 命名を改善
  • パフォーマンスを最適化
  • 可読性を向上

ステップ 7: カバレッジを確認する

<coverage>
# 80%以上のカバレッジが達成されたことを確認

テストパターン

単体テストパターン(Jest/Vitest)

import { render, screen, fireEvent } from '@testing-library/react'
import { Button } from './Button'

describe('Buttonコンポーネント', () => {
  it('正しいテキストでレンダリングされる', () => {
    render(<Button>クリック</Button>)
    expect(screen.getByText('クリック')).toBeInTheDocument()
  })

  it('クリックされるとonClickが呼び出される', () => {
    const handleClick = jest.fn()
    render(<Button onClick={handleClick}>クリック</Button>)

    fireEvent.click(screen.getByRole('button'))

    expect(handleClick).toHaveBeenCalledTimes(1)
  })

  it('disabledプロップがtrueの場合、無効になる', () => {
    render(<Button disabled>クリック</Button>)
    expect(screen.getByRole('button')).toBeDisabled()
  })
})

Bunネイティブテストパターン(bun:test)

プロジェクトがBunのビルドインランナーを使用する場合(ステップ0を参照)、bun:testからインポートし、bun testで実行します。bun run testでは実行しません。APIはJestライクなので、describe / it / expect とほとんどのマッチャーはそのまま使用できます。

import { describe, it, expect, mock } from 'bun:test'
import { searchMarkets } from './search'

describe('searchMarkets', () => {
  it('空のクエリに対して空のリストを返す', async () => {
    expect(await searchMarkets('')).toEqual([])
  })

  it('類似度スコアで結果をソートする', async () => {
    const results = await searchMarkets('選挙')
    expect(results).toEqual([...results].sort((a, b) => b.score - a.score))
  })
})
bun test              # 一度実行(RED/GREENゲート)
bun test --watch      # 開発中のウォッチモード
bun test --coverage   # カバレッジレポート
  • モジュールをモックするには、jest.mock(...)の代わりにbun:testからmock.module(...) / mock(...)を使用します。
  • JestのcoverageThresholds設定ブロックではなく、bunfig.tomlの[test]セクションでカバレッジしきい値を設定します(例: coverageThreshold)。

API結合テストパターン

import { NextRequest } from 'next/server'
import { GET } from './route'

describe('GET /api/markets', () => {
  it('マーケットを正常に返す', async () => {
    const request = new NextRequest('http://localhost/api/markets')
    const response = await GET(request)
    const data = await response.json()

    expect(response.status).toBe(200)
    expect(data.success).toBe(true)
    expect(Array.isArray(data.data)).toBe(true)
  })

  it('クエリパラメータを検証する', async () => {
    const request = new NextRequest('http://localhost/api/markets?limit=invalid')
    const response = await GET(request)

    expect(response.status).toBe(400)
  })

  it('データベースエラーを適切に処理する', async () => {
    // データベースの障害をモック
    const request = new NextRequest('http://localhost/api/markets')
    // エラーハンドリングのテスト
  })
})

E2Eテストパターン(Playwright)

import { test, expect } from '@playwright/test'

test('ユーザーはマーケットを検索およびフィルタリングできる', async ({ page }) => {
  // マーケットページに移動
  await page.goto('/')
  await page.click('a[href="/markets"]')

  // ページが読み込まれたことを確認
  await expect(page.locator('h1')).toContainText('マーケット')

  // マーケットを検索
  await page.fill('input[placeholder="マーケットを検索"]', '選挙')

  // デバウンスと結果を待機
  await page.waitForTimeout(600)

  // 検索結果が表示されていることを確認
  const results = page.locator('[data-testid="market-card"]')
  await expect(results).toHaveCount(5, { timeout: 5000 })

  // 結果に検索語が含まれていることを確認
  const firstResult = results.first()
  await expect(firstResult).toContainText('選挙', { ignoreCase: true })

  // ステータスでフィルタリング
  await page.click('button:has-text("アクティブ")')

  // フィルタリング結果を確認
  await expect(results).toHaveCount(3)
})

test('ユーザーは新しいマーケットを作成できる', async ({ page }) => {
  // 最初にログイン
  await page.goto('/creator-dashboard')

  // マーケット作成フォームに入力
  await page.fill('input[name="name"]', 'テストマーケット')
  await page.fill('textarea[name="description"]', 'テスト説明')
  await page.fill('input[name="endDate"]', '2025-12-31')

  // フォームを送信
  await page.click('button[type="submit"]')

  // 成功メッセージを確認
  await expect(page.locator('text=マーケットが正常に作成されました')).toBeVisible()

  // マーケットページにリダイレクトされたことを確認
  await expect(page).toHaveURL(/\/markets\/test-market/)
})

テストファイルの構成

src/
├── components/
│   ├── Button/
│   │   ├── Button.tsx
│   │   ├── Button.test.tsx          # 単体テスト
│   │   └── Button.stories.tsx       # Storybook
│   └── MarketCard/
│       ├── MarketCard.tsx
│       └── MarketCard.test.tsx
├── app/
│   └── api/
│       └── markets/
│           ├── route.ts
│           └── route.test.ts         # 結合テスト
└── e2e/
    ├── markets.spec.ts               # E2Eテスト
    ├── trading.spec.ts
    └── auth.spec.ts

外部サービスのモック

Supabaseのモック

jest.mock('@/lib/supabase', () => ({
  supabase: {
    from: jest.fn(() => ({
      select: jest.fn(() => ({
        eq: jest.fn(() => Promise.resolve({
          data: [{ id: 1, name: 'テストマーケット' }],
          error: null
        }))
      }))
    }))
  }
}))

Redisのモック

jest.mock('@/lib/redis', () => ({
  searchMarketsByVector: jest.fn(() => Promise.resolve([
    { slug: 'test-market', similarity_score: 0.95 }
  ])),
  checkRedisHealth: jest.fn(() => Promise.resolve({ connected: true }))
}))

OpenAIのモック

jest.mock('@/lib/openai', () => ({
  generateEmbedding: jest.fn(() => Promise.resolve(
    new Array(1536).fill(0.1) // 1536次元の埋め込みをモック
  ))
}))

テストカバレッジの検証

カバレッジレポートの実行

<coverage>

カバレッジしきい値

{
  "jest": {
    "coverageThresholds": {
      "global": {
        "branches": 80,
        "functions": 80,
        "lines": 80,
        "statements": 80
      }
    }
  }
}

避けるべき一般的なテストの間違い

間違い:実装の詳細のテスト

// 内部状態をテストしないでください
expect(component.state.count).toBe(5)

正解:ユーザーが目に見える動作をテストする

// ユーザーが見るものをテストします
expect(screen.getByText('カウント: 5')).toBeInTheDocument()

間違い:脆いセレクタ

// 簡単に壊れる
await page.click('.css-class-xyz')

正解:意味論的なセレクタ

// 変更に強い
await page.click('button:has-text("送信")')
await page.click('[data-testid="submit-button"]')

間違い:テストの分離がない

// テストが互いに依存している
test('ユーザーを作成する', () => { /* ... */ })
test('同じユーザーを更新する', () => { /* 前のテストに依存 */ })

正解:独立したテスト

// 各テストが独自のデータをセットアップする
test('ユーザーを作成する', () => {
  const user = createTestUser()
  // テストロジック
})

test('ユーザーを更新する', () => {
  const user = createTestUser()
  // 更新ロジック
})

継続的テスト

開発中のウォッチモード

<test-watch>
# ファイル変更時にテストが自動実行されます

プレコミットフック

# すべてのコミットの前に実行
<test> && <lint>

CI/CD統合

# GitHub Actions
- name: テストの実行
  run: <coverage>
- name: カバレッジのアップロード
  uses: codecov/codecov-action@v3

ベストプラクティス

  1. テストを先に書く - 常にTDD
  2. テストごとに1つのアサーション - 単一の動作に焦点を当てる
  3. 説明的なテスト名 - 何をテストしているかを説明する
  4. Arrange-Act-Assert - 明確なテスト構造
  5. 外部依存関係をモックする - 単体テストを分離する
  6. エッジケースをテストする - null、undefined、空、大規模
  7. エラーパスをテストする - ハッピーパスだけではない
  8. テストを高速に保つ - 単体テストは各50ms未満
  9. テスト後にクリーンアップする - 副作用なし
  10. カバレッジレポートを確認する - ギャップを特定する

成功指標

  • 80%以上のコードカバレッジを達成
  • すべてのテストがパス(グリーン)
  • スキップされたり無効化されたテストがない
  • 高速なテスト実行(単体テストは30秒未満)
  • E2Eテストが重要なユーザーフローをカバー
  • テストが本番環境に移行する前にバグを発見

覚えておいてください:テストはオプションではありません。テストは、自信を持ってリファクタリングし、迅速な開発を可能にし、本番環境の信頼性を確保するためのセーフティネットです。

関連スキル