dotCover 2024.1 ヘルプ

コマンドラインからのカバレッジ分析

dotCover コマンドラインツールを使用すると、次のことが可能になります。

  • 任意のテストランナー (MSTest、NUnit、xUnit、MSpec など) の実行を制御し、実行されたテストのカバレッジをカバレッジスナップショットに記録します。

  • たとえば、さまざまなテストフレームワークを使用する単体テストのスナップショットを結合するには、merge コマンドを使用してカバレッジスナップショットをマージします。

  • report コマンドを使用して、さまざまな形式でカバレッジレポートを生成します。

  • さらに

このツールは、Windows (x86、x64、arm64)、Linux (x64、arm32、arm64、musl-x64、musl-arm64)、macOS (x64、arm64) で使用できます。

配信形式

このツールは次の形式で配布されます。

フォーマット

クロスプラットフォームのフレームワークに依存するツール


(すべての OS、.NET がインストールされている必要があります)


プラットフォーム固有の自己完結型ツール


(OS 固有、バンドルされた .NET)


プラットフォーム固有の


(Windows のみ、.NET フレームワークが必要)


アーカイブ

ダウンロードページ

ダウンロードページ

ダウンロードページ

NuGet パッケージ

ダウンロードページ (英語)

ダウンロードページ (英語)

ダウンロードページ (英語)

dotCover 2023.2 以前では、コマンドラインツールも別のパッケージ(英語)として配布されていましたが、今後はメンテナンスされなくなります。

dotCover コマンドラインツールをインストールする

ツールをインストールするにはいくつかの方法があります。

dotnet ドライバーを使用して、コンピューターまたは CI/CD サーバー上でローカルにカバレッジ分析を実行する場合に推奨されます。

コンピューター上のすべてのプロジェクトのグローバルツールとして

  • 実行:

    dotnet tool install --global JetBrains.dotCover.CommandLineTools --version 2024.1.0

特定のプロジェクト / ディレクトリのローカルツールとして

  • 実行:

    dotnet tool install JetBrains.dotCover.CommandLineTools --version 2024.1.0 --tool-path "some/path"

CI/CD サーバーのビルドステップとしてカバレッジ分析を実行する場合に推奨されます。

  1. 必要な単体テストプロジェクトを開き、JetBrains.dotCover.CommandLineTools(英語) パッケージへの参照を追加します。例:

    Install-Package JetBrains.dotCover.CommandLineTools -Version 2024.1.0
  2. CI/CD サーバーで、NuGet パッケージを復元するビルドステップを追加します。

  3. CI/CD サーバーで、dotnet dotCover.dll ... などのコマンドラインツールを使用するビルドステップを追加します。

コマンドラインツールをインストールするための汎用的な方法。

  1. 必要なオペレーティングシステム用の dotCover コマンドラインツールパッケージをダウンロードします

  2. アーカイブを抽出します。

dotCover コマンドラインツールを構成する

dotCover コマンドラインツールは、コマンドラインパラメーターまたは XML 構成ファイルを使用して構成できます。両方のアプローチを同時に使用できます。競合が発生した場合、コマンドラインパラメーターは XML で指定されたパラメーターをオーバーライドします。

例:

dotCover.exe dotnet --output=AppCoverageReport.html -- test "C:\MyProject\MainTests.csproj"
  • ツールのインストール型や OS に関係なく、同じパラメーター構文 (例: --TargetExecutable=MyApp.exe) を使用できます。

  • コマンドラインパラメーターでは大文字と小文字が区別されます。たとえば、次は等しい: --TargetExecutable=MyApp.exe--targetexecutable=MyApp.exe

  • スラッシュ / および二重ダッシュ -- を使用してパラメーターを指定できます。たとえば、次は等しい: --TargetExecutable=MyApp.exe/TargetExecutable=MyApp.exe

  • 等号 = とコロン : を使用してパラメーター値を指定できます。たとえば、次は等しい: --TargetExecutable=MyApp.exe--TargetExecutable:MyApp.exe

  • コマンドラインパラメーターの相対パスは、コマンドラインツールの作業ディレクトリを基準にして処理されます。

  • パラメーターの完全なリストについては、「コマンドリファレンス」を参照してください。

例:

dotCover.exe dotnet MyConfig.xml

すべての dotCover コマンド ( version および help を除く) は、XML 構成ファイル内のパラメーターを受け入れることができます。構成ファイルは、すべてのパラメーターをインラインで指定したり、バッチファイルに含めたりするための合理的な代替手段です。サポートされている XML タグのエラーを回避するには、最初に構成スタブファイルを生成し、次にそのファイルにカスタムパラメーター値を指定することをお勧めします。

特定の dotCover コマンドの構成スタブファイルを生成するには、次のコマンドを実行します。

dotCover help <command name> <configuration stub file>

例: cover コマンドの場合:

dotCover help cover config.xml

XML 構成ファイルで定義された相対パスは、このファイルの場所を基準にして扱われます。

.NET プロジェクトの単体テストカバレッジを分析する

コマンドラインツールをどのようにインストールしたかに応じて、.NET および .NET Core プロジェクトでカバレッジ分析を実行するには 2 つの方法があります。フレームワークに依存する .NET ツール (dotnet ドライバー経由) を使用する方法と、自己完結型ツール (dotCover.exedotCover.sh) を使用する方法です。

  1. ソリューションフォルダーを開きます。

  2. ソリューションを構築します。

    dotnet build
  3. カバレッジ分析でテストを実行する:

    dotnet dotcover cover-dotnet -- test --no-build

    dotnet dotcover .NET ツールは、dotCover.exe および dotCover.sh と同じコマンドとパラメーターのセットをサポートします。例: レポート型を指定するには、すべてのツールで --ReportType パラメーターを使用します。

    dotnet dotcover cover-dotnet --ReportType=XML -- test

    XML ファイルを使用して dotCover.exe を構成し、それを引き続き使用する場合は、ファイルへのパスを指定します。

    dotnet dotcover cover-dotnet "C:\config\config.xml" -- test
  1. dotCover.exe/dotCover.sh が配置されているディレクトリに移動します。

  2. コンソールに次のコマンドを入力します。

    dotCover.exe dotnet --output=AppCoverageReport.html --reportType=HTML -- test "C:\MyProject\MainTests.csproj"

    ここに:

    • --output はレポートのファイル名です

    • --reportType はレポートのタイプです (この場合、HTML レポートを生成します)

    • 最後の -- test "C:\MyProject\MainTests.csproj"dotnet に渡される引数です。実際には、--TargetArguments="test \"C:\MyProject\MainTests.csproj\"" に置き換えることができますが、はるかに長くなります。

  3. コマンドラインツールの動作が完了すると、dotCover コマンドラインツールと同じディレクトリに AppCoverageReport.html ファイルが作成されます。このファイルを開いて、Web ブラウザーでカバレッジ結果を調べます。

.NET フレームワークプロジェクトの単体テストカバレッジを分析する

次の手順は、.NET フレームワークプロジェクトでコマンドラインツールを使用してカバレッジを実行する最も単純なケースを示しています。

  1. ユニットテストプロジェクトがビルドされていることを確認してください。

  2. dotCover.exe があるディレクトリに移動します。

  3. コンソールに次のコマンドを入力します。

    dotCover cover /TargetExecutable="D:\Program Files\NUnit 2.6\bin\nunit-console.exe" /TargetArguments="D:\Projects\TheApplication\bin\Debug\AppTests.dll" /Output="AppCoverageReport.html" /ReportType="HTML"

    説明:

    • TargetExecutable は、単体テストフレームワークランナーへのパスです。

    • TargetArguments は、ランナー(コンパイル済みユニットテストアセンブリ)に渡される引数です。これらの引数にスペースが含まれるパスが含まれる場合は、追加の二重引用符とバックスラッシュを使用してエスケープする必要があることに注意してください(例: ... /TargetArguments="\"D:\My Projects\My Application\bin\Debug\AppTests.dll"\"

    • Output はレポートファイル名です。

    • ReportType はレポートのタイプです (この場合、HTML レポートを生成します)

  4. コマンドラインツールが終了すると、AppCoverageReport.html ファイルが dotCover コマンドラインツールと同じディレクトリに表示されます。このファイルを開いて、Web ブラウザーでカバレッジ結果を調べます。

  5. また、XML ファイルでパラメーターを渡すこともできます。これを行うには、コマンドラインで dotCover help cover coverage.xml と入力します。

  6. 生成された coverage.xml ファイルを開き、設定パラメーターを指定します。例: 設定ファイルは次のようになります。

    <?xml version="1.0" encoding="utf-8"?> <AnalyseParams> <TargetExecutable>D:\Program Files\NUnit 2.6\bin\nunit-console.exe</TargetExecutable> <TargetArguments>D:\Projects\TheApplication\bin\Debug\AppTests.dll</TargetArguments> <Output>AppCoverageReport.html</Output> <ReportType>html</ReportType> </AnalyseParams>
  7. dotCover cover coverage.xml を使用して、指定されたパラメーターでカバレッジを実行します。

カバレッジフィルターを適用する

カバレッジレポートに興味のない情報が含まれている場合は、カバレッジレポートに何を含めるか、何を除外するかをコマンドラインツールに指示するフィルターを適用できます。

  • 包含フィルターと除外フィルターは任意の順序で指定できます。

  • 順序に関係なく、コマンドラインツールは最初に包含フィルターを適用し、次に除外フィルターを適用します。

  • 包含フィルターが明示的に指定されていない場合、コマンドラインツールは最初にすべてを含めてから、除外フィルターで指定されたものを除外します。

  • 包含フィルターがある場合、コマンドラインツールはまず包含フィルターに一致しないすべてのものを除外し、次に明示的な除外フィルター (存在する場合) を適用します。

デフォルトでは、除外フィルターを指定するかどうかに関係なく、コマンドラインツールはシステムアセンブリに次のフィルターを追加します: mscorlibSystemSystem.*Microsoft .*

必要に応じて、これらのデフォルトフィルターを DisableDefaultFilters コマンドラインパラメーターで無効にすることができます。

カバレッジフィルターを指定するには、コマンドラインパラメーターを使用する方法と XML 構成ファイルを使用する方法の 2 つがあります。

  • カバレッジ分析から項目を除外または含めるには、--Filters パラメーターを指定してコマンドラインツールを実行する必要があります。次に例を示します (わかりやすくするために、カバレッジターゲットに関連するパラメーターを省略します)。

    dotCover.exe cover ... --Filters=-:module=AdditionalTests;-:type=MainTests.Unit*; -:type=MainTests.IntegrationTests;function=TestFeature1;

    この例は、XML 構成と同等です。セミコロン (;) はフィルターエントリだけでなく、フィルターエントリ内の項目も区切ることに注意してください。

  • -: で始まるエントリは、+: で始まるエントリを除外します(その逆もあります)。

  • モジュールのみを除外 / インクルードする必要がある場合は、module キーワードを省略できます。

    dotCover.exe cover ... --Filters=-:AdditionalTests;
  • それらの属性に基づいてクラスとメソッドを除外するには、--AttributeFilters パラメーターを使用する必要があります。例: System.Diagnostics.CodeAnalysis.ExcludeFromCodeCoverageAttribute 属性でマークされたメソッドをフィルターにかける:

    dotCover.exe cover ... --AttributeFilters=System.Diagnostics.CodeAnalysis.ExcludeFromCodeCoverageAttribute;

    セミコロン(;)はセパレータとして機能します。

  • カバレッジレポートから一部のアイテム(モジュール、クラス、メソッド)を除外し、他のすべてを保持するには、対応するエントリを ExcludeFilters ノードに追加します。例:

    ... <Filters> <ExcludeFilters> <FilterEntry> <ModuleMask>AdditionalTests</ModuleMask> </FilterEntry> <FilterEntry> <ClassMask>MainTests.Unit*</ClassMask> </FilterEntry> <FilterEntry> <ClassMask>MainTests.IntegrationTests</ClassMask> <FunctionMask>TestFeature1</FunctionMask> </FilterEntry> </ExcludeFilters> </Filters>

    ここに:

    • <ModuleMask>AdditionalTests</ModuleMask> - 対応するモジュールからのすべてのテストは除外されます。ここ AdditionalTests は拡張子のないアセンブリ名です。

    • <ClassMask>MainTests.Unit*</ClassMask> - 名前が MainTests.Unit で始まるすべてのクラスが除外されます。

    • <ClassMask>MainTests.IntegrationTests</ClassMask> <FunctionMask>TestFeature1</FunctionMask> - MainTests.IntegrationTests クラスの TestFeature1 メソッドは除外されます。FunctionMask は常にメソッドのショートネームを含まなければならないことに注意してください。FilterEntry の要素を省略すると、dotCover はこれをワイルドカードと見なします。例: この特別な場合に ClassMask を削除すると、dotCover はすべての TestFeature1 メソッド(すべてのモジュールとクラスに属する)を除外します。

  • または、同じ種類の他のすべてを除外しながら、目的の項目のみを含めるには、IncludeFilters ノードに対応するエントリを追加します。

  • もう 1 つの選択肢は、クラスとメソッドをそれらの属性に基づいて除外することです。例: System.Diagnostics.CodeAnalysis.ExcludeFromCodeCoverageAttribute 属性でマークされたメソッドを除外するために、coverage.xml 設定ファイルに以下を追加することができます。

    ... <AttributeFilters> <AttributeFilterEntry> <ClassMask>System.Diagnostics.CodeAnalysis.ExcludeFromCodeCoverageAttribute</ClassMask> </AttributeFilterEntry> </AttributeFilters>

カバレッジ結果の範囲を変更する

デフォルトでは、カバレッジスナップショットの準備が完了すると、分析のために読み込まれたアセンブリ、つまりフィルターで除外されず、テストが行われたアセンブリに関する情報のみが含まれます。これにより、全体のカバレッジ率が不正確になる可能性があります。

必要に応じて、情報をスナップショットに追加する必要があるアセンブリの範囲を変更することができます。これを行うには、Scope パラメーターを使用します。例: プロジェクトのすべてのアセンブリをスナップショットに追加するには、以下を構成ファイルに追加します。

<Scope> <ScopeEntry>ProjectFolder/**/*.dll</ScopeEntry> <ScopeEntry>ProjectFolder/**/*.exe</ScopeEntry> </Scope>

フィルターで除外されたものはすべて、指定されたスコープに関係なく除外されます。

複数のテストプロジェクトをカバー

ソリューション内に複数の単体テストプロジェクトがある場合は、「基本シナリオ」で説明したように、それらすべてのカバレッジを一度に実行できます。この場合、各アセンブリへの絶対パスの指定を避けるために、テストアセンブリを指定するときに TargetWorkingDir パラメーターを使用できます。例: XML 構成ファイルの場合:

<?xml version="1.0" encoding="utf-8"?> <AnalyseParams> <TargetExecutable>D:\Program Files\NUnit 2.6\bin\nunit-console.exe</TargetExecutable> <TargetArguments>AppTests.dll AppTests2.dll AppTests3.dll</TargetArguments> <TargetWorkingDir>D:\Projects\TheApplication\bin\Debug</TargetWorkingDir> <Output>AppCoverageReport.html</Output> <ReportType>html</ReportType> </AnalyseParams>

ただし、単体テストプロジェクトが異なる単体テストフレームワークを使用している場合、このアプローチは機能しません。このような場合、カバレッジ、マージ、レポートを個別のステップに分割できます。

MSTest を使用する TestProject1 と NUnit を使用する TestProject2 という 2 つの単体テストプロジェクトがあるとします。両方のプロジェクトでカバレッジを実行し、単一のレポートを取得するには、次の手順を実行します。

dotCover: Merging coverages snapshot into a single report

複数のプロジェクトのカバレッジを個別のステップで実行する

  1. 各テストプロジェクトでカバー (c) コマンドを実行するための 2 つの構成ファイルを作成します。MSTest を使用する TestProject1testProject1.xml:

    <?xml version="1.0" encoding="utf-8"?> <CoverageParams> <TargetExecutable>C:\Program Files (x86)\Microsoft Visual Studio 12.0\Common7\IDE\MSTest.exe</TargetExecutable> <TargetArguments>TestProject1.dll</TargetArguments> <TargetWorkingDir>D:\Projects\TheApplication\bin\Debug</TargetWorkingDir> <Output>Snapshot1.dcvr</Output> </CoverageParams>

    NUnit を使用する TestProject2 の場合は testProject2.xml:

    <?xml version="1.0" encoding="utf-8"?> <CoverageParams> <TargetExecutable>D:\Program Files\NUnit 2.6\bin\nunit-console.exe</TargetExecutable> <TargetArguments>TestProject2.dll</TargetArguments> <TargetWorkingDir>D:\Projects\TheApplication\bin\Debug</TargetWorkingDir> <Output>Snapshot2.dcvr</Output> </CoverageParams>
  2. 準備した構成ファイル dotCover c testProject1.xml および dotCover c testProject2.xml を使用して、各テストプロジェクトで cover (c) コマンドを実行します。結果として、Snapshot1.dcvrSnapshot2.dcvr という 2 つのカバレッジスナップショットが得られます。

  3. マージ (m) コマンドを実行して、両方のスナップショットをマージします。

    dotCover m merge.xml

    ここで、merge.xml は構成ファイルです。

    <?xml version="1.0" encoding="utf-8"?> <MergeParams> <Source>Snapshot1.dcvr</Source> <Source>Snapshot2.dcvr</Source> <Output>MergedSnapshots.dcvr</Output> </MergeParams>
  4. マージされたスナップショットから HTML テストレポートを作成するには、報告する (r) コマンドを実行します

    dotCover r report.xml

    ここで、report.xml は構成ファイルです。

    <?xml version="1.0" encoding="utf-8"?> <ReportParams> <Source>MergedSnapshots.dcvr</Source> <Output>CoverageReport.html</Output> <ReportType>html</ReportType> </ReportParams>

シンボルファイルを検索する (PDB)

対象バイナリのシンボルファイル(PDB)を見つけることは、カバレッジを計算するために不可欠です。単体テストスタートアッププロジェクトをカバーする場合、dotCover は現在のソリューションの構造を使用してシンボルファイルを簡単に見つけます。

デフォルトでは、次の場所にあるシンボルファイルを検索します。

  • バイナリファイルが存在するディレクトリと同じディレクトリにあります。

  • バイナリファイル内で指定されたデバッグディレクトリ内 ;

  • _NT_SYMBOL_PATH 環境変数とレジストリで指定されたすべてのディレクトリ

必要に応じて、シンボルファイルを検索する他の場所を指定できます。これを行うには、cover または cover-dotnet コマンドを使用するときに次のパラメーターを使用します。

  • SymbolSearchPaths パラメーターを使用して、シンボルファイルを検索するためのパスのセミコロンで区切られたリストを指定します。各パスは、ディレクトリパスまたはシンボルサーバーパス (例: srv*C:\LocalSymbols*http://symbolserver:33417/) のいずれかになります。

  • AllowSymbolServerAccess パラメーターを使用して、SymbolSearchPaths パラメーターまたは _NT_SYMBOL_PATH 環境変数で指定された dotCover アクセスシンボルサーバーを許可します。