Coverage Analysis from the Command Line

As a global tool for all projects on the computer

• Run:

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

As a local tool for a specific project/directory

• Run:

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

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 2024.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 command-line tool, e.g., dotnet dotCover.dll ...

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

2. Extract the archive.

To generate a stub configuration file

• Run:

  dotCover help <command name> <configuration stub file>

  For example, for dotnet:

  dotCover.exe help dotnet C:\Temp\MyConfig.xml

To run coverage analysis based on the configuration file

• Provide the configuration file with your custom parameter values to a dotCover command. For example, for dotnet:

  dotCover.exe dotnet C:\Temp\MyConfig.xml

  Relative paths defined in the XML configuration file are treated relative to the location of this file.

1. Open the solution folder.

2. Build the solution:

   dotnet build

3. Run tests with coverage analysis:

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

   The dotnet dotcover .NET tool supports the same set of commands and parameters as dotCover.exe and dotCover.sh. For example, to specify a report type, all tools use the --ReportType parameter:

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

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

   dotnet dotcover cover-dotnet "C:\config\config.xml" -- test

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"

   Here:

   • --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. This is a shortcut for --targetArguments="test \"C:\MyProject\MainTests.csproj\""

3. After the command-line tool finishes working, it will create the AppCoverageReport.html file in the same directory with the dotCover command-line tool. Open this file to explore the coverage results in your web browser.

• To exclude/include items from the coverage analysis, you should run the command-line tool with the --filters parameter. For example (for simplicity, we omit non-filter parameters):

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

  This example is equivalent to the XML configuration example. 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 ... --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 ... --attributeFilters=System.Diagnostics.CodeAnalysis.ExcludeFromCodeCoverageAttribute;

  The semicolon (;) works as a separator.

• To exclude specific entities (modules, classes, methods) from the coverage report while keeping the 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>