qa-testing-nunit

QA テスト（NUnit）

クイックリファレンス

• まずテストの範囲を分類します：API、コンポーネント、統合テスト。
• 実行前にランタイムの制約を確認します：Docker が利用可能か、ターゲットフレームワーク、明示的に除外されているテストスイート。
• タスクに dotnet test、Microsoft.Testing.Platform、global.json、アダプター、またはカバレッジ／ログ出力のスイッチが含まれる場合は、まずリポジトリの現在のランナーモードを確認し、data/sources.json にある最新の一次情報を使用します。
• このスキルはテストスイートのアーキテクチャとフィクスチャの動作に使用し、一般的なサービス実装や CI グラフのリファクタリングには使用しません。
• セットアップが複雑な場合は、セットアップとテストメソッドを分けます。フィクスチャクラスには依存関係の配線と Given... ヘルパーを配置し、テストクラスには NUnit のライフサイクルとアサーションを配置します。
• エンドツーエンドの API テストは、コントローラーまたはエンドポイントのファミリーごとにグループ化します。グローバルに共有する単一のセットアップフィクスチャは避け、各ファミリーのフィクスチャがデータベースコンテナーとマイグレーション、HTTP スタブ、WebApplicationFactory、クライアントを所有するようにします。
• API フィクスチャで共有するランタイムは、並列実行に安全な状態を保ちます。フィクスチャレベルでの並列化は問題ありませんが、WireMock スタブ、クライアント、または変更可能なランタイム状態を共有している場合は、子テストの並列化を有効にしないでください。
• [FixtureLifeCycle(LifeCycle.InstancePerTestCase)] と [Parallelizable] を組み合わせる理由：NUnit の既定の SingleInstance ライフサイクルでは、すべてのテストメソッドで同じフィクスチャオブジェクトを共有するため、2 つのテストが同時に実行された時点でインスタンスフィールドが競合状態になります。InstancePerTestCase を使うと各テストに専用のインスタンスが割り当てられ、インスタンスフィールドの状態が分離されます。ただし、static フィールドや外部共有リソース（コンテナー、WireMock サーバー）は分離されません。そのため、このライフサイクルでは [OneTimeSetUp]／[OneTimeTearDown] を static のままにする必要があり、共有ランタイムにも [SetUp] で独自のリセット手順が必要です。
• 変更可能な状態は [SetUp] でリセットし、所有するインフラストラクチャはすべて [OneTimeTearDown] で破棄します。
• データベースのブートストラップでは、データベースコンテナーを起動し、各マイグレーションセットを終了コード 0 で終了する必要がある単発コンテナーとして実行した後、必要なテーブルを確認します（出発点として assets/nunit-database-launcher-template.cs を参照）。リポジトリにすでにランチャーまたはマイグレーションヘルパーがある場合は、分岐させずに再利用します。
• リポジトリのマイグレーションイメージにすでに記載されているコマンドでマイグレーションを実行します。テスト内のカスタム準備完了確認引数ではなく、コンテナーの待機戦略で準備完了を判定します。
• マイグレーターの順序を明示します（依存関係のマイグレーターを先に、ドメインマイグレーターを最後にします）。また、一部のスイートで全データベースが不要な場合に備え、フィクスチャレベルでマイグレーターを任意に切り替えられるようにします。
• ランチャーの起動、マイグレーターの完了と順序、必要なテーブルを検証する明示的なマイグレーター検証テストを追加します。
• ヘルスエンドポイントには、メソッドシグネチャを (string url, CancellationToken cancellationToken) とする [Test] + [TestCase] + [CancelAfter(...)] を使用します。NUnit アナライザーの問題を避けるため、[Test] と [TestCase] は併用します。
• アナライザーに適した NUnit の使い方と、詳細な診断を優先します。関連するアサーションには Assert.Multiple または Assert.EnterMultipleScope を使用し、失敗時に詳しい情報が必要な場合は TestContext.Progress またはフィクスチャの診断情報を使用します。
• ユーザーがインフラストラクチャに依存するスイート（たとえば Docker が必要なコンポーネントテスト）を除外した場合は、実行可能なカテゴリを先に実行し、未検証の内容を正確に報告します。
• タスクがサービス設計やバックエンドのリファクタリングに移った場合は、$software-csharp-backend に切り替えます。
• タスクが nuke/Build.cs、テストランナーの選択、カテゴリターゲットの配線、または CI 成果物の公開に移った場合は、$ops-nuke-cicd に切り替えます。

現在の事実に関するプロトコル

• runner モード、パッケージのバージョン、アナライザーの動作、アダプターの要件、CLI／カバレッジのスイッチは、変化しやすい現在の状態に関する事実として扱ってください。
• パッケージの変更やコマンドラインフラグを推奨する前に、バージョンに依存するガイダンスを data/sources.json で確認してください。
• リポジトリ全体に関わる dotnet test、MTP、カバレッジ、CI の配線は $ops-nuke-cicd に含め、このスキルではフィクスチャの設計とスイートの構成に集中してください。
• パッケージ、アダプター、runner モード、カバレッジに関する情報は references/test-platform-modes.md に、アサーションライブラリのライセンス情報は references/assertions-and-diagnostics.md にあります。バージョンを固定する前に、NuGet で現在のバージョンを調べてください。

ワークフロー

1. 境界、依存関係、想定するアサーションの深さ、環境の制約を定義します。 references/nunit-structure.md を読み込みます。依頼が dotnet test、runner モード、アダプター、CLI フラグに関係する場合は、references/test-platform-modes.md も読み込みます。
2. フィクスチャの構成とライフサイクルを選択します。 references/fixture-pattern.md と references/testing-templates.md を読み込みます。
3. 対象レイヤーのシナリオテストを実装します。 references/api-testing-nunit.md を読み込みます。コンポーネントテストでは、references/reliability-and-dependencies.md の境界に関するセクションも読み込みます。
4. 依存関係をダブルにするか実物にするかの方針と、コンテナーのトポロジーを選択します。 references/reliability-and-dependencies.md を読み込んでから、references/wiremock-setup.md または references/testcontainers-setup.md を読み込みます。
5. 堅牢な非同期アサーションと結果整合性アサーションを追加し、テストの不安定さを抑えます。 references/reliability-and-dependencies.md と references/assertions-and-diagnostics.md を読み込みます。
6. テンプレートの一貫性を保ちます。 API アセット一式をまとめてコピーします（references/testing-templates.md のテンプレートマップを参照してください）。
7. CI での実行を調整します。 references/ci-parallelism-sharding.md と references/infrastructure-troubleshooting.md を読み込みます。
8. ビルドとテストのフィードバック用ターゲットを通じて、変更したスイートを検証します。 SDK、runner モード、ターゲットフレームワーク、フィルター、検出／実行／スキップされた件数、結果のパス、コンテナーまたはスタブの診断情報を記録します。ビルドまたは --list-tests で確認できるのはテストの検出のみです。フィルターを指定した実行が成功しても、証明できるのはそのカテゴリとターゲットフレームワークに限られます。NUKE ベースのリポジトリでは、リポジトリのビルドターゲットと、変更を対象とするカテゴリのテストターゲットを実行します。パイプラインターゲットの変更には $ops-nuke-cicd を使用します。

Testcontainers または WireMock をテスト結果の判定に使用する場合は、対象の依存関係が起動して準備完了になり、想定したやり取りを受け取り、クリーンアップされたことを示す証拠を必須とします。NUnit の実行が完了したと述べるのではなく、除外したスイートを明示してください。

リソース

• NUnit の構成：プロジェクト構成、命名、カテゴリ、ライフサイクルの規約です。
• フィクスチャパターン：フィクスチャの境界、共有セットアップ、ティアダウン、合成について説明します。
• テストテンプレート：テンプレートの一覧、並列実行の規約、ヘルスチェックテンプレートについて説明します。
• NUnit による API テスト：HTTP アサーションとコントラクトチェックを使用した、エンドポイントレベルのテストです。
• テストプラットフォームのモード：dotnet test、MTP、アダプター、リポジトリレベルの CLI の差異に関するランナーモードのチェックです。
• 信頼性と依存関係：WireMock と Testcontainers の比較、コンテナーのトポロジー、コンポーネントの境界、最終的な状態のアサーション、決定性、不安定なテストのルールについて説明します。
• WireMock のセットアップ：決定論的なスタブ、リクエストの検証、障害のシミュレーションについて説明します。
• Testcontainers のセットアップ：コンテナーのライフサイクル、準備完了の確認、テストの分離について説明します。
• アサーションと診断：グループ化されたアサーション、アナライザーに安全なパターン、詳細な失敗出力について説明します。
• CI の並列実行とシャーディング：テスト実行を安全かつ効率的に分割する方法です。
• インフラストラクチャのトラブルシューティング：起動時の失敗、ポートの競合、準備完了に関する問題の診断について説明します。
• スキルのソース：最新状態の確認に使用する、NUnit、.NET ランナー、Testcontainers、WireMock.Net、パッケージの厳選された参照資料です。

テンプレート

• NUnit ハンドラーフィクスチャテンプレート：セットアップの構成と決定論的なシナリオ設定に使用する基本フィクスチャです。
• NUnit ハンドラーテストテンプレート：Arrange／Act／Assert の流れでフィクスチャを使用する基本テストクラスです。
• NUnit API フィクスチャテンプレート：コントローラーに焦点を当てた、API からデータベースまでの全サイクルテスト用 API フィクスチャです。
• NUnit API テストテンプレート：フィクスチャの分離と並列実行に安全なライフサイクルを備えた、基本 API テストクラスです。
• NUnit API リクエストビルダーテンプレート：シナリオ設定用の決定論的なリクエストビルダーです。
• NUnit API TestCaseSources テンプレート：再利用可能な TestCaseData ソースメソッドです。
• NUnit WireMock テンプレート：WireMockServerWrapper と依存関係ごとの *WiremockServer ヘルパーパターンです。
• NUnit データベースランチャーテンプレート：データベースコンテナー、順序指定された一度限りの移行コンテナー、任意の移行切り替え、テーブルチェックです。

ナビゲーション

• ## Workflow から始めてください。症状を起点としたデバッグには ## Failure Triage を、引き継ぎには ## Related Skills を使用してください。

このスキルを使用しないケース（判断が必要な場合）

• 問いが「そもそもこのテストは必要か」（リスクに基づくカバレッジの優先順位付け、何をテストするか）である場合は、まず $qa-testing-strategy を使用し、その後、テストの構築方法を確認するためにこちらに戻ってください。
• 問題がテストフィクスチャやテストコードではなく、dotnet test／MTP／VSTest のランナーモードの不一致、カバレッジコレクターの設定、または CI ターゲットグラフである場合は、$ops-nuke-cicd を使用してください。テストファイルを編集してランナーモードの不整合を解消しようとしないでください。
• 失敗したテストで明らかになった本番コード／サービスコードの実装や修正がタスクである場合は、$software-csharp-backend に切り替えてください。不具合を囲むテストを書くのはこのスキルの役割ですが、不具合の修正は対象外です。
• 対象のテストスイートが、インプロセスの API／コンポーネント／統合テストや Testcontainers を利用したテストではなく、ブラウザー／E2E（Playwright、Selenium）である場合は、$qa-testing-playwright または該当するモバイル／UI スキルを使用してください。
• references/reliability-and-dependencies.md を一度確認しても不安定なテストの根本原因が不明な場合は、修正を推測し続けないでください。まず診断情報（相関 ID、コンテナー／WireMock のログ、タイミング）を追加し、再現性のある方法で再現してから修正してください。原因不明の不安定さを隠すために [Retry] を黙って追加するのは、修正ではなく後退です。

失敗のトリアージ（症状 → 考えられる原因 → 最初に行うこと）

症状	考えられる原因の分類	最初に行うこと
テスト単体では成功するが、全体実行では失敗する	共有された可変状態、またはフィクスチャのライフサイクルの不一致	[FixtureLifeCycle]／[Parallelizable] の組み合わせを確認します。失敗するテストが読み取るすべての状態を [SetUp] で実際にリセットしていることを確認します
ローカルでは成功するが、CI でのみ失敗する	ポートの競合、Docker ホストの想定（localhost とリモート Docker ホストの違い）、または CI の並列実行時のリソース競合	ハードコードされたポート／ホストを確認します（references/reliability-and-dependencies.md、references/testcontainers-setup.md）。診断のために失敗するカテゴリの並列度を下げます。恒久的な修正にはしないでください
最終的整合性のアサーションで断続的にタイムアウトする	ポーリングではなく固定時間のスリープを使用している、または CI 負荷時にはタイムアウトが短すぎる	references/reliability-and-dependencies.md の Eventually ヘルパーに置き換えます。タイムアウトを延長するのは、条件が正しいと確認してからにしてください。競合状態をごまかすために延長してはいけません
アップグレード後、dotnet test でテストが検出されず、何も表示されない	アダプターのメジャーバージョンが MTP の世代と一致していない、または 1 つのソリューション内で VSTest と MTP が混在している	テストコードを変更する前に、references/test-platform-modes.md のアダプター ↔ MTP ↔ TFM の対応表を確認します。MTP では --minimum-expected-tests を追加し、成功扱いではなく実行を失敗させるようにします
MTP の有効化後、カバレッジレポートが空、または見つからない	VSTest 専用のカバレッジコレクターが残っており、MTP では何もせずに処理を終了している	MTP ネイティブのカバレッジ拡張機能に切り替えます。references/test-platform-modes.md で現在のパッケージの組み合わせを確認し、パッケージ独自のドキュメントでも確認します
マイグレーターに依存するテストが、テーブルが見つからないというエラーで失敗する	テストの不具合ではなく、マイグレーターの順序の問題	リトライやタイムアウトの延長を追加する前に、references/infrastructure-troubleshooting.md のマイグレーター順序に関するセクションを確認します

関連スキル

スキル	目的
software-csharp-backend	バックエンドサービスの実装
ops-nuke-cicd	NUKE パイプラインのターゲットと CI の設定
dev-structured-logs	構造化ログへの移行
qa-testing-strategy	リスクに基づくテスト戦略
qa-testing-playwright	ブラウザー／E2E スイート（ここでは対象外）

学びのループ

過去の判断や落とし穴が関係する場合は、learnings.consolidated.md があれば参照してください。必要な履歴を確認する場合、または他に利用できるものがない場合に限り、learnings.md を使用してください。それ以外の場合は、どちらも参照しないでください。

適用後、覚えておく価値のあるパターン、防止すべきミス、または意外だった分野の事実に気づいた場合は、agents-skills-feedback-loop/scripts/append_learning.py を使って、日付付きの箇条書きを learnings.md に1つ追記してください。SKILL.md 自体は変更しないでください。