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

複数の対象を持つプロジェクトでは、対象となる各フレームワークに対してテストが実行されます。 テスト ホストと単体テスト フレームワークは、NuGet パッケージとしてパッケージ化され、プロジェクトの通常の依存関係として復元されます。

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

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

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

  <ItemGroup>
    <PackageReference Include="Microsoft.NET.Test.Sdk" Version="17.4.1" />
    <PackageReference Include="xunit" Version="2.4.2" />
    <PackageReference Include="xunit.runner.visualstudio" Version="2.4.5" />
  </ItemGroup>

</Project>

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

暗黙的な復元

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

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

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

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

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

引数

  • PROJECT | SOLUTION | DIRECTORY | DLL | EXE

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

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

オプション

警告

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

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

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

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

  • --arch <ARCHITECTURE>

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

  • --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 以降で利用可能)

    収集されるクラッシュ ダンプの種類。 必ず、fullmini、または 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」 (テストの実行のモニターと分析) を参照してください。

    たとえば、 オプションを使用してコード カバレッジを --collect "Code Coverage" 収集できます。 詳細については、コード カバレッジの使用に関するページと「コード カバレッジ分析のカスタマイズ」を参照してください。

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

  • -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>

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

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

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

    たとえば、-v:detailed --consoleLoggerParameters:ErrorsOnlyverbosity=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 を使用して、出力ディレクトリ内のテスト資産を使用できます。

  • --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 のビットは、テストを実行するために使用されるものです。 詳細については、次のリソースを参照してください。

  • -t|--list-tests

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

  • -v|--verbosity <LEVEL>

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

  • args

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

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

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

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

--filter <EXPRESSION>

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

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

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

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

演算子 関数
= 完全一致
!= 完全一致ではない
~ 内容
!~ 含まない

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

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

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

演算子 関数
| OR
& AND

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

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

関連項目