mcpField
N
ns-backend-tests

ns-backend-tests

github.com/nextstage-brasilテスト・品質0129 回インストール1 週間前に更新
リポジトリ

ns-backend-tests について

ns-backend-testsは、PHPプロジェクトのバックエンドでPHPUnitテストを実装・実行するスキルです。テストルートの検出や構築、プロジェクトに沿ったテスト設計、コンテナ内実行、結果報告を扱います。

主な機能

  1. 01PHPUnitテストルートの検出または構築
  2. 02実装コードと既存テストの確認
  3. 03ユニットテストと機能テストの作成
  4. 04ライブテストと標準スイートの分離
  5. 05Dockerテストコンテナでの実行
  6. 06テスト結果と阻害要因の報告

活用シーン

  1. 01既存プロジェクトへのバックエンドテスト追加
  2. 02バックエンドのテスト構成の初期化
  3. 03外部サービスに接続せずに行うテスト
  4. 04Dockerでの標準PHPUnitスイート実行

インストール

コマンドをコピーしてターミナルで実行します。

$npx skills add https://github.com/nextstage-brasil/skills --skill ns-backend-tests

インストール後、Claude Code で/ns-backend-testsを入力して読み込まれたか確認します。

同梱ファイルevals/evals.jsonreferences/backend-testing-architecture.md

詳細

バックエンドテストの作成

実行フェーズで PHPUnit を実装します。計画フェーズについては、ns-spec-driven/references/unit-test-task-generator.md を参照してください。

セッションの起動

.nextstage-harness/rules/backend-tests-rules.mdc と backend-rules.mdc がある場合は読み込みます。ディレクトリ構成、実行契約、ブートストラップの概要については、references/backend-testing-architecture.md を参照してください。

フェーズ 0 — バックエンドテストのルートを特定またはブートストラップする

テストクラスのコードを書く前に、PHPUnit プロジェクトを特定するか、最小限の構成を作成してください。

0.1 — 既存テストの検出（ブラウンフィールド）

次の順序でリポジトリを検索します。

  1. backend/phpunit.xml
  2. リポジトリルートの phpunit.xml
  3. PHPUnit を含む composer.json があるディレクトリ配下の tests/Unit/ または tests/Feature/

phpunit.xml を含むディレクトリを {backend_root} として記録します。以下のパスはすべて {backend_root} からの相対パスです。

0.2 — 何もない場合のブートストラップ（グリーンフィールド）

バックエンドのアプリケーションコード（app/、src/、または同等のもの）が存在するものの、phpunit.xml と tests/ がない場合：

ルール詳細
場所そのパッケージがある場合は backend/、それ以外はリポジトリルート
構成references/backend-testing-architecture.md に従います — phpunit.xml、tests/TestCase.php、tests/Unit/、tests/Feature/
依存関係既存の composer.json を使用した PHPUnit — フロントエンドや無関係なパッケージには追加しません

その後、そのディレクトリを {backend_root} に設定します。

グリーンフィールドで禁止されていること： テストが存在すると仮定すること、ホスト上で PHPUnit を実行すること、バックエンドパッケージの外にテストをスキャフォールドすること。

0.3 — ブートストラップ後のドキュメント更新

docs/context/stack-confirmed.md または architecture-rules.md がある場合は、バックエンドテストの行を追加または更新します。内容には {backend_root}、Docker のテストコンテナー、フェーズ 5 の PHPUnit 実行コマンドを記載します。

{backend_root} が確定し、phpunit.xml が読み取り可能になるまで、フェーズ 1 に進まないでください。

フェーズ 1 — 調査（機能コードの前）

  1. テスト対象のコード — 実装ファイル（Service、FormRequest、Controller など）を読みます
  2. 既存テスト — tests/Unit/ と tests/Feature/ 配下の該当ファイルを読みます。重複させず、既存のテストを拡張します
  3. プロジェクトのパターン — ハーネスルールに記載されたファクトリー、RefreshDatabase、レスポンスエンベロープ、マルチテナント用ヘルパーを確認します
  4. タスクの契約 — 単体テスト計画タスクを実装する場合は、そのシナリオチェックリストに従います

フェーズ 2 — テストの作成

  • 単体／機能テストのデフォルトティア： 実稼働のサードパーティへの HTTP／ネットワーク通信は行わず、フェイク／フィクスチャのみを使用します（../../ns-harness/references/docker-and-testing.md の「テストティア」を参照）
  • 単体テスト：依存関係をモックし、実際の DB／キュー／キャッシュの I/O は行いません
  • 機能テスト：認証、401／403、該当する場合は P0 のテナント間テストを含む HTTP テスト
  • 実際の外部サービスまたは実際の LLM が必要な場合 → PHPUnit の live グループ（例：#[Group('live')]）。デフォルト実行ではそのグループを phpunit.xml で除外し、マーカーと必要時の実行コマンドを architecture-rules.md に記録します
  • 命名：{Component}Test.php、説明的な snake_case のメソッド名
  • モジュールのパスに合わせます：tests/Unit/Modules/{Domain}/、tests/Feature/Modules/{Domain}/
  • 壊れた動作に合わせるためにアサーションを編集することは決してしません

フェーズ 3 — 実行（必須の契約）

../../ns-harness/references/docker-and-testing.md も参照してください。

  1. docker ps を実行し、ドキュメントに記載されたテストコンテナーを確認します（記載がない場合は一度だけ確認します）
  2. {backend_root} を作業ディレクトリとして、テストコンテナー内で実行します — デフォルトスイートのみ（live グループは除外）。この実行を人間から依頼されない限り、live グループを含めてはいけません：
timeout 120 docker exec -w {workdir} {test_container} \
  vendor/bin/phpunit --testdox --stop-on-failure --stop-on-error {optional_filter}
  1. タイムアウト： 120 秒でコマンドが強制終了された場合（例：終了コード 124）、実行は停止／ハングしたものとして扱います。中止してブロッカーを報告し、黙って再試行しないでください
  2. ホスト上で vendor/bin/phpunit または phpunit.sh を実行することは決してしません

フィルター付きの実行（単一クラスまたはメソッド）にも、同じフラグとタイムアウトを適用します。

フェーズ 4 — 報告

  • 成功：追加／変更したファイルを列挙します
  • 失敗：--testdox の出力から、最初に失敗したテスト名とアサーションを示します
  • ハング／タイムアウト：120 秒の制限を超えたことを記載します。根本原因が不明な場合は ns-investigator を呼び出します

参考資料

ファイル用途
references/backend-testing-architecture.mdレイアウト、ブートストラップ、実行契約
../ns-spec-driven/references/unit-test-task-generator.mdタスク契約の参照元

関連スキル

  • ns-spec-driven references/unit-test-task-generator.md — タスクの計画
  • ns-investigator — 失敗またはハングしたテストのデバッグ
  • ns-coder — 計画されたユニットテストタスク以外のアドホックな修正

コメント

Markdown 対応