run-tests

.NET テストの実行

リポジトリのプロジェクトシステム、テストプラットフォーム、フレームワーク、SDK モードに合ったコマンドまたはコマンド列を返すか、実行します。

リポジトリオーバーレイ

読み取り専用のファイル調査が許可されているリポジトリ単位のタスクでは、ほかの調査を行う前に、リポジトリルートにある .agents/skill-overlays/dotnet-test/run-tests.md を確認してください。正確なコマンドを求められた場合も対象です。「実行しないで」という指示は、オーバーレイを読むことを禁じるものではありません。ファイルが存在する場合は、作業に取りかかる前に一度読み、リポジトリ固有のランナー、コマンド、フィルタリング、レポートの指定を適用してください。 適用する前に、そのフロントマターで core: dotnet-test/run-tests、binding-revision: "1"、mode: extend が宣言されていることを確認してください。いずれかの値が欠落または異なる場合は、不一致を報告してオーバーレイを無視し、このスキルの汎用的なガイダンスに従ってください。 ユーザーの明示的な指示と確認済みのプロジェクト制約はオーバーレイより優先されます。オーバーレイは、このスキルの汎用的な既定値や例より優先されます。ファイルが存在しても読み取れない場合、またはリポジトリと矛盾する場合は、問題を報告してオーバーレイを無視し、確認済みのプロジェクト制約に従いつつ、汎用的なガイダンスを使用してください。存在しない場合は、通常どおり続行してください。 リポジトリに関係しないタスク、またはユーザーがすべてのファイル／ツールへのアクセスを明示的に禁止した場合に限り、確認を省略してください。オーバーレイによってツールの使用許可やタスクの範囲を拡張することはできません。

範囲とツールのポリシー

依頼を満たす最小限の手順を選んでください。

依頼	対応
正確なコマンドまたは説明。ユーザーが実行しないよう指示している場合	構文を確定するのに必要なファイルだけを調査します。復元、ビルド、テストの実行は行いません。
テストの実行	リポジトリで使用するコマンドを特定し、依頼された最小限のテスト範囲を実行します。
ビルドせずに一度だけ SDK スタイルの dotnet test を実行する	run-tests の範囲で対応し、--no-build を追加します。
ビルドせずに一度だけ従来形式のテストを実行する	リポジトリのランナーを維持し、既存のビルド済みアセンブリを指定して実行します。dotnet test に置き換えないでください。
プラットフォーム／フレームワークの特定のみ	platform-detection を使用し、テスト実行には進みません。
明示的なホットリロード、または編集と再実行を続けるループ	mtp-hot-reload を使用します。
フィルターが必要で、フレームワーク固有の構文がまだ明らかでない	提供済み、または実行時に一覧表示された filter-syntax カタログファイルを読みます。この参照専用ヘルパーは呼び出さないでください。

プロンプトだけですでにコマンドが確定している場合、同じコマンドを繰り返すためにツールを呼び出さないでください。「念のため」ビルドを先に行わないでください。dotnet test は既定でビルドします。 ユーザーがプロジェクトの変更を求めていない限り、テストパッケージを追加またはアップグレードしないでください。 正確なコマンドを求められた場合は、最初に実行可能なコマンドを1つ返してください。プレースホルダーのパス、探索的な代替案、修正手順は出さないでください。プロンプトまたはリポジトリでプロジェクトパスが特定されている場合に限り、そのパスを使用してください。そうでなければ、現在のプロジェクトまたはソリューションを対象にできる構文であれば、そのまま使用してください。コマンドの説明には、必要な構文上の事実だけを続けてください。ユーザーが求めていない限り、プラットフォームやコマンドモードの分類を自発的に説明しないでください。特に、dotnet test が VSTest コマンドモードを使用するというだけで、SDK 8／9 のブリッジを「VSTest プラットフォーム」と呼ばないでください。実行されるプラットフォームは MTP です。コマンドのみを求められた場合は、通常、MTP のアプリケーション引数は -- の後に指定する、とだけ伝えるのが明確です。

検出する入力

• プロジェクト、ソリューション、モジュール、またはリポジトリのテストコマンド
• 要求された範囲：すべてのテスト、TFM、クラス、メソッド、カテゴリ、または特性
• 要求された出力：コンソール結果、TRX、診断情報、クラッシュダンプ、またはハングダンプ

プロンプトにこれらの情報が含まれている場合は、それを使用します。含まれていない場合は、関連するファイルのみを確認します。global.json、選択したプロジェクト、packages.config、Directory.Build.props、Directory.Packages.props、その後にリポジトリのスクリプト／CI ドキュメントを確認します。ファイルに基づくリクエストでは、これらの設定ファイル名を一度だけ列挙し、該当するファイルがあればすべてまとめて読み込みます。ランナーやブリッジのプロパティが.csprojにないことだけを根拠に、それらが存在しないと推測してはいけません。シグナルの優先順位分析が必要な場合に限り、platform-detectionを読み込みます。応答でその分析全体を重複して説明してはいけません。 実行が求められており、コマンドがアクティブな SDK に依存する一方、プロンプトにもglobal.jsonにも SDK が指定されていない場合は、dotnet --versionを一度実行します。実行を禁止するコマンドのみのリクエストでは、確認のためのコマンドを実行しません。構文をほかの方法で特定できない場合は、必要な SDK の前提を述べるか、SDK のバージョンを尋ねます。識別のみを求めるリクエストはplatform-detectionに振り分けます。

判定表

検出されたモード／プラットフォーム	コマンド形式	使用禁止
クラシックな非 SDK	リポジトリのスクリプト、または完全な MSBuild の後にvstest.console.exe／MSTest.exeを実行	dotnet testが互換性を持つと決めつけること、または暗黙に移行すること
VSTest モード／VSTest	dotnet test [<path>] [VSTEST_OPTIONS]	--report-trxや--treenode-filterなど、MTP 専用のフラグ
VSTest モード／実行可能な MTP ブリッジ	dotnet test [<path>] [DOTNET_OPTIONS] -- [MTP_OPTIONS]	SDK 10 でも--区切りを省略すること
ネイティブ MTP モード、SDK 10 以降	dotnet test --project <path> [DOTNET_OPTIONS] [MTP_OPTIONS]	位置指定のみのプロジェクトパス、またはブリッジ区切り

global.jsonは SDK 10 以降のdotnet testコマンドモードを制御しますが、テストを実行するプラットフォームを必ずしも制御するわけではありません。MTP ランナーを備え、TestingPlatformDotnetTestSupport=trueかつ最終的なOutputType=Exeである VSTest モードのプロジェクトでも、--を使うブリッジ構文が必要です。SDK 8／9 にあるのは VSTest コマンドモードのみです。

--projectが有効なのは SDK 10 以降のネイティブ MTP コマンドモード（global.jsonのtest.runnerで選択）に限られます。VSTest モードや SDK 8／9 のブリッジでは決して使用しないでください。これらの形式では、位置指定のプロジェクトパスを使います。反対に、ネイティブ MTP のオプションは直接渡す引数であり、ブリッジ区切りの後に置いてはいけません。

--framework、--configuration、--no-build、--verbosityなどのdotnet test／MSBuild オプションは、--より前に置きます。ブリッジモードでは、--の後には MTP アプリケーションの引数だけを置きます。

ワークフロー

1. リポジトリに適合するランナーを特定します。

クラシックなプロジェクトでは、ToolsVersion、明示的なCompileとReferenceの項目、レガシーなインポート、packages.configなどが手がかりになります。チェックイン済みのスクリプト、またはドキュメントに記載された CI コマンドを優先します。一般的な代替手段は次のとおりです。

nuget restore MySolution.sln
MSBuild.exe MySolution.sln /t:Build /p:Configuration=Debug
vstest.console.exe path\to\MyTests.dll /TestAdapterPath:path\to\adapter\build\<tfm>

packages.configを使用する場合、インポートされたパッケージファイルがすでに存在するのでなければ、ビルドの前に NuGet で復元します。アダプターの検出方法がリポジトリで設定されていない場合は、復元されたアダプターパッケージのパス、またはアダプターの.props／.targetsインポートから/TestAdapterPathを導き出します。パッケージのルートを推測してはいけません。

再ビルドなしでの実行が要求された場合は、ビルド手順を省略し、想定されるアセンブリがすでに存在するときに限り、リポジトリのテストランナーを実行します。存在しない場合は、暗黙に再ビルドしたりランナーを切り替えたりせず、ビルド出力が見つからないことを報告します。

一部のテストが要求された場合は、リポジトリのランナーを使い続け、そのフィルター構文を使用します。 vstest.console.exe path\to\MyTests.dll /TestCaseFilter:"TestCategory=Integration"。古いMSTest.exeを使うリポジトリでは、代わりに/test:<name>または/category:<category>を使う場合があります。クラシックなランナーに、後述のdotnet testのフィルター例を代用してはいけません。 インストール済みのアダプター互換 VSTest/MSTest ツールチェーンを使用します。利用できない場合は、不足している前提条件と文書化されたコマンドを明記し、テストを実行したと主張しないでください。 従来の packages.config 用のフォールバックコマンドは、Windows ツールチェーンのコマンドです。現在のホストで nuget、フル版 MSBuild、vstest.console.exe を利用できない場合は、Windows Developer Command Prompt（またはリポジトリで同等に構成された環境）が必要であることを明確に伝えてください。

SDK スタイルのプロジェクトでは、次のように区別します。

シグナル	意味
SDK 10 以降の global.json が Microsoft.Testing.Platform を選択	ネイティブ MTP コマンドモード
VSTest モード ＋ MTP ランナーが有効 ＋ 最終的な TestingPlatformDotnetTestSupport=true ＋ 最終的な OutputType=Exe	実行可能な VSTest から MTP へのブリッジ
完全なランナーとブリッジの組み合わせを備えていない VSTest モード	VSTest
より強い MTP シグナルを伴わない Microsoft.NET.Test.Sdk とアダプター	VSTest
TUnit	MTP のみ。構成済みのブリッジ／ネイティブモード、またはテスト実行可能ファイルを使用

プロジェクトとインポートされた Directory.Build.props／Directory.Packages.props からプロパティを評価します。プロジェクトレベルのオーバーライドと、ターゲットフレームワークごとの条件を尊重してください。実行可能な最終出力を伴わないランナーとブリッジは、不完全な MTP 構成であり、使用可能なブリッジではありません。

2. コマンドと要求された範囲を選択します。

# VSTest mode
dotnet test path/to/Tests.csproj

# VSTest mode that bridges to MTP
dotnet test path/to/Tests.csproj -- <MTP_OPTIONS>

# Native MTP mode on SDK 10+
dotnet test --project path/to/Tests.csproj <MTP_OPTIONS>

# One target framework; this stays before the bridge separator
dotnet test path/to/Tests.csproj --framework net9.0 -- <MTP_OPTIONS>

ネイティブ MTP では --project、--solution、または --test-modules を使用します。位置引数のパスは VSTest モード用です。

ユーザーが対象の一部を指定した場合、テストスイート全体を実行しないでください。「integration」や「smoke」などの人間向けのラベルをフレームワークの実際のカテゴリ／トレイト名に変換する必要がある場合に限り、テスト属性を調べてください。

VSTest のクラスフィルターで似た名前のクラスを区別する必要がある場合は、偶然の部分文字列の違いに頼らず、肯定セレクターと明示的な否定セレクターを組み合わせてください。

3. プラットフォームとフレームワークに適したフィルターを適用します。

要求にフィルターが指定されており、フレームワーク固有の構文が不明な場合に限り、提供された、または実行時に一覧表示された filter-syntax ファイルを読みます。これは参照専用であり、実行可能なスキルではありません。それ以外の場合は、以下の共通ルールを使用します。

ファイルを対象とするフィルター付きの要求では、構文を選ぶ前にプロジェクト、global.json、インポートされた props からフレームワークと SDK のコマンドモードを特定します。Microsoft.NET.Test.Sdk があることやフレームワーク名だけから、VSTest の構文だと推測しないでください。

プラットフォーム／フレームワーク	フィルター
MSTest、xUnit v2、または NUnit を使用する VSTest	--filter "<property expression>"
MSTest または NUnit を使用する MTP	同じ式。ブリッジモードでは -- の後、ネイティブモードでは直接指定
xUnit v3 を使用する MTP	--filter-class、--filter-method、--filter-trait、または複合式用の --filter-query 1 つ
TUnit を使用する MTP	--treenode-filter のパス式

例：

# VSTest MSTest/NUnit
dotnet test --filter "FullyQualifiedName~OrderServiceTests&TestCategory=Unit"

# SDK 8/9 or SDK 10 VSTest-mode MTP bridge, xUnit v3
dotnet test -- --filter-trait "Category=Integration"

# Native MTP, xUnit v3
dotnet test --project Tests.csproj --filter-class "*ShoppingCartTests*"

# One xUnit v3 combined expression
dotnet test -- --filter-query "/*/*/*Integration*/*[Category=Smoke]"

# TUnit on SDK 8/9 with a configured VSTest-to-MTP bridge
dotnet test -- --treenode-filter "/*/*/SmsNotificationTests/*"

# TUnit executable fallback when no bridge is configured
dotnet run --project Tests.csproj -- --treenode-filter "/*/*/SmsNotificationTests/*"

MTP 上の xUnit v3 で、VSTest の --filter "ClassName=..." を使用しないでください。TUnit で汎用的な VSTest 式を使用しないでください。 ユーザーが xUnit の複合クエリ式を 1 つ要求した場合は、--filter-query コマンドを 1 つだけ返してください。これを個別のフィルターフラグに置き換えたり、推測に基づく別の構文を提示したりしないでください。

4. レポートまたは診断を追加します。

結果	VSTest	MTP
TRX	SDK スタイル：正確な出力ファイルが指定されている場合は --logger "trx;LogFileName=<name>.trx"、それ以外は --logger trx。スタンドアロンの vstest.console.exe：/Logger:trx。MSTest.exe：リポジトリに記載された結果オプション	--report-trx
結果ディレクトリ	--results-directory <dir>	--results-directory <dir>
診断ログ	--diag <file>	--diagnostic --diagnostic-output-directory <dir>
クラッシュダンプ	--blame-crash	--crashdump
ハングタイムアウト	--blame-hang --blame-hang-timeout 5min	--hangdump --hangdump-timeout 5min
コードカバレッジ	--collect "Code Coverage"	--coverage
MTP のレポート、ダンプ、カバレッジのフラグには、対応する登録済みの拡張機能（TrxReport、CrashDump、HangDump、または CodeCoverage）が必要です。一部のフレームワーク SDK には一般的な拡張機能が同梱されています。フラグが認識されない場合は、パッケージの変更を提案する前にパッケージ参照を確認してください。

--verbosity diagnostic は dotnet/MSBuild の出力の詳細度を上げますが、VSTest の診断ログファイルは書き込みません。

例:

# VSTest TRX
dotnet test Tests.csproj --logger "trx;LogFileName=TestResults.trx"

# MTP bridge TRX
dotnet test Tests.csproj -- --report-trx

# Native MTP TRX and hang detection
dotnet test --project Tests.csproj --report-trx --hangdump --hangdump-timeout 5min

# Native MTP diagnostics
dotnet test --project Tests.csproj --diagnostic --diagnostic-output-directory artifacts/diagnostics

5. 要求された場合にのみ実行します。

要求に応える最小限のコマンドまたはコマンドシーケンスを実行します。各コマンド、終了コード、テスト概要を記録します。復元/ビルドの失敗はテストの失敗ではなく、テストの失敗はツールの失敗ではありません。どのフェーズが失敗したかを報告し、実行可能な診断情報を含めます。意図したテストが実行されてシーケンスが正常に完了しない限り、クリーンな実行だったと主張しないでください。 フィルタリングされた実行では、正常終了だけでは不十分です。報告されたテスト名または件数が要求された範囲と一致することを確認してください。フィルターが無視された場合は、プラットフォーム固有の構文を修正し、成功を報告する前に再実行してください。

出力契約

• コマンドのみの要求: 正確なコマンドまたはコマンドシーケンスを先頭に示し、その後に簡潔な構文の説明を 1 つ付けます。
• 実行の要求: 正確なコマンドまたはコマンドシーケンスと、完了した実行からの文字通りの Passed: N, Failed: N, Skipped: N の概要を報告し、最初の実行可能な失敗を含めます。
• 構文の選択のみを目的とした検出: 選択したモード/プラットフォームを簡潔に述べ、別途検出レポートを出さないでください。
• 前提条件の欠如または互換性のない構成: それを明示的に示し、成功のように見せかけたフォールバックを返すのではなく停止してください。

検証

• コマンドがクラシック、VSTest、ブリッジされた MTP、またはネイティブ MTP モードに一致している。
• フレームワーク固有のフィルターが要求されたサブセットを対象としている。
• --framework およびその他の dotnet test オプションが、ブリッジ区切り文字より前にある。
• SDK 8/9 のブリッジコマンドに -- が含まれており、--project は SDK 10+ のネイティブ MTP モードにのみ現れる。
• TRX、診断、ダンプ、カバレッジの各フラグがプラットフォームに一致している。
• 助言のみの要求に対して、復元、ビルド、テストが実行されていない。
• 報告された結果が実際のコマンドの結果と一致している。