Coverlet

Driver	Current version	Downloads
coverlet.MTP
coverlet.collector
coverlet.msbuild
coverlet.console

Coverlet is a cross platform code coverage framework for .NET, with support for line, branch and method coverage. It works with .NET Framework on Windows and .NET Core on all supported platforms.

[!NOTE] Coverlet only supports modern .NET SDK-style projects.

Coverlet documentation reflect the current repository state of the features, not the released ones. Check the changelog to understand if the documented feature you want to use has been officially released.

Main contents

• QuickStart
• How It Works
• Drivers features differences
• Deterministic build support
• Known Issues
• Consume nightly build
• Feature samples
• Experimental features
• Cake Add-In
• Visual Studio Add-In
• Changelog
• Roadmap

Quick Start

Coverlet can be used through four different drivers

• Microsoft Testing Platform integration (coverlet.MTP)
• As a .NET Global tool (supports standalone integration tests)
• VSTest engine integration
• MSBuild task integration

Coverlet supports only SDK-style projects https://docs.microsoft.com/en-us/visualstudio/msbuild/how-to-use-project-sdk?view=vs-2019

Microsoft Testing Platform Integration (guide)

Installation (coverlet.MTP)

dotnet add package coverlet.MTP

[!NOTE] Add the coverlet.MTP package only to test projects that use the Microsoft Testing Platform. This package is designed for projects using Microsoft.Testing.Platform (MTP) as the test runner, not the traditional VSTest runner.

Usage (coverlet.MTP)

Coverlet integrates with the Microsoft Testing Platform as an extension. To enable coverage collection, run your tests with the --coverlet flag:

dotnet run --project <your-test-project> -- --coverlet

Or when using dotnet test with MTP-enabled projects:

dotnet test --coverlet

After the above command is run, coverage report files will be generated in the test results directory. By default, reports are generated in json and cobertura formats.

Additional Options (coverlet.MTP)

Option	Description
--coverlet	Enable code coverage data collection
--coverlet-output-format	Output format(s) for coverage report (json, lcov, opencover, cobertura)
--coverlet-include	Include assemblies matching filters (e.g., [Assembly]Type)
--coverlet-exclude	Exclude assemblies matching filters (e.g., [Assembly]Type)
--coverlet-include-test-assembly	Include test assembly in coverage

Example with options:

dotnet run --project <your-test-project> --coverlet --coverlet-output-format cobertura --coverlet-exclude "[xunit.]"

Requirements (coverlet.MTP)

• .NET 8.0 SDK or newer
• Test project configured for Microsoft Testing Platform

.NET Global Tool (guide, known issue)

Installation (coverlet.console)

dotnet tool install --global coverlet.console

Usage (coverlet.console)

The coverlet tool is invoked by specifying the path to the assembly that contains the unit tests. You also need to specify the test runner and the arguments to pass to the test runner using the --target and --targetargs options respectively. The invocation of the test runner with the supplied arguments must not involve a recompilation of the unit test assembly or no coverage result will be generated.

The following example shows how to use the familiar dotnet test toolchain:

coverlet /path/to/test-assembly.dll --target "dotnet" --targetargs "test /path/to/test-project --no-build"

Note: The --no-build flag is specified so that the /path/to/test-assembly.dll assembly isn't rebuilt

See documentation for advanced usage.

Requirements (coverlet.console)

• .NET global tools rely on a .NET Core runtime installed on your machine https://docs.microsoft.com/en-us/dotnet/core/tools/global-tools#what-could-go-wrong
• .NET Coverlet global tool requires .NET 8.0 or above

[!WARNING] coverlet.collector and coverlet.msbuild cannot be used with the Microsoft Testing Platform (MTP). This is especially relevant when using the native dotnet test integration introduced with .NET 10.

Both packages rely on the VSTest infrastructure, while the Microsoft Testing Platform uses a different test execution architecture, which makes these integrations incompatible. (Use Microsoft.Testing.Platform in the VSTest mode of dotnet test)

If your test project targets .NET 10.0, where the Microsoft Testing Platform is enabled by default, you need to disable TestingPlatformDotnetTestSupport:

 <PropertyGroup>
   <TestingPlatformDotnetTestSupport>false</TestingPlatformDotnetTestSupport>
 </PropertyGroup>

DataCollectors element

Microsoft.Testing.Platform is not using data collectors. Instead it has the concept of in-process and out-of-process extensions. Each extension is configured by its respective configuration file or through the command line.

Most importantly hang and crash extension, and code coverage extension.

Instead, use the coverlet.MTP extension designed for Microsoft Testing Platform: The coverlet.MTP package provides the equivalent functionality of coverlet.collector but is implemented as a native extension for Microsoft Testing Platform.

VSTest Integration (guide, known issue)

Installation (coverlet.collector)

dotnet add package coverlet.collector

[!NOTE] You MUST add package only to test projects and if you create xunit test projects (dotnet new xunit) you will find the reference already present in csproj file because Coverlet is the default coverage tool for every .NET Core and >= .NET 8 applications, you've only to update to last version if needed. Add coverlet.collector OR coverlet.msbuild package in a test project.

Usage (coverlet.collector)

Coverlet is integrated into the Visual Studio Test Platform as a data collector. To get coverage simply run the following command:

dotnet test --collect:"XPlat Code Coverage"

After the above command is run, a coverage.cobertura.xml file containing the results will be published to the TestResults directory as an attachment.

See documentation for advanced usage.

Requirements (coverlet.collector)

• .NET 8.0 SDK is required (version 8.0.112 or higher)
• Microsoft.NET.Test.Sdk version 17.12.0 or higher

<PackageReference Include="Microsoft.NET.Test.Sdk" Version="17.12.0" />

MSBuild Integration (guide, known issue)

Installation (coverlet.msbuild)

dotnet add package coverlet.msbuild

N.B. Typically you MUST add package only to test projects. Do not add coverlet.msbuild and coverlet.collector package in a test project.

Usage (coverlet.msbuild)

Coverlet also integrates with the build system to run code coverage after tests. Enabling code coverage is as simple as setting the CollectCoverage property to true

dotnet test /p:CollectCoverage=true

After the above command is run, a coverage.json file containing the results will be generated in the root directory of the test project. A summary of the results will also be displayed in the terminal.

See documentation for advanced usage.

Requirements (coverlet.msbuild)

• .NET 8.0 SDK is required (version 8.0.112 or higher)
• .NET Framework that supports .NET Standard 2.0

How It Works

Coverlet generates code coverage information by going through the following process:

Before Tests Run

• Locates the unit test assembly and selects all the referenced assemblies that have PDBs.
• Instruments the selected assemblies by inserting code to record sequence point hits to a temporary file.

After Tests Run

• Restore the original non-instrumented assembly files.
• Read the recorded hits information from the temporary file.
• Generate the coverage result from the hits information and write it to a file.

Deterministic build support

Coverlet supports coverage for deterministic builds. The solution at the moment is not optimal and need a workaround. Take a look at documentation.

Are you in trouble with some feature? Check on examples

Experimental features

Coverlet exposes opt-in performance improvements that are not yet enabled by default. Each feature is controlled by an environment variable.
Setting a variable to 1 (or any non-empty value other than 0 / false) enables the feature.
When the variable is absent or falsy, Coverlet behaves exactly like the current stable release.

[!WARNING] Experimental features may change or be removed without notice. Please report any issues you find.

COVERLET_EXPERIMENTAL_AUTOPROP_BACKING_FIELD_CACHE

Scope: SkipInlineAssignedAutoProperty / auto-property backing-field detection
Default: disabled (original O(N) LINQ scan, identical to master)

When enabled, Coverlet caches the set of compiler-generated k__BackingField names per declaring type so the per-field scan is performed at most once per type rather than on every constructor instruction. This can measurably reduce instrumentation time for assemblies with many classes that use inline-initialised auto-properties.

Performance impact

Scenario	Without flag (default)	With flag enabled
Per-constructor instruction	O(N) LINQ scan over all fields of the declaring type	O(1) HashSet<string> lookup
First visit of a declaring type	O(N) scan	O(N) scan — result is cached
Subsequent visits of the same type	O(N) scan repeated for every instruction	O(1) lookup from cache
Memory overhead	None	One HashSet<string> per instrumented declaring type, held for the lifetime of the CecilSymbolHelper instance

[!NOTE] The benefit is most noticeable in large assemblies that contain many classes with multiple inline-initialised auto-properties (i.e. properties with a default value set directly in the declaration). For small assemblies or assemblies without auto-property initialisers the difference is negligible.

# Enable
$env:COVERLET_EXPERIMENTAL_AUTOPROP_BACKING_FIELD_CACHE = "1"

# Disable (restore default)
Remove-Item Env:COVERLET_EXPERIMENTAL_AUTOPROP_BACKING_FIELD_CACHE

Or set it as a persistent user/system environment variable before running dotnet test / coverlet:

# Linux / macOS
export COVERLET_EXPERIMENTAL_AUTOPROP_BACKING_FIELD_CACHE=1

# Windows (Command Prompt)
set COVERLET_EXPERIMENTAL_AUTOPROP_BACKING_FIELD_CACHE=1

Known Issues

Unfortunately we have some known issues

Cake Add-In

If you're using Cake Build for your build script you can use the Cake.Coverlet add-in to provide you extensions to dotnet test for passing Coverlet arguments in a strongly typed manner.

Visual Studio Add-In

If you want to visualize coverlet output inside Visual Studio while you code, you can use the following addins depending on your platform.

Windows

If you're using Visual Studio on Windows, you can use the Fine Code Coverage extension. Visualization is updated when you run unit tests inside Visual Studio.

Mac OS

If you're using Visual Studio for Mac, you can use the VSMac-CodeCoverage extension.

Consume nightly build

We offer nightly build of master for all packages. See the documentation

Issues & Contributions

If you find a bug or have a feature request, please report them at this repository's issues section. See the CONTRIBUTING GUIDE for details on building and contributing to this project.

Coverlet Team

Author and owner

• Toni Solarin-Sodara (Inactive)

Co-maintainers

• David Müller
• Bert
• Peter Liljenberg (Inactive)
• Marco Rossignoli (Inactive)

Code of Conduct

This project has adopted the code of conduct defined by the Contributor Covenant to clarify expected behavior in our community.

For more information, see the .NET Foundation Code of Conduct.

Credits

Part of the code is based on work done by OpenCover team https://github.com/OpenCover

License

This project is licensed under the MIT license. See the LICENSE file for more info.

Supported by the .NET Foundation