Coverage Guard
JavaScript/TypeScriptプロジェクトで100%テストカバレッジを確保します。テストランナーを自動検出し、不足しているテスト基盤をセットアップし、カバレッジのないコンポーネントのテストを作成し、すべてのファイルが100%カバレッジに達するまでループします。
概要
このスキルは完全なパイプラインに従います:
- 検出 ランナーと基盤 → 2. スキャン ソースファイルとテスト → 3. セットアップ 不足時 → 4. 生成 新しいテスト → 5. 実行 カバレッジ → 6. 補填 ギャップ → 7. 検証 → 100%になるまで繰り返し
ステップバイステップのワークフロー
フェーズ1: 環境の検出
プロジェクトルートの package.json を確認して判別します:
cat package.json
テストランナーとカバレッジツールを特定:
| 指標 | ランナー | カバレッジコマンド |
|---|---|---|
"vitest" が devDependencies に存在 | Vitest | npx vitest --coverage |
"jest" が devDependencies に存在 | Jest | npx jest --coverage |
"react-scripts" が devDependencies に存在 | react-scripts (Jest) | npx react-scripts test --coverage |
"next" が devDependencies に存在 | Next.js (Jest) | npx next test --coverage または jest.config を確認 |
"@angular/core" が dependencies に存在 | Angular (Karma/Jasmine) | ng test --code-coverage |
"@playwright/test" が devDependencies に存在 | Playwright | npx playwright test (ビルトインカバレッジなし; @playwright/test を istanbul と併用) |
"mocha" が devDependencies に存在 | Mocha | npx mocha (c8/nyc でカバレッジ) |
"cypress" が devDependencies に存在 | Cypress | npx cypress run (@cypress/code-coverage でカバレッジ) |
"ava" が devDependencies に存在 | AVA | npx ava (c8 でカバレッジ) |
| 見つからない | なし → フェーズ2へ → フェーズ3でセットアップ |
フェーズ2: ソースファイルと既存テストのスキャン
テストが必要なすべてのソースファイル(コンポーネント、モジュール、ユーティリティ)を検索:
# 一般的なソースディレクトリ
find src -type f \( -name "*.ts" -o -name "*.tsx" -o -name "*.js" -o -name "*.jsx" \) ! -name "*.test.*" ! -name "*.spec.*" ! -name "*.d.ts" ! -path "*/node_modules/*" ! -path "*/dist/*" ! -path "*/build/*" ! -path "*/.next/*"
すべての既存テストファイルを検索:
find src -type f \( -name "*.test.*" -o -name "*.spec.*" \) ! -path "*/node_modules/*"
各ソースファイルをテストファイルにマッピング:
src/components/Button.tsx→src/components/Button.test.tsxまたはsrc/components/__tests__/Button.test.tsxsrc/utils/format.ts→src/utils/format.test.tsまたはsrc/utils/__tests__/format.test.ts- プロジェクトの既存のテストファイル配置規則に従う
各ソースファイルを分類:
- テストあり → カバレッジ分析リストに追加
- テストなし → テスト生成対象としてマーク
フェーズ3: テスト基盤のセットアップ(不足時)
フェーズ1でテストランナーが検出されなかった場合、ユーザーに対話的に確認:
? テストフレームワークが検出されませんでした。どれをセットアップしますか?
1) Vitest (推奨 — 高速、モダン、ネイティブESM)
2) Jest (最も広く使われている)
3) react-scripts (Create React App)
4) なし — スキップ、手動でセットアップします
ユーザーが選択したら、依存関係をインストールして設定を作成:
Vitest セットアップ:
npm install -D vitest @vitest/coverage-v8
vitest.config.ts を作成:
import { defineConfig } from 'vitest/config'
export default defineConfig({
test: {
coverage: {
provider: 'v8',
reporter: ['text', 'json', 'html'],
exclude: [
'**/node_modules/**',
'**/dist/**',
'**/*.config.*',
'**/*.d.ts',
],
},
},
})
package.json の scripts に追加:
{
"scripts": {
"test": "vitest",
"test:coverage": "vitest --coverage"
}
}
Jest セットアップ:
npm install -D jest @types/jest ts-jest
npx ts-jest config:init
npm install -D jest @testing-library/react @testing-library/jest-dom jest-environment-jsdom
jest.config.ts を作成:
export default {
testEnvironment: 'jsdom',
transform: {
'^.+\\.tsx?$': 'ts-jest',
},
coverageReporters: ['text', 'json', 'html'],
collectCoverageFrom: ['src/**/*.{ts,tsx}', '!src/**/*.d.ts'],
}
package.json の scripts に追加:
{
"scripts": {
"test": "jest",
"test:coverage": "jest --coverage"
}
}
react-scripts セットアップ:
npm install -D @testing-library/react @testing-library/jest-dom @testing-library/user-event
カバレッジはビルトイン:
{
"scripts": {
"test": "react-scripts test",
"test:coverage": "react-scripts test --coverage"
}
}
セットアップ後、テストを実行してすべてが正常に動作することを確認:
npm test
失敗した場合、設定の問題を修正してから次に進みます。
フェーズ4: テスト未作成のソースファイルにテストを作成
テストファイルがない各ソースファイルについて、ソースコードを分析:
- ソースファイルを読み取る
- 以下を特定:
- エクスポートされたすべての関数、クラス、コンポーネント
- 戻り値の型と可能な戻りパス
- パラメーターとその型(必須、オプション、デフォルト値)
- Props インターフェース(React コンポーネントの場合)
- 非同期動作(Promises、async/await)
- 副作用(API 呼び出し、localStorage など)
- エラー状態とエッジケース
- プロジェクトの規約に従ってテストファイルを生成:
- 検出されたテストランナーのAPIを使用(Jest/Vitest では
describe/it/expectなど) - React の場合:
@testing-library/reactを使用(render、screen、fireEvent) - 外部依存関係をモック
- すべての分岐、エッジケース、エラーパスをカバー
- 検出されたテストランナーのAPIを使用(Jest/Vitest では
React コンポーネントの例 (src/components/Button.tsx → src/components/Button.test.tsx):
import { render, screen, fireEvent } from '@testing-library/react'
import { Button } from './Button'
describe('Button', () => {
it('ラベル付きでレンダリングされる', () => {
render(<Button label="クリックして" />)
expect(screen.getByText('クリックして')).toBeInTheDocument()
})
it('クリック時に onClick が呼ばれる', () => {
const onClick = vi.fn() // Jest の場合は jest.fn()
render(<Button label="クリック" onClick={onClick} />)
fireEvent.click(screen.getByText('クリック'))
expect(onClick).toHaveBeenCalledTimes(1)
})
it('disabled プロップが true の場合、無効になる', () => {
render(<Button label="クリック" disabled />)
expect(screen.getByText('クリック')).toBeDisabled()
})
})
ユーティリティ関数の例 (src/utils/format.ts → src/utils/format.test.ts):
import { formatCurrency, truncate } from './format'
describe('formatCurrency', () => {
it('整数の金額をフォーマットする', () => {
expect(formatCurrency(1000)).toBe('$1,000.00')
})
it('小数の金額をフォーマットする', () => {
expect(formatCurrency(99.95)).toBe('$99.95')
})
it('ゼロを処理する', () => {
expect(formatCurrency(0)).toBe('$0.00')
})
it('負の値を処理する', () => {
expect(formatCurrency(-50)).toBe('-$50.00')
})
})
フェーズ5: カバレッジレポートの実行
検出されたランナーに基づいて適切なカバレッジコマンドを実行:
| ランナー | コマンド |
|---|---|
| Vitest | npx vitest --coverage --reporter=verbose |
| Jest | npx jest --coverage --verbose |
| react-scripts | npx react-scripts test --coverage --watchAll=false |
| その他 | プロジェクトで設定されたカバレッジコマンドを使用 |
出力を解析して以下を特定:
- 100%未満のファイル
- カバーされていない行、分岐、関数、ステートメント
- テストが必要な特定の行番号
- 0%カバレッジのファイル(テストが存在しない)
フェーズ6: カバレッジギャップの分析と補填
100%未満のファイルごと(フェーズ4でテストが作成されたが100%になっていないファイルを含む):
- ソースファイルとそのテストファイルを並べて読み取る
- カバーされていない行/関数/分岐が何を行うかを理解する
- テストで不足しているエッジケースを特定する
- ギャップをカバーするためのターゲットテストを作成:
- カバーされていない分岐:
ifとelseの両方のパス、三項演算子の条件をテスト - カバーされていない関数: すべての可能な戻りパスをテスト
- カバーされていない行: ロジックを追跡し、それらに到達するケースを作成
- カバーされていない非同期パス: 解決された Promise と拒否された Promise の両方の分岐をテスト
- カバーされていないエラー処理: エラーコールバック、catch ブロック、エラーバウンダリーをテスト
検出されたテストランナーのパターンを使用:
- Vitest:
vi.mock()、vi.spyOn()、vi.fn() - Jest:
jest.mock()、jest.spyOn()、jest.fn() - react-scripts: Jest と同じ
フェーズ7: 検証
テストの追加/更新後にカバレッジを再実行:
# 検出されたコマンドを使用
npx vitest --coverage # Vitest の場合
npx jest --coverage # Jest の場合
すべてのファイルでステートメント、分岐、関数、行が100%になっていることを確認。
フェーズ8: 繰り返し
カバレッジがまだ100%未満の場合、フェーズ6にループバック。
ランナー別設定
Vitest カバレッジ設定
vitest.config.ts を確認:
import { defineConfig } from 'vitest/config'
export default defineConfig({
test: {
coverage: {
provider: 'v8',
reporter: ['text', 'json', 'html'],
exclude: [
'**/node_modules/**',
'**/dist/**',
'**/*.config.*',
'**/*.d.ts',
],
},
},
})
Jest カバレッジ設定
jest.config.ts に以下が含まれていることを確認:
export default {
collectCoverage: true,
coverageReporters: ['text', 'json', 'html'],
collectCoverageFrom: [
'src/**/*.{ts,tsx,js,jsx}',
'!src/**/*.d.ts',
'!src/**/*.test.*',
'!src/**/*.spec.*',
],
}
ヒント
- 既存のテストがあってもカバレッジが低いファイルから始める — 最も早く改善される
- 次に、最も単純なロジックのテスト未作成ファイルに取り組む
- React コンポーネントの場合: レンダリング、ユーザー操作、条件付きレンダリング、エラー状態、空/ローディング状態をテスト
- ユーティリティ関数の場合: エッジケース(空文字列、null/undefined、境界値、特殊文字)をテスト
- API サービスの場合: 成功応答、エラー応答、ローディング状態、タイムアウト、ネットワーク障害をテスト
- デッドコードが見つかった場合(カバー不可能): 削除を提案するか、カバレッジ無視コメントを追加:
- Vitest/V8:
/* c8 ignore next */または/* c8 ignore next 3 */ - Jest/Istanbul:
/* istanbul ignore next */または/* istanbul ignore if */
- Vitest/V8:
- ソースコードのロジックは変更しない — テストのみを追加または更新する
- プロジェクトの既存のテストパターン(ファイル命名、フォルダ構造、モックスタイル)に従う
- テストが0のファイルの場合、最初に主要なパスすべてをカバーする包括的なテストファイルを作成し、その後反復する
検出優先順位
ソースファイルをスキャンする際、以下の一般的なディレクトリ構造の順序でチェック:
src/app/(Next.js app ディレクトリ)components/lib/utils/server/(Next.js/Node.js)pages/(Next.js pages ディレクトリ)- ルートレベルの
*.ts/*.tsxファイル
例
ユーザー: "カバレッジレポートで login.ts が72%と表示される、修正して"
エージェントのアクション:
npx vitest --coverage --reporter=verboseを実行し、login.ts の45-52行がカバーされていないことを確認(validateEmailのエラー分岐)- ソースを読み取り、
validateEmailが無効なメールアドレスで例外をスローすることを理解 login.test.tsに無効なメール入力のテストケースを追加- カバレッジを再実行 — login.ts が100%になる
ユーザー: "jest を使っている、カバレッジをチェックして"
npx jest --coverage --verboseを実行し、カバーされていないファイルを特定src/components/Header.tsxが0%であることを発見 — テストが存在しない- Header.tsx のソースを読み取り、
src/components/Header.test.tsxを作成 - カバレッジを再実行 — Header.tsx が100%になる
ユーザー: "このプロジェクトにはテスト設定がない、カバレッジを追加して"
- package.json にテストランナーが検出されないことを確認
- ユーザーに確認: "テストフレームワークが検出されませんでした。Vitest をインストールしますか?(推奨)"
- ユーザーが確認 → vitest + @vitest/coverage-v8 をインストール、vitest.config.ts を作成
- src/ をスキャンし、8個のソースファイル、0個のテストファイルを発見
- 8個すべてのファイルにテストを作成
- カバレッジを実行 — すべて100%