dotnet test

この記事の対象: ✔️ .NET Core 3.1 SDK 以降のバージョン

名前

dotnet test - 単体テストを実行するために使用される .NET テスト ドライバー。

構文

dotnet test [<PROJECT> | <SOLUTION> | <DIRECTORY> | <DLL> | <EXE>]
    [--test-adapter-path <ADAPTER_PATH>]
    [-a|--arch <ARCHITECTURE>]
    [--artifacts-path <ARTIFACTS_DIR>]
    [--blame]
    [--blame-crash]
    [--blame-crash-dump-type <DUMP_TYPE>]
    [--blame-crash-collect-always]
    [--blame-hang]
    [--blame-hang-dump-type <DUMP_TYPE>]
    [--blame-hang-timeout <TIMESPAN>]
    [-c|--configuration <CONFIGURATION>]
    [--collect <DATA_COLLECTOR_NAME>]
    [-d|--diag <LOG_FILE>]
    [-f|--framework <FRAMEWORK>]
    [-e|--environment <NAME="VALUE">]
    [--filter <EXPRESSION>]
    [--interactive]
    [-l|--logger <LOGGER>]
    [--no-build]
    [--nologo]
    [--no-restore]
    [-o|--output <OUTPUT_DIRECTORY>]
    [--os <OS>]
    [--results-directory <RESULTS_DIR>]
    [-r|--runtime <RUNTIME_IDENTIFIER>]
    [-s|--settings <SETTINGS_FILE>]
    [-t|--list-tests]
    [-v|--verbosity <LEVEL>]
    [<args>...]
    [[--] <RunSettings arguments>]

dotnet test -h|--help

説明

dotnet test コマンドは、指定されたソリューションで単体テストを実行する場合に使用されます。 dotnet test コマンドは、ソリューションをビルドし、VSTestを使用してソリューション内の各テスト プロジェクトのテスト ホスト アプリケーションを実行します。 テスト ホストは、MSTest、NUnit、xUnit などのテスト フレームワークを使用して特定のプロジェクトでテストを実行し、各テストの成功または失敗を報告します。 すべてのテストが成功した場合、テスト ランナーは 0 の終了コードを返します。それ以外の、いずれかのテストに失敗した場合は、1 を返します。

Note

dotnet test は当初、 VSTest ベースのテスト プロジェクトのみをサポートするように設計されました。 最近のバージョンのテスト フレームワークでは、 Microsoft.Testing.Platform のサポートが追加されています。 この代替テスト プラットフォームは、 VSTest よりも軽量で高速であり、さまざまなコマンド ライン オプションで dotnet test をサポートします。 詳細については、「 Microsoft.Testing.Platform を参照してください。

複数の対象を持つプロジェクトでは、対象となる各フレームワークに対してテストが実行されます。 テスト ホストと単体テスト フレームワークは、NuGet パッケージとしてパッケージ化され、プロジェクトの通常の依存関係として復元されます。 .NET 9 SDK 以降では、これらのテストは既定で並列で実行されます。 並列実行を無効にするには、 TestTfmsInParallel MSBuild プロパティを false に設定します。 詳細については、 並列実行テストと この記事で後述する サンプル コマンド ラインを参照してください。

テスト プロジェクトでは、通常の <PackageReference> 要素を使用してテスト ランナーを指定します。次のサンプル プロジェクト ファイルのようになります。

<Project Sdk="Microsoft.NET.Sdk">

  <PropertyGroup>
    <TargetFramework>net6.0</TargetFramework>
    <Nullable>enable</Nullable>
  </PropertyGroup>

  <ItemGroup>
    <PackageReference Include="Microsoft.NET.Test.Sdk" Version="17.10.0" />
    <PackageReference Include="xunit" Version="2.8.1" />
    <PackageReference Include="xunit.runner.visualstudio" Version="2.8.1" />
  </ItemGroup>

</Project>

Microsoft.NET.Test.Sdk がテスト ホストの場合、xunit はテスト フレームワークです。 また、xunit.runner.visualstudio はテスト アダプターであり、xUnit フレームワークはテスト ホストと連携できます。

暗黙的な復元

復元を必要とするすべてのコマンド (dotnet new、dotnet build、dotnet run、dotnet test、dotnet publish、dotnet pack など) によって暗黙的に実行されるため、dotnet restore を実行する必要がなくなりました。 暗黙的な復元を無効にするには、--no-restore オプションを使用します。

dotnet restoreなどの、明示的な復元が意味のある一部のシナリオや、復元が行われるタイミングを明示的に制御する必要があるビルド システムでは、dotnet restore は引き続き有用なコマンドです。

NuGet フィードの管理方法については、dotnet restore のドキュメントをご覧ください。

ワークロード マニフェストのダウンロード

このコマンドを実行すると、ワークロードの広告マニフェストの非同期バックグラウンド ダウンロードが開始されます。 このコマンドが終了してもダウンロードが実行されている場合、ダウンロードは停止します。 詳細については、「広告マニフェスト」を参照してください。

引数

• PROJECT | SOLUTION | DIRECTORY | DLL | EXE

  • テスト プロジェクトへのパス。
  • ソリューションへのパス。
  • プロジェクトまたはソリューションを含むディレクトリへのパス。
  • テスト プロジェクト ".dll" ファイルへのパス。
  • テスト プロジェクト .exe ファイルへのパス。

  指定しない場合、DIRECTORY 引数を使用して現在のディレクトリを指定する場合と同じ効果があります。

[オプション]

警告

オプションの破壊的変更:

• .NET 7 以降: -a を --test-adapter-path の代わりにエイリアス --arch に切り替える
• .NET 7 以降: -r を --results-directory の代わりにエイリアス --runtime に切り替える

警告

Microsoft.Testing.Platformを使用する場合は、サポートされているオプションについては、dotnet テスト統合を参照してください。 経験則として、テストに関連しないすべてのオプションがサポートされますが、テスト関連のオプションはすべてそのままサポートされていません。

• --test-adapter-path <ADAPTER_PATH>

  追加のテスト アダプターを検索するディレクトリへのパス。 サフィックス .TestAdapter.dll を持つ ".dll" ファイルのみが検査されます。 指定しない場合、テスト ".dll" のディレクトリが検索されます。

  7 より前のバージョンの .NET SDK で使用できる短い形式 -a 。

• --arch <ARCHITECTURE>

  ターゲット アーキテクチャを指定します。 これは、ランタイム識別子 (RID) を設定する簡単な構文です。指定した値は、既定の RID と組み合わされます。 たとえば、win-x64 マシンで --arch x86 と指定すると、RID は win-x86 に設定されます。 このオプションを使用する場合は、-r|--runtime オプションは使用しないでください。 .NET 6 Preview 7 以降で利用できます。

• --artifacts-path <ARTIFACTS_DIR>

  実行されたコマンドからのすべてのビルド出力ファイルは、指定されたパスの下のサブフォルダーに配置され、プロジェクトで区切られます。 詳細については、「 Artifacts 出力レイアウトを参照してください。 .NET 8 SDK 以降で利用可能です。

• --blame

  変更履歴モードでテストを実行します。 このオプションは、テスト ホストがクラッシュする原因となる問題のあるテストを分離するために役立ちます。 クラッシュが検出されると、クラッシュ前に実行されたテストの順序をキャプチャするシーケンス ファイルが TestResults/<Guid>/<Guid>_Sequence.xml に作成されます。

  このオプションではメモリ ダンプは作成されず、テストがハングしている場合は役に立ちません。

• --blame-crash (.NET 5.0 SDK 以降で利用可能)

  テスト ホストが予期せずに終了した場合に、変更履歴モードでテストを実行して、クラッシュ ダンプを収集します。 このオプションは、使用されている .NET のバージョン、エラーの種類、およびオペレーティング システムによって異なります。

  マネージド コードでの例外の場合、ダンプは .NET 5.0 以降のバージョンで自動的に収集されます。 testhost や、やはり .NET 5.0 で実行されてクラッシュした子プロセスのダンプが生成されます。 ネイティブ コードでのクラッシュの場合、ダンプは生成されません。 このオプションは、Windows、macOS、Linux で動作します。

  ネイティブ コードでのクラッシュ ダンプ、または .NET Core 3.1 以前のバージョンを使用しているときのクラッシュ ダンプは、Windows 上でのみ、Procdump を使用して収集できます。 procdump.exe および procdump64.exe を含むディレクトリが、PATH または PROCDUMP_PATH 環境変数に指定されている必要があります。 ツールをダウンロードします。 --blame を意味します。

  .NET 5.0 以降で実行されているネイティブ アプリケーションからクラッシュ ダンプを収集するには、VSTEST_DUMP_FORCEPROCDUMP 環境変数を 1 に設定することで、Procdump を強制的に使用できます。

• --blame-crash-dump-type <DUMP_TYPE> (.NET 5.0 SDK 以降で利用可能)

  収集されるクラッシュ ダンプの種類。 サポートされているダンプの種類は full (既定)、および miniです。 --blame-crash を意味します。

• --blame-crash-collect-always (.NET 5.0 SDK 以降で利用可能)

  予期しないテスト ホストの終了だけでなく、予期されていたものに対しても、クラッシュ ダンプを収集します。

• --blame-hang (.NET 5.0 SDK 以降で利用可能)

  変更履歴モードでテストを実行し、テストが指定のタイムアウトを超えたときにハング ダンプを収集します。

• --blame-hang-dump-type <DUMP_TYPE> (.NET 5.0 SDK 以降で利用可能)

  収集されるクラッシュ ダンプの種類。 必ず、full、mini、または none になります。 none が指定されている場合、タイムアウト時にテスト ホストが終了されますが、ダンプは収集されません。 --blame-hang を意味します。

• --blame-hang-timeout <TIMESPAN> (.NET 5.0 SDK 以降で利用可能)

  テストごとのタイムアウト。それが過ぎると、ハング ダンプがトリガーされ、テスト ホスト プロセスとそのすべての子プロセスは、ダンプされて終了されます。 タイムアウト値は、次のいずれかの形式で指定されます。

  • 1.5h、1.5hour、1.5hours
  • 90m、90min、90minute、90minutes
  • 5400s、5400sec、5400second、5400seconds
  • 5400000ms、5400000mil、5400000millisecond、5400000milliseconds

  単位が使用されていない場合 (例: 5400000)、値はミリ秒単位であると見なされます。 データ ドリブン テストと共に使用すると、タイムアウトの動作は、利用するテスト アダプターに応じて異なります。 xUnit、NUnit の場合。 および MSTest 2.2.4+ の場合、タイムアウトはテスト ケースの後に毎回更新されます。 バージョン 2.2.4 より前の MSTest の場合、すべてのテスト ケースにこのタイムアウトが使用されます。 このオプションは、netcoreapp2.1 以降がインストールされている Windows と、netcoreapp3.1 以降がインストールされている Linux と、net5.0 以降がインストールされている macOS でサポートされています。 --blame と --blame-hang を意味します。

• -c|--configuration <CONFIGURATION>

  ビルド構成を定義します。 ほとんどのプロジェクトの既定値は Debug ですが、プロジェクトでビルド構成設定をオーバーライドできます。

• --collect <DATA_COLLECTOR_NAME>

  テストの実行のためのデータ コレクターを有効にします。 詳細については、「Monitor and analyze test run」 (テストの実行のモニターと分析) を参照してください。

  Windows では、--collect "Code Coverage" オプションを使用してコード カバレッジを収集できます。 詳細については、「コード カバレッジの使用」、「コード カバレッジ分析のカスタマイズ」、および 「GitHub issue dotnet/docs#34479」 を参照してください。

  コード カバレッジを収集するには、 --collect "XPlat Code Coverage" オプションを使用して Coverlet を使用することもできます。

• -d|--diag <LOG_FILE>

  テスト プラットフォームの診断モードを有効にし、指定したファイルとそれ以降のファイルに診断メッセージを出力します。 メッセージをログに記録するプロセスによって、テスト ホスト ログの *.host_<date>.txt やデータ コレクター ログの *.datacollector_<date>.txt などの、作成されるファイルが決まります。

• -e|--environment <NAME="VALUE">

  環境変数の値を設定します。 存在しない場合は変数を作成し、存在する場合はオーバーライドします。 このオプションを使用すると、分離プロセスでテストが強制的に実行されます。 このオプションは複数回指定して、複数の変数を指定できます。

• -f|--framework <FRAMEWORK>

  テストを実行するターゲット フレームワークのターゲット フレームワーク モニカー (TFM)。 ターゲット フレームワークもプロジェクト ファイルに指定する必要があります。

• --filter <EXPRESSION>

  指定された式を使用して、現在のプロジェクト内のテストをフィルタリングします。 フィルター式に一致するテストのみが実行されます。 詳細については、「フィルター オプションの詳細」セクションをご覧ください。 選択的単体テストのフィルター処理の使用方法に関する詳細と例については、「選択的単体テストの実行」をご覧ください。

• -?|-h|--help

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

• --interactive

  コマンドを停止して、ユーザーの入力または操作のために待機させることができます。 たとえば、認証を完了する場合があります。 .NET Core 3.0 SDK 以降で使用できます。

• -l|--logger <LOGGER>

  テスト結果のロガーを指定し、オプションでロガーに切り替えます。 複数のロガーを有効にするには、パラメーターを複数回指定します。 詳細については、「テスト結果の報告」、「ロガーのスイッチ」、およびこの記事の後で出てくる例に関するセクションを参照してください。

  コマンド ライン スイッチをロガーに渡すには、次の手順を実行します:

  • 省略形ではなく、スイッチの完全な名前を使用します (たとえば、 verbosity ではなく v)。
  • 先頭のダッシュを省略します。
  • 各スイッチを区切るスペースをセミコロン ; で置き換えます。
  • スイッチに値がある場合は、そのスイッチとその値の間のコロン区切り記号を等号 =に置き換えます。

  たとえば、-v:detailed --consoleLoggerParameters:ErrorsOnly は verbosity=detailed;consoleLoggerParameters=ErrorsOnly になります。

• --no-build

  実行前にテスト プロジェクトをビルドしません。 また、--no-restore フラグが暗黙的に設定されます。

• --nologo

  Microsoft TestPlatform バナーを表示せずにテストを実行します。 .NET Core 3.0 SDK 以降で使用できます。

• --no-restore

  コマンドを実行するときに、暗黙的な復元を実行しません。

• -o|--output <OUTPUT_DIRECTORY>

  実行するバイナリを検索するディレクトリです。 指定しない場合、既定のパスは ./bin/<configuration>/<framework>/ になります。 (TargetFrameworks プロパティを使用した) ターゲット フレームワークが複数あるプロジェクトの場合は、このオプションを指定するときに --framework も定義する必要があります。 dotnet test では常に、出力ディレクトリからテストが実行されます。 AppDomain.BaseDirectory を使用して、出力ディレクトリ内のテスト資産を使用できます。

  • .NET 7.0.200 SDK 以降

    ソリューションでこのコマンドを実行するときに --output オプションを指定すると、出力パスの不明なセマンティクスが原因で、CLI から警告 (7.0.200 のエラー) が出力されます。 このオプションは、ビルドされたすべてのプロジェクトのすべての出力が指定されたディレクトリにコピーされるため、この --output オプションは許可されません。これは、複数のターゲットを持つプロジェクトと、直接および推移的依存関係の異なるバージョンを持つプロジェクトと互換性がありません。 詳しくは、「ソリューション レベルの --output オプションがビルド関連コマンドで無効に」を参照してください。

• --os <OS>

  ターゲット オペレーティング システム (OS) を指定します。 これは、ランタイム識別子 (RID) を設定する簡単な構文です。指定した値は、既定の RID と組み合わされます。 たとえば、win-x64 マシンで --os linux と指定すると、RID は linux-x64 に設定されます。 このオプションを使用する場合は、-r|--runtime オプションは使用しないでください。 .NET 6 以降で使用可能です。

• --results-directory <RESULTS_DIR>

  テスト結果が配置されるディレクトリです。 指定されたディレクトリが存在しない場合は、作成されます。 既定値は、プロジェクト ファイルが含まれるディレクトリの TestResults です。

  7 より前のバージョンの .NET SDK で使用できる短い形式 -r 。

• -r|--runtime <RUNTIME_IDENTIFIER>

  テスト対象のターゲット ランタイム。

  .NET SDK 7 以降で使用できる短い形式 -r。

• -s|--settings <SETTINGS_FILE>

  テストの実行に使用する .runsettings ファイルです。 TargetPlatform 要素 (x86|x64) は dotnet test には影響しません。 x86 を対象とするテストを実行するには、x86 バージョンの .NET Core をインストールします。 パスにある dotnet.exe のビットは、テストを実行するために使用されるものです。 詳細については、次のリソースを参照してください。

  • .runsettings ファイルを使用して単体テストを構成します。
  • テスト実行を構成する

• -t|--list-tests

  テストを実行する代わりに、検出されたテストを一覧表示します。

• -v|--verbosity <LEVEL>

  コマンドの詳細レベルを設定します。 指定できる値は、q[uiet]、m[inimal]、n[ormal]、d[etailed]、および diag[nostic] です。 既定値は、minimal です。 詳細については、LoggerVerbosityを参照してください。

• args

  アダプターに渡す追加の引数を指定します。 複数の引数を指定する場合は、空白で区切ります。

  可能な引数の一覧は、指定された動作に依存します。

  • プロジェクト、ソリューション、またはディレクトリを指定する場合、またはこの引数を省略する場合、呼び出しは msbuild に転送されます。 その場合、使用可能な引数は、dotnet msbuild のドキュメントで確認できます。
  • .dll または .exe を指定する場合、呼び出しは vstest に転送されます。 その場合、使用可能な引数は、dotnet vstest のドキュメントで確認できます。

• RunSettings 引数

インラインの RunSettings は、コマンド ラインの最後の引数として "-- " の後に渡されます (-- の後のスペースに注意してください)。 インラインの RunSettings は [name]=[value] のペアとして指定されます。 複数の [name]=[value] のペアを区切るにはスペースを使用します。

例: dotnet test -- MSTest.DeploymentEnabled=false MSTest.MapInconclusiveToFailed=True

詳しくは、「コマンド ラインで RunSettings 引数を渡す」をご覧ください。

例

• 現在のディレクトリのプロジェクトでテストを実行します。

  dotnet test
  

• test1 プロジェクトでテストを実行します。

  dotnet test ~/projects/test1/test1.csproj
  

• test1.dll アセンブリを使用してテストを実行します。

  dotnet test ~/projects/test1/bin/debug/test1.dll
  

• 現在のディレクトリでプロジェクトのテストを実行し、trx 形式でテスト結果ファイルを生成します。

  dotnet test --logger trx
  

• 現在のディレクトリでプロジェクトのテストを実行し、(Coverlet コレクター統合をインストールした後) コード カバレッジ ファイルを生成します。

  dotnet test --collect:"XPlat Code Coverage"
  

• 現在のディレクトリでプロジェクトのテストを実行し、コード カバレッジ ファイルを生成します (Windows のみ)。

  dotnet test --collect "Code Coverage"
  

• 現在のディレクトリでプロジェクトのテストを実行し、詳細をコンソールに記録します。

  dotnet test --logger "console;verbosity=detailed"
  

• 現在のディレクトリにあるプロジェクトでテストを実行し、trx ロガーを使用して TestResults フォルダー内の testResults.trx にログを記録します。

  dotnet test --logger "trx;logfilename=testResults.trx"
  

  ログ ファイル名が指定されているため、マルチターゲット プロジェクトの場合は各ターゲット フレームワークに同じ名前が使用されます。 各ターゲット フレームワークの出力によって、前のターゲット フレームワークの出力は上書きされます。 ファイルはテスト プロジェクト フォルダー内の TestResults フォルダーに作成されます。これは、相対パスがそのフォルダーを基準にしているからです。 次の例は、ターゲット フレームワークごとに個別のファイルを作成する方法を示しています。

• 現在のディレクトリにあるプロジェクトでテストを実行し、trx ロガーを使用して TestResults フォルダー内のファイルにログを記録します。ファイル名は、ターゲット フレームワークごとに一意とします。

  dotnet test --logger:"trx;LogFilePrefix=testResults"
  

• 現在のディレクトリにあるプロジェクトでテストを実行し、html ロガーを使用して TestResults フォルダー内の testResults.html にログを記録します。

  dotnet test --logger "html;logfilename=testResults.html"
  

• 現在のディレクトリのプロジェクトでテストを実行し、テスト ホストがクラッシュしたときに実行されていたテストを報告します。

  dotnet test --blame
  

• -bl (バイナリ ログ) 引数を msbuild に指定して、test1 プロジェクトでテストを実行します。

  dotnet test ~/projects/test1/test1.csproj -bl
  

• MSBuild DefineConstants プロパティを DEV に設定して、test1 プロジェクトでテストを実行します。

  dotnet test ~/projects/test1/test1.csproj -p:DefineConstants="DEV"
  

• MSBuild TestTfmsInParallel プロパティを false に設定して、test1 プロジェクトでテストを実行します。

  dotnet test ~/projects/test1/test1.csproj -p:TestTfmsInParallel=false
  

フィルター オプションの詳細

--filter <EXPRESSION>

<Expression> の形式は <property><operator><value>[|&<Expression>] です。

<property> は Test Case の属性です。 よく利用される単体テスト フレームワークでサポートされるプロパティは以下の通りです。

テスト フレームワーク	サポートされるプロパティ
MSTest	FullyQualifiedName 名前 ClassName 優先順位 TestCategory
xUnit	FullyQualifiedName DisplayName カテゴリ
NUnit	FullyQualifiedName 名前 カテゴリ 優先順位

<operator> は、プロパティと値の関係を示します。

オペレーター	Function
=	完全一致
!=	完全一致ではない
~	Contains
!~	含まない

<value> は、文字列です。 すべての参照で大文字と小文字が区別されます。

<operator> を含まない式は、自動的に FullyQualifiedName プロパティの contains とみなされます (たとえば、dotnet test --filter xyz は dotnet test --filter FullyQualifiedName~xyz と同じです)。

式は条件演算子を使用して結合できます。

オペレーター	Function
|	または
&	かつ

条件演算子を使用する場合は、式をかっこで囲みます (例: (Name~TestMethod1) | (Name~TestMethod2))。

選択的単体テストのフィルター処理の使用方法に関する詳細と例については、「選択的単体テストの実行」をご覧ください。

関連項目

• フレームワークとターゲット
• .NET Runtime Identifier (RID) カタログ
• コマンドラインを使用して runsettings 引数を渡す