Microsoft.Testing.Platform (MTP) CLIのオプション リファレンス

この記事では、MTP コマンド ライン オプションの中心的なエントリ ポイントについて説明します。

Important

プラットフォーム オプションは、MTP 自体から使用できます。 拡張機能オプションは、対象となる各テスト アプリケーションが、それらを提供する拡張機能パッケージを登録する場合にのみ使用できます。 パッケージを直接追加するか、それを含むテスト SDK 構成またはプロファイルを使用します。 テスト アプリケーションで拡張機能が登録されていない場合、オプションが認識されないため、終了コード 5 で実行が失敗します。

プラットフォームのオプション

  • @

    応答ファイルの名前を指定します。 応答ファイル名は、@文字と応答ファイル名の間に空白のない@文字の直後に続く必要があります。

    応答ファイル内のオプションは、コマンド ラインのその場所にあるかのように解釈されます。 円記号文字 \ を使用して行を連結することはできません。 応答ファイルを使用すると、ターミナルの制限を超える可能性がある非常に長いコマンドに役立ちます。 応答ファイルをインラインのコマンド ライン引数と組み合わせることができます。 例えば次が挙げられます。

    ./TestExecutable.exe @"filter.rsp" --timeout 10s

    filter.rsp は次の内容を含むことができます。

    --filter "A very long filter"

    または、1 つの rsp ファイルを使用して、タイムアウトとフィルターの両方を次のように指定できます。

    ./TestExecutable.exe @"arguments.rsp"

    --filter "A very long filter" --timeout 10s

    注

    dotnet testを使用する場合、SDK コマンド ライン パーサーは、応答ファイル内の各行が 1 つのトークンとして扱われる、1 行ごとのトークンアプローチを使用します。 その場合、各引数は別々の行に配置する必要があります。

    --filter
A very long filter
--timeout
10s

  • --config-file

    testconfig.json ファイルを指定します。

  • --debug

    デバッガーをテスト プロセスにアタッチできるように、起動時にテストの実行を一時停止します。 TESTINGPLATFORM_WAIT_ATTACH_DEBUGGER environment 変数を 1 に設定することと同じです。 ブラウザー プラットフォームではサポートされていません。

    注

    このオプションは、バージョン 1.9.0 以降の MTP で使用できます。 以前の --debug-wait-attach オプション (MTP 1.6.0 で導入) が置き換えられます。古い名前は削除されたため、使用しなくなりました。

  • --diagnostic

    診断ログを有効にします。 デフォルトのログ レベルは Trace です。 テスト ソースごとに、MTP は <asm>_<tfm>_<arch>_<timestamp>.diagを書き込みます。 タイムスタンプが競合する場合、MTP は既存のファイルを上書きするのではなく、プロセスとカウンター サフィックスを追加します。

  • --diagnostic-synchronous-write

    組み込みのファイル ロガーにログの同期的な書き込みを強制します。 (プロセスがクラッシュした場合に) ログ エントリを少しも失いたくないときのシナリオに役立ちます。 これにより、テストの実行が遅くなります。

    注

    バージョン 2.0.0 以降の MTP で使用できます。 MTP 2.0.0 で削除された以前の --diagnostic-filelogger-synchronouswrite オプションが置き換えられます。

  • --diagnostic-output-directory

    指定しない場合、診断ログの出力ディレクトリとして、ファイルはデフォルトの TestResults ディレクトリに生成されます。

  • --diagnostic-file-prefix

    ログ ファイル名のプレフィックス。 既定値は <asm>_<tfm>_<arch> です。

    注

    バージョン 2.0.0 以降の MTP で使用できます。 MTP 2.0.0 で削除された以前の --diagnostic-output-fileprefix オプションが置き換えられます。

  • --diagnostic-verbosity

    --diagnostic スイッチを使用するときの詳細レベルを定義します。 使用できる値は Trace、Debug、Information、Warning、Error、Critical です。

  • --enable-dynamic-extensions

    テスト アプリケーションの横 *.testingplatformextensions.json マニフェスト ファイルによって宣言された拡張機能の読み込みを有効にします。 動的拡張機能は既定で無効になっています。 セキュリティ要件とマニフェスト スキーマについては、「拡張機能を 動的に読み込む」を参照してください。

    注

    このオプションは、バージョン 2.4.0 以降の MTP で使用できます。

  • --exit-on-process-exit

    依存プロセスが終了した場合は、テスト プロセスを終了します。 PID を指定する必要があります。

  • --filter-uid

    テスト ノードの UID によって実行されるようにテストをフィルター処理します。 1 つ以上の UID を受け入れます。

    フレームワークの作成者は、検出と実行に関して TestNodeUidListFilter に従う必要があります。 実装に関するガイダンスについては、リクエスト フィルターを尊重するを参照してください。

    注

    このオプションは、バージョン 1.8.0 以降の MTP で使用できます。 MTP 2.3.0 以降では、 --filter-uid と --treenode-filterを組み合わせることはできません。両方を指定すると、コマンド ライン検証と InvalidCommandLine 終了コードの両方が失敗します。

  • --help

    コマンドの使用方法を示した説明を出力します。

  • --ignore-exit-code

    一部の 0 以外の終了コードを無視し、代わりに 0 として返すようにします。 詳細については、「特定の終了コードを無視する」を参照してください。

  • --info

    .NET テスト アプリケーションに関する次のような詳細情報を表示します。

    • プラットフォーム。
    • 環境。
    • 各登録済みコマンド ライン プロバイダー (name、version、description、optionsなど)。
    • 登録されている各ツール (command、name、version、description、すべてのコマンド ライン プロバイダーなど)。

    この機能は、同じコマンド ライン オプションを登録する拡張機能や、拡張機能 (またはプラットフォーム) の複数のバージョン間で使用可能なオプションの変更を理解するのに使用されます。

  • --list-tests

    使用可能なテストを実行せずに一覧表示します。 必要に応じて、出力形式を制御する引数 ( text (既定、人間が判読可能) または jsonを受け取ります。

    構造化メタデータと例については、「 テストを JSON として検出する」を参照してください。

    注

    json出力形式は、バージョン 2.3.0 以降の MTP で使用できます。

  • --maximum-failed-tests

    テストの失敗件数の最大値 (正の値) を指定します。 エラー数が最大値に達すると、MTP はグレースフルストップを要求し、終了コード 13を返します。 既に進行中のテストは完了できるため、最終的なエラー数が最大値を超える可能性があります。 詳細については、 MTP 終了コードを参照してください。

    フレームワークの作成者は、IGracefulStopTestExecutionCapability を実装して登録し、オプション プロバイダーを AddMaximumFailedTestsService に登録する必要があります。 機能ドキュメントには、実装と登録の例が含まれています。 フレームワークですでにその機能がサポートされている場合、テスト作成者はその機能を実装する必要はありません。

    注

    この機能は、バージョン 1.5 以降の MTP で使用できます。

  • --minimum-expected-tests

    実行する必要があるテストの正の最小数を指定します。 実行が実行されるテストが 0 個を含めて少なくなると、コード 9で終了します。 明示的な最小値が --zero-tests-policyよりも優先されます。

    dotnet testでは、このオプションは、--前に指定された場合は実行全体に適用され、--後に指定された場合は各テスト モジュールに適用されます。 詳細については、「 実行全体とモジュールごとの最小値」を参照してください。

    注

    --minimum-expected-tests 0 が無効です。 ゼロ テスト終了コードを抑制するには、 --ignore-exit-code 8を使用します。

  • --no-banner

    スタートアップ バナー、著作権メッセージ、テレメトリ バナーを無効にします。 同じ効果は、 TESTINGPLATFORM_NOBANNER 変数または DOTNET_NOLOGO環境変数を通じて達成できます。

  • --results-directory

    MTP がテスト結果を配置するディレクトリを指定します。 ディレクトリが存在しない場合は、作成されます。 既定では、MTP の作業ディレクトリ配下の TestResults です。 テスト アプリケーションを直接起動すると、作業ディレクトリは既定でテスト アプリケーションを含むディレクトリになります。

    dotnet testでは、既定値は SDK と MTP のバージョンによって異なります。 共有呼び出し相対ルート、バージョン要件、成果物レイアウトのオーバーライドについては、「 結果と成果物」を参照してください。

    複数のテスト アプリケーションを分離するには、--results-directory-layout per-module の前に SDK の -- オプションを渡します。 このオプションは MTP コアではなく SDK に属し、テスト アプリケーションを直接起動する場合は使用できません。

  • --server

    エディター、IDE、またはツール統合 JSON-RPC サーバー モードでテスト アプリケーションを起動します。 値を省略するか、 jsonrpcを使用します。 サポートされているソースのみのクライアントについては、 MTP サーバー モードを参照してください。

    Important

    dotnettestcli値とそのトランスポート引数は、.NET SDK 統合の内部にあります。 手動で渡さないでください。

  • --show-slowest-tests

    ターミナルの概要に、要求された最も遅いテストの数が表示されます。 実行に複数のテスト モジュールが含まれている場合、MTP は各モジュールの最も低速なテストを報告します。

    注

    このオプションは、バージョン 2.4.0 以降の MTP で使用できます。

  • --timeout

    グローバル テストの実行タイムアウト。 1 つの引数を、<value>[h|m|s] が float である <value> 形式で文字列として受け取ります。

  • --treenode-filter

    ツリー フィルター式を使用して、実行するテストをフィルター処理します。 ツリー フィルターは、高度なシナリオで --filter よりも豊富な一致を提供します。

    注

    MTP 2.3.0 以降では、 --treenode-filter と --filter-uidを組み合わせることはできません。両方を指定すると、コマンド ライン検証と InvalidCommandLine 終了コードの両方が失敗します。

  • --zero-tests-policy

    すべてのテストがスキップされたためにテストを実行しない実行を失敗として扱うかどうかを制御します。 有効な値は allow-skipped (既定値) と strictです。 allow-skippedでは、すべてがスキップされた実行は成功と見なされます。 strictでは、終了コード8で失敗します。 明示的な --minimum-expected-tests 値がこのポリシーよりも優先され、最小値が満たされていない場合は終了コード 9 が使用されます。

    注

    このオプションは、バージョン 2.3.0 以降の MTP で使用できます。 dotnet testでは、各テスト モジュールに転送する--の後にオプションを渡します。 グローバル最小値を設定しない場合、.NET 11 SDK によって、実行全体のゼロ テストの判定が個別に決定されます。 詳細については、「 実行全体とモジュールごとの最小値」を参照してください。

JSON形式でテストを検出

MTP 2.3.0 以降では、人間が判読できるリストを解析する代わりに、 --list-tests json を使用してマシンが読み取り可能な JSON ドキュメントとしてテストを検出します。

dotnet Contoso.MyTests.dll --list-tests json --no-banner

ビルド出力も書き込むコマンドではなく、ビルドされたテスト アプリケーションを実行 標準エラーとは別に標準出力をキャプチャし、ドキュメントを処理する前にプロセス終了コードを確認します。 機械可読モードでは、アプリケーションと拡張機能のスタートアップ メッセージを標準出力に出力しないようにします。

検出を、 --report-trxなどの実行専用オプションと組み合わせないでください。 testconfig.json がこれらのオプションを有効にする場合は、それらのオプションを省略した別の探索構成で --config-file を使用します。

ドキュメントには、 schemaVersion と tests 配列が含まれています。 各テストには、 uid と displayNameが含まれます。 テスト フレームワークが対応するメタデータを提供する場合、オプションのフィールドには、 type、 location、 traits、および propertiesが含まれます。 たとえば、Environment 特性を持つテストでは、次の結果を生成することがあります。

{
  "schemaVersion": 1,
  "tests": [
    {
      "uid": "<test-uid>",
      "displayName": "ConnectToService",
      "traits": [
        { "key": "Environment", "value": "Staging" }
      ]
    }
  ]
}

traitsとpropertiesの両方で、JSON オブジェクトではなくキー値エントリの配列が使用されます。 キーが一意であると想定しないでください。 特性は、MSTest カテゴリやカスタム TestMetadataProperty値など、パブリック TestProperty値を表します。 properties配列には、プラットフォームまたは互換性レイヤーによって提供されるシリアル化可能な文字列プロパティが含まれています。 メモリ内のすべてのプロパティをエクスポートするわけではありません。また、その内部 SerializableKeyValuePairStringProperty 型は外部フレームワークや拡張機能の API ではありません。

検出された UID を --filter-uid とともに使用して、選択したテストを実行します。 検出、実行、取り消し、ライブ更新を備えた型指定された .NET クライアントには、MTP サーバー モードを使用します。

シナリオ別の拡張機能オプション

次の表を使用して、各拡張機能のパッケージとオプションを見つけます。 テスト SDK プロファイルでは、直接パッケージ参照ではなくパッケージを指定できます。

Scenario 必須コンポーネント 機能に関するドキュメント
コード カバレッジを収集する Microsoft.Testing.Extensions.CodeCoverage または coverlet.MTP コードカバレッジ
クラッシュ ダンプまたはハング ダンプを収集する Microsoft.Testing.Extensions.CrashDump または Microsoft.Testing.Extensions.HangDump クラッシュ ダンプとハング ダンプ
テスト レポートを生成する 選択した形式の拡張機能パッケージ (例: Microsoft.Testing.Extensions.TrxReport テスト レポート
ターミナル出力をカスタマイズする MTP コア (追加パッケージなし) ターミナル出力
失敗したテストを再試行する Microsoft.Testing.Extensions.Retry 再試行

テスト アプリのオプションを検出する

--helpを使用してテスト実行可能ファイルを実行するか、MTP モードでdotnet test --help実行して、現在の拡張機能セットで使用可能なオプションを一覧表示します。

MTP 2.4 以降では、不明なオプション エラーにより、使用可能な場合に一意に一致するオプション名が示されます。 このオプションが、テスト アプリケーションが登録していない既知のMicrosoft提供拡張機能に属している場合、エラーはオプションを提供する NuGet パッケージも識別します。

登録済みのプロバイダーとオプションの高度な診断を行う場合は、 --infoを使用して実行します。

登録済みツールを実行する

一部の拡張機能では、テストを実行する代わりにアーティファクトを処理するコマンドが登録されます。 テスト アプリケーションの最初の位置引数としてコマンド名を渡します。 たとえば、TRX 拡張機能は merge-trx と ms-trxcompareを提供します。

--infoを使用してアプリケーションを実行し、登録されているツールとそのコマンド ライン オプションを一覧表示します。 これらのコマンドはテスト アプリケーションに属するものであり、dotnet tool コマンドではありません。

こちらも参照ください

  • 最終更新: