test-suite-ensure

テストスイートの整備

現在のプロジェクトにテストスイートが整備されていることを確認します。技術スタックとフレームワークを検出し、必要に応じてひな形を作成して、ユニットテスト（必須、ロジックコードのみ）を生成し、必要に応じて E2E テストを生成・実行します。

呼び出し規約

• 単独での起動：ユーザーがトリガーワードを指定した場合、現在のプロジェクトで一連のフローを実行します
• ワークフローからの呼び出し：テスト生成の対象を、ワークフローで変更されたロジックファイルに限定します
• 呼び出す前に SKILL.md を読む：ワークフローでは、呼び出しのたびにこのファイルを読む必要があります。記憶だけに頼って呼び出してはいけません

ワークフローのモード

ワークフローから呼び出す場合は、必ずいずれかのモードを宣言してください。

• mode=advisory：必須のテスト用ひな形がなく、ユーザーが作成を拒否した場合は、ロジックの変更に対するテストが生成されていない旨をリマインダーとしてレポートに記載して続行します。これは処理をブロックしません。
• mode=mandatory：必須のテスト用ひな形の作成を拒否された場合、またはユニットテストの実行に失敗した場合は、問題を解決するか、ユーザーの指示を待つまで実行ステージを終了できません。

単独で呼び出す場合は一連のフロー全体を実行します。フェーズ 5 におけるユニットテスト失敗時の処理は、どちらのモードでも適用されます。

test-first-discipline との境界

このスキルは事後対応です。既存のロジックを対象に、技術スタックを検出し、テストを整備して生成・実行し、助言または必須のゲートとして適用します。失敗するテストを先に作成する手順は担当しません。test-suite-ensure を完了しても、test-first-discipline を満たしたと説明してはいけません。両方が対象となる場合、ホストは動作の実装中にテストファーストを実施し、その後、テストスイートの整備によってカバレッジやひな形の不足に対応します。

---

フェーズ 1：技術スタックの検出

プロジェクトのルートをスキャンし、主要な言語とフレームワークを特定します。

ファイル	検出対象
package.json	JavaScript / TypeScript
go.mod	Go
requirements.txt / pyproject.toml / setup.py	Python
pom.xml / build.gradle	Java
Cargo.toml	Rust
*.csproj / *.sln	C# / .NET

package.json が検出された場合は、フロントエンドフレームワークをさらに特定します。

• "vite" を含む → Vitest を優先します
• "react" / "vue" / "angular" を含む → フロントエンドフレームワークです（ただし、テスト対象は引き続きロジック層のみです）
• "next" / "nuxt" を含む → サーバーサイドレンダリングフレームワークです
• "express" / "fastify" / "koa" などのみを含む → 純粋な Node.js バックエンドです

---

フェーズ 2：テストフレームワークの検出

技術スタックに基づいて、既存のテストフレームワークを検出します。

JavaScript / TypeScript：

• jest.config.js / jest.config.ts が存在する、または package.json の devDependencies に jest が含まれる → Jest ✅
• vitest.config.js / vitest.config.ts が存在する、または devDependencies に vitest が含まれる → Vitest ✅
• package.json の scripts.test が設定されている → 対応するフレームワーク ✅
• いずれも見つからない → ひな形の作成が必要です（フェーズ 3 を参照）

Python：

• pytest.ini / setup.cfg [tool:pytest] / pyproject.toml [tool.pytest.ini_options] が存在する → Pytest ✅
• devDependencies または requirements*.txt に pytest が含まれる → Pytest ✅
• いずれも見つからない → ひな形の作成が必要です（フェーズ 3 を参照）

Go：

• 組み込みの go test を使用します。go.mod の検出だけで十分です ✅。追加のフレームワークは不要です

Java：

• pom.xml に junit 依存関係が含まれる、または build.gradle に testImplementation 'junit' が含まれる → JUnit ✅

Rust：

• 組み込みの cargo test を使用します。追加の検出は不要です ✅

---

Phase 3：フレームワークのスキャフォールディング（Phase 2で「スキャフォールディングが必要」と判断された場合のみ）

技術スタックに基づいて選択し、インストールします。

技術スタック	推奨する選択肢	インストールコマンド
TypeScript + Vite プロジェクト	Vitest	npm install -D vitest @vitest/ui
TypeScript / JavaScript の一般的なプロジェクト	Jest + ts-jest	npm install -D jest ts-jest @types/jest
Python	Pytest	pip install pytest pytest-cov

スキャフォールディングの手順：

1. インストールコマンドを実行します
2. 最小限の設定ファイル（vitest.config.ts / jest.config.ts / pytest.ini）を作成します
3. package.json の scripts に "test" エントリーを追加します（ない場合）：
   • Vitest："test": "vitest run"
   • Jest："test": "jest"

ツールの制約：✅ インストールコマンドには Bash を使用できます。✅ 設定ファイルには Write を使用できます

---

Phase 4：ユニットテストの対象範囲の決定

対象範囲（ロジックコード）

次のディレクトリとファイル形式が対象範囲です。

• services/、utils/、helpers/、lib/、core/、models/、store/、api/
• 純粋なロジックを扱うフック（hooks/、composables/ 内で JSX／テンプレートのレンダリングを行わないもの）
• ユーティリティ関数のファイル（*.util.ts、*.helper.ts、*.service.ts）
• 状態管理ロジック（Vuex / Redux / Zustand / Pinia のストアロジック層）
• データ処理、フォーマット、検証、変換の各関数

対象外（UI 層 — ユニットテストなし）

次のディレクトリとファイル形式は対象外です。

• components/、views/、pages/、layouts/、screens/
• JSX／テンプレートをレンダリングするファイル：.tsx、.vue、.svelte、.jsx
• *.stories.tsx、*.stories.ts（Storybook）
• __mocks__/、fixtures/（テストヘルパーファイル）
• スタイルファイル（*.css、*.scss、*.less）

対象範囲の優先順位

1. ワークフローから呼び出された場合：ワークフローで変更されたファイルのうち、ロジックファイルのカバーを優先します。指定されていない場合は、全体をスキャンします
2. 単独で実行する場合：全体をスキャンし、対応するテストファイルがないロジックファイルを優先します

---

Phase 5：ユニットテストの生成と実行 【必須、ブロッキング】

生成の原則

• 各ロジックファイルにテストファイルを1つ対応させます。すでに存在する場合は、上書きせず、不足しているケースを追記します
• 各関数／メソッドについて、次の3種類以上のケースをカバーします：
  • 正常系（通常の入力）
  • 境界値（空、ゼロ、極端な入力）
  • エラー系（例外の発生、不正な入力）
• フレームワーク標準のアサーションを使用し、追加のアサーションライブラリは導入しません

テストファイルの命名規則

フレームワーク	命名規則	推奨される配置場所
Jest / Vitest	<name>.spec.ts または <name>.test.ts	ソースと同じディレクトリ、または __tests__/
Pytest	test_<name>.py または <name>_test.py	tests/ ディレクトリ、またはソースと同じディレクトリ
Go	<name>_test.go	ソースと同じディレクトリ（同じパッケージ）
JUnit	<Name>Test.java	パッケージパスに対応する src/test/java/

実行

Node / JavaScript / TypeScript プロジェクトでは、実行前に Node のバージョンをプロジェクトで宣言されているバージョンに合わせてください。そのために node-version-discipline スキルを呼び出してください（.nvmrc / .node-version / .tool-versions / volta / engines.node / CI 設定の全チェーンを調べ、宣言が見つからない場合はユーザーに確認します）。誤った Node バージョンでテストを実行すると、誤った成功判定／失敗判定につながります。その他のスタック（Python / Go / Rust / Java）には影響しません。

# JavaScript / TypeScript (Jest)
npm test -- --passWithNoTests

# JavaScript / TypeScript (Vitest)
npx vitest run

# Python
pytest --tb=short

# Go
go test ./...

# Rust
cargo test

# Java (Maven)
mvn test

# Java (Gradle)
./gradlew test

ブロッキング条件

ユニットテストが失敗した場合（終了コードが0以外）：

1. 失敗したテストの一覧（ファイル名 + テスト名 + エラーメッセージ）を出力します
2. 自動修正を試みます（最大2ラウンド：エラーを分析 → テストコードまたは実装を修正）
3. 2ラウンド後も失敗する場合：停止して、ユーザーの対応を待ちます。次の内容を出力します：
   • 失敗原因の分析
   • 修正方針の提案（実装を変更する／テストの期待値を調整する／手動でモックを追加する）

---

Phase 6：E2E テストの検出と実行 【任意】

E2E サポートの検出

設定ファイル	フレームワーク
playwright.config.ts / playwright.config.js	Playwright
cypress.config.ts / cypress.config.js	Cypress
nightwatch.conf.js / nightwatch.conf.ts	Nightwatch
wdio.conf.js / wdio.conf.ts	WebdriverIO

• 検出された場合 → E2E テストの生成と実行に進みます
• 検出されなかった場合 → 何もせずにスキップし、出力に「E2E フレームワークが検出されなかったため、スキップしました」と記載します

E2E テスト生成の原則（フレームワークが検出された場合のみ）

• 主要なユーザーフロー（ログイン／登録、主要な業務操作、重要なページ遷移）を優先します
• ワークフローから呼び出された場合は、この変更の影響を受けるページ／フローに重点を置きます
• E2E テストケースがすでに存在する場合は、上書きせずに追加します

実行

# Playwright
npx playwright test

# Cypress (headless mode)
npx cypress run

E2E の失敗時：失敗のスクリーンショットのパス（存在する場合）と失敗の理由を出力します。メインフローをブロックしないでください（E2E は任意です）。

---

出力形式

【test-suite-ensure Results】
- Tech Stack: ... (e.g. TypeScript + Vite)
- Test Framework: Existing <name> / Newly installed <name> (with config file path)
- Unit Tests:
  - In-scope logic files: X
  - New test files: X, Appended cases: X
  - Run result: ✅ X passed, 0 failed / ❌ X failed (list failed tests)
- E2E Tests:
  - Detection: Detected <framework name> / Not detected, skipped
  - Run result: ✅ X passed / ❌ X failed (with screenshot path) / Skipped

---

よくある間違い

間違い	結果	修正方法
ユニットテストの対象に UI コンポーネントファイルを含める	意味のないレンダリングテストが生成され、保守コストが高くなります	除外ルールに厳密に従い、ロジック層のみを対象にします
フレームワークがすでに存在するのに再インストールする	依存関係のバージョンが競合します	フェーズ 2 でフレームワークが検出された場合はフェーズ 3 をスキップします
既存のテストファイルを上書きする	既存のテストロジックが失われます	常に追加モードを使用し、上書きしないでください
ユニットテストが 2 回以上失敗した後も続行する	テストが失敗した状態で納品することになります	2 回失敗した時点で必ず停止し、ユーザーの介入を待ちます
E2E の失敗によってメインフローをブロックする	E2E は任意であり、必須のゲートにするべきではありません	E2E の失敗は警告を出力するだけで、処理をブロックしません
ワークフローから呼び出されたときに変更ファイルの一覧を無視する	テスト範囲が広すぎるか、重要な変更が漏れます	変更ファイルを優先的な対象とし、その後、対象を全体に広げます