Coverage Analysis from the Command Line

To install the dotCover console runner from the archive

1. Download dotCover command line tools package for the required operating system.

2. Copy the archive to the machine where you are going to set up the console runner.

3. Extract files from the archive to a directory, from which you are going to start the console runner executable file dotCover.exe (Windows), dotCover.sh (Linux, macOS).

To install the dotCover console runner from the NuGet package

1. Open the required unit test project and add the reference to the JetBrains.dotCover.CommandLineTools package. For example:

   Install-Package JetBrains.dotCover.CommandLineTools -Version 2021.1.0

2. On your CI/CD server, add a build step that restores NuGet packages.

3. On your CI/CD server, add build steps that use the console runner.

To install the dotCover console runner as a .NET global tool

• To install the dotCover console runner as a global .NET Core tool in the default location, run the following command line:

  dotnet tool install JetBrains.dotCover.GlobalTool -g

• To install it as a local tool:

  dotnet new tool-manifest dotnet tool install JetBrains.dotCover.GlobalTool

• For further instructions, refer to the official Microsoft documentation.

1. Make sure your unit test project is built.

2. Navigate to the directory where dotCover.exe is located.

3. Type the following command in the console:

   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"

   Where:

   • TargetExecutable is the path to the unit testing framework runner

   • TargetArguments are arguments passed to the runner - the compiled unit test assembly. Note that if these arguments contain paths with spaces, you should escape them with additional double quotes and a backslash, for example, ... /TargetArguments="\"D:\My Projects\My Application\bin\Debug\AppTests.dll""

   • Output is the report filename.

   • ReportType is the type of the report (in this case, we generate an HTML report)

4. When the console runner exits, the AppCoverageReport.html file should appear in the same directory with the dotCover console runner. Open this file to explore the coverage results in your web browser.

5. Alternatively, you can pass parameters in an XML file. To do so, type dotCover help cover coverage.xml in the command line.

6. Open the generated coverage.xml file and specify the configuration parameters. For example, the configuration file can look as follows:

   <?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. Use dotCover cover coverage.xml to run the coverage with the specified parameters.

(Recommended) To analyze coverage in a .NET Core project with the global tool

1. Open the solution folder.

2. Build the solution:

   dotnet build

3. Run tests with coverage analysis:

   dotnet dotcover test --no-build

   The dotnet dotcover does not support the commands of dotCover.exe – it always runs coverage analysis as if you run dotCover.exe cover. The arguments specified after dotnet dotcover are passed not to the dotcover but to the dotnet tool. If you want to provide arguments to dotCover, use the same arguments as for the standard dotCover.exe runner but with the dc prefix. For example, to specify a report type, use --dcReportType instead of --ReportType:

   dotnet dotcover test --dcReportType=XML

   If you configured dotCover.exe with an XML file and want to continue using it, specify a path to the file:

   dotnet dotcover test --dcXML="C:\config\config.xml"
   All parameters in the XML file that are not applicable to this runner type will be ignored.

To analyze coverage in a .NET Core project with dotCover.exe, dotCover.sh

1. Navigate to the directory where dotCover.exe / dotCover.sh is located.

2. Type the following command in the console:

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

   where:

   • --output is the report filename.

   • --reportType is the type of the report (in this case, we generate an HTML report)

   • -- test "C:\MyProject\MainTests.csproj" at the end is an argument passed to dotnet. Actually, you can replace it with --TargetArguments="test \"C:\MyProject\MainTests.csproj\"" but that is much longer.

   • You've probably noticed that we're using Unix-style syntax for command-line arguments. You can use this syntax on Windows as well. For example, the following is interchangeable on Windows (but not on macOS and Linux): /TempDir:"../myDir" and --tempDir="../myDir"

3. When the console runner exits, the AppCoverageReport.html file should appear in the same directory with the dotCover console runner. Open this file to explore the coverage results in your web browser.

Set up coverage filters using XML configuration file

• To exclude some items (modules, classes, methods) from the coverage report while keeping all others, add the corresponding entries to the ExcludeFilters node. For example:

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

  Here:

  • <ModuleMask>AdditionalTests</ModuleMask> - all tests from the corresponding module will be excluded. AdditionalTests here is an assembly name without extension.

  • <ClassMask>MainTests.Unit*</ClassMask> - all classes whose name starts with MainTests.Unit will be excluded.

  • <ClassMask>MainTests.IntegrationTests</ClassMask> <FunctionMask>TestFeature1</FunctionMask> - the TestFeature1 method of the MainTests.IntegrationTests class will be excluded. Note that FunctionMask must always contain method's short name. If you omit any element in FilterEntry, dotCover will consider this as a wildcard. For example, if you remove ClassMask in this particular case, dotCover will exclude all TestFeature1 methods (belonging to all modules and classes).

• Alternatively, to include only the desired items while excluding all others of the same kind, add the corresponding entries to the IncludeFilters node.

• Another option, is to filter out classes and methods based on their attributes. For example, to filter out methods marked with the System.Diagnostics.CodeAnalysis.ExcludeFromCodeCoverageAttribute attribute, we can add the following to the coverage.xml configuration file:

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

Set up coverage filters using command-line arguments

• To exclude/include items from the coverage analysis, you should run the console runner with the /Filters parameter. For example (for simplicity, we omit parameters related to the coverage target):

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

  This example is equivalent to the XML configuration example from above. Note that the semicolon (;) separates not only filter entries but also items inside filter entries.

• An entry that starts with -: is responsible for excluding, and vice versa, an entry that starts with +: - for including.

• If you need to exclude/include only a module, you can omit the module keyword:

  dotCover.exe cover ... /Filters=-:AdditionalTests;

• To filter out classes and methods based on their attributes, you should use the /AttributeFilters parameter. For example, to filter out methods marked with the System.Diagnostics.CodeAnalysis.ExcludeFromCodeCoverageAttribute attribute:

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

  The semicolon (;) works as a separator.

Run coverage for multiple projects in separate steps

1. Create two configuration files for running the cover (c) command on each of the tests projects. testProject1.xml for the TestProject1 that uses MSTest:

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

   and testProject2.xml for the TestProject2 that uses NUnit:

   <?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. Run the cover (c) command on each of the tests projects using the prepared configuration files: dotCover c testProject1.xml and dotCover c testProject2.xml. As a result you'll get two coverage snapshots, Snapshot1.dcvr and Snapshot2.dcvr.

3. Run the merge (m) command to merge both snapshots:

   dotCover m merge.xml

   where the merge.xml is the configuration file:

   <?xml version="1.0" encoding="utf-8"?> <MergeParams> <Source>Snapshot1.dcvr</Source> <Source>Snapshot2.dcvr</Source> <Output>MergedSnapshots.dcvr</Output> </MergeParams>

4. To build an HTML test report from the merged snapshots, run the report (r) command

   dotCover r report.xml

   where the report.xml is the configuration file:

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