configure-integration-tests

/configure:integration-tests

サービス間の連携、データベース、外部依存関係をテストするための統合テスト基盤を確認し、設定します。

このスキルを使う場合

次の場合にこのスキルを使います...	次の場合は別の方法を使います...
Supertest、pytest、または Testcontainers を使って統合テスト基盤を設定する	特定のエンドポイントの個別の統合テストケースを書く（api-plugin:api-testing を使います）
ローカルテスト用サービスコンテナのために docker-compose.test.yml を作成する	既存の統合テストを実行する（bun test、pytest -m integration）
統合テストの設定が十分か監査する（フィクスチャ、ファクトリー、CI）	単体テストランナーを設定する（代わりに /configure:tests を使います）
サービスコンテナを使った GitHub Actions の統合テストジョブを追加する	特定の失敗した統合テストをデバッグする
プロジェクト構成で統合テストと単体テストを分離する	API コントラクトテストを設定する（代わりに /configure:api-tests を使います）

コンテキスト

• プロジェクトルート：!pwd
• パッケージファイル：!find . -maxdepth 1 \( -name 'package.json' -o -name 'pyproject.toml' -o -name 'Cargo.toml' -o -name 'go.mod' \)
• 統合テストディレクトリ：!find . -path '*/tests/*' -maxdepth 2 -type d -name 'integration'
• Docker Compose テスト：!find . -maxdepth 1 -name 'docker-compose.test.yml'
• Vitest 統合テスト設定：!find . -maxdepth 1 -name 'vitest.integration.config.*'
• Supertest 依存関係：!find . -maxdepth 1 -name 'package.json' -exec grep -l 'supertest' {} +
• Testcontainers 依存関係：!find . -maxdepth 1 \( -name package.json -o -name pyproject.toml \) -exec grep -l 'testcontainers' {} +
• プロジェクト標準：!find . -maxdepth 1 -name '.project-standards.yaml'

パラメーター

コマンド引数から解析します。

• --check-only：変更を加えずに準拠状況を報告します（CI/CD モード）
• --fix：確認を求めずに修正を自動適用します
• --framework <supertest|pytest|testcontainers>：フレームワークの検出結果を上書きします

統合テストスタック：

• JavaScript/TypeScript：Supertest + Testcontainers
• Python：pytest + testcontainers-python + httpx
• Rust：#[ignore] を使った cargo test + testcontainers-rs
• Go：testing + testcontainers-go

単体テストとの主な違い：

• 統合テストでは、実際のデータベース、API、サービスとやり取りします
• コンポーネントの境界とデータフローをテストします
• 通常、テストフィクスチャとクリーンアップが必要です

実行

次の統合テスト準拠チェックを実行します。

Step 1：既存の統合テスト基盤を検出する

次の指標を確認します。

指標	コンポーネント	状態
tests/integration/ ディレクトリ	統合テスト	存在
依存関係に testcontainers がある	コンテナテスト	設定済み
package.json に supertest がある	HTTP テスト	設定済み
docker-compose.test.yml	テストサービス	存在
integration マーカーを含む pytest.ini	pytest 統合テスト	設定済み

Step 2：現在の状態を分析する

統合テストの設定が完全か確認します。

テスト構成：

• tests/integration/ ディレクトリが存在する
• 統合テストが単体テストと分離されている
• テストフィクスチャとファクトリーがある
• データベースのシーディング／マイグレーションスクリプトがある

JavaScript/TypeScript（Supertest）：

• supertest がインストールされている
• @testcontainers/postgresql などがインストールされている
• テストデータベースが設定されている
• API エンドポイントのテストがある
• 認証テスト用ヘルパーがある

Python（pytest + testcontainers）：

• testcontainers がインストールされている
• HTTP テスト用の httpx または requests がある
• 非同期テスト用の pytest-asyncio がある
• integration マーカーが定義されている
• データベースフィクスチャが conftest.py にある

コンテナ基盤：

• docker-compose.test.yml が存在する
• テスト用データベースコンテナが定義されている
• Redis／キャッシュコンテナがある（必要な場合）
• ネットワーク分離が設定されている

ステップ 3：コンプライアンスレポートを生成する

書式付きのコンプライアンスレポートを出力します。

Integration Testing Compliance Report
======================================
Project: [name]
Language: [TypeScript | Python | Rust | Go]

Test Organization:
  Integration directory    tests/integration/         [EXISTS | MISSING]
  Separated from unit      not in src/                [CORRECT | MIXED]
  Test fixtures            tests/fixtures/            [EXISTS | MISSING]
  Database seeds           tests/seeds/               [EXISTS | N/A]

Framework Setup:
  HTTP testing             supertest/httpx            [INSTALLED | MISSING]
  Container testing        testcontainers             [INSTALLED | MISSING]
  Async support            pytest-asyncio             [INSTALLED | N/A]

Infrastructure:
  docker-compose.test.yml  test services              [EXISTS | MISSING]
  Test database            PostgreSQL/SQLite          [CONFIGURED | MISSING]
  Service isolation        network config             [CONFIGURED | MISSING]

CI/CD Integration:
  Integration test job     GitHub Actions             [CONFIGURED | MISSING]
  Service containers       workflow services          [CONFIGURED | MISSING]

Overall: [X issues found]

Recommendations:
  - Install testcontainers for database testing
  - Create docker-compose.test.yml for local testing
  - Add integration test job to CI workflow

--check-only が指定されている場合は、ここで終了します。

ステップ 4：統合テストを設定する（--fix が指定されている場合、またはユーザーが確認した場合）

検出したプロジェクトの種類に基づいて設定を適用します。REFERENCE.md のテンプレートを使用します。

1. 依存関係をインストールする（supertest、testcontainers など）
2. テストディレクトリ（tests/integration/）とセットアップファイルを作成する
3. API エンドポイントとデータベース操作のサンプルテストを作成する
4. Vitest 統合テスト用設定（JS/TS）または pytest マーカー（Python）を作成する
5. package.json にスクリプトを追加するか、実行コマンドを作成する

ステップ 5：コンテナインフラストラクチャを作成する

docker-compose.test.yml を作成し、以下を含めます。

• PostgreSQL テストデータベース（高速化のため tmpfs を使用）
• Redis テストインスタンス（必要な場合）
• ネットワーク分離

テストコンテナを管理するための対応する npm/bun スクリプトを追加します。REFERENCE.md のテンプレートを使用します。

ステップ 6：CI/CD 統合を設定する

.github/workflows/test.yml に統合テストのジョブを追加し、以下を含めます。

• サービスコンテナ（postgres、redis）
• データベースのマイグレーション手順
• 統合テストの実行
• テスト結果のアーティファクトのアップロード

REFERENCE.md の CI ワークフローテンプレートを使用します。

ステップ 7：テスト用フィクスチャとファクトリーを作成する

tests/fixtures/factories.ts（または Python の同等ファイル）を作成し、以下を含めます。

• faker を使用したデータファクトリー関数
• データベースのシード用ヘルパー
• クリーンアップ用ユーティリティ

ファクトリーテンプレートは REFERENCE.md を使用します。

ステップ 8：標準の追跡情報を更新する

.project-standards.yaml を更新します。

standards_version: "2025.1"
last_configured: "[timestamp]"
components:
  integration_tests: "2025.1"
  integration_tests_framework: "[supertest|pytest|testcontainers]"
  integration_tests_containers: true
  integration_tests_ci: true

ステップ 9：最終レポートを出力する

適用した変更、追加したスクリプト、統合テストの実行手順をまとめて出力します。

詳細なテンプレートとコード例については、REFERENCE.md を参照してください。

エージェント向けの最適化

コンテキスト	コマンド
コンプライアンスをすばやく確認	/configure:integration-tests --check-only
すべての問題を自動修正	/configure:integration-tests --fix
統合テストを実行（JS）	bun test tests/integration --dots --bail=1
統合テストを実行（Python）	pytest -m integration -x -q
テストコンテナを起動	docker compose -f docker-compose.test.yml up -d
コンテナのヘルス状態を確認	`docker compose -f docker-compose.test.yml ps --format json

フラグ

フラグ	説明
--check-only	修正を提示せずにステータスを報告します
--fix	確認を求めず、すべての修正を自動的に適用します
--framework <framework>	フレームワークの検出を上書きします（supertest、pytest、testcontainers）

例

# Check compliance and offer fixes
/configure:integration-tests

# Check only, no modifications
/configure:integration-tests --check-only

# Auto-fix all issues
/configure:integration-tests --fix

# Force specific framework
/configure:integration-tests --fix --framework pytest

エラー処理

• アプリのエントリーポイントが見つからない場合：アプリの場所をユーザーに確認します
• Docker が利用できない場合：testcontainers が必要であることを警告します
• データベースの種類が不明な場合：データベースの種類をユーザーに確認します
• ポートが競合している場合：docker-compose 内で代替ポートを提案します

関連項目

• /configure:tests - ユニットテストの設定
• api-plugin:api-testing - このスキルがインフラストラクチャを用意する Supertest / httpx+pytest テストの作成
• /configure:api-tests - API コントラクトテスト
• /configure:coverage - カバレッジの設定
• /configure:all - すべてのコンプライアンスチェックを実行
• Testcontainers のドキュメント：https://testcontainers.com
• Supertest のドキュメント：https://github.com/ladjs/supertest