👁 Image
coverlet.collector 10.0.1

Coverlet integration with VSTest (a.k.a. Visual Studio Test Platform)

Supported runtime versions:

Since version 8.0.0

• .NET Core >= 8.0
• .NET Framework >= 4.7.2

As explained in quick start section, to use collectors you need to run SDK v8.0.414 (LTS) or newer and your project file must reference coverlet.collector and a minimum version of Microsoft.NET.Test.Sdk.

A sample project file looks like:

<Project Sdk="Microsoft.NET.Sdk">
 
 <PropertyGroup>
 <TargetFrameworks>net8.0;net9.0</TargetFrameworks>
 <TestingPlatformDotnetTestSupport>false</TestingPlatformDotnetTestSupport>
 </PropertyGroup>
 <ItemGroup>
 
 <PackageReference Include="Microsoft.NET.Test.Sdk" Version="18.4.0" />
 
 <PackageReference Include="coverlet.collector" Version="10.0.1" />
 ...
 </ItemGroup>
...
</Project>

The reference to coverlet.collector package is included by default with xunit template test (dotnet new xunit), you only need to update the package for new versions like any other package reference.

With correct reference in place you can run coverage through default dotnet test CLI verbs:

dotnet test --collect:"XPlat Code Coverage"

or

dotnet publish
...
 ... -> C:\project\bin\Debug\net8.0\testdll.dll
 ... -> C:\project\bin\Debug\net8.0\publish\
...
dotnet vstest C:\project\bin\Debug\net8.0\publish\testdll.dll --collect:"XPlat Code Coverage"

As you can see in case of vstest verb you must publish project before.

At the end of tests you'll find the coverage file data under default VSTest platform directory TestResults

Attachments:
 C:\git\coverlet\Documentation\Examples\VSTest\HelloWorld\XUnitTestProject1\TestResults\bc5e983b-d7a8-4f17-8c0a-8a8831a4a891\coverage.cobertura.xml
Test Run Successful.
Total tests: 1
 Passed: 1
 Total time: 2.5451 Seconds

You can change the output directory using the standard dotnet test switch --results-directory

Coverlet options supported by VSTest integration

⚠️At the moment VSTest integration doesn't support all features of msbuild and .NET tool, for instance show result on console, report merging and threshold validation. We're working to fill the gaps.

Default option (if you don't specify a runsettings file)

Without specifying a runsettings file and calling coverlet by just the name of the collector, the result of the generated coverage output is by default in cobertura format.

dotnet test --collect:"XPlat Code Coverage"

The output format of the coverage report can also be changed without a runsettings file by specifying it in a parameter. The supported formats are lcov, opencover, cobertura, teamcity, json (default coverlet proprietary format).

dotnet test --collect:"XPlat Code Coverage;Format=json"

It is even possible to specify the coverage output in multiple formats.

dotnet test --collect:"XPlat Code Coverage;Format=json,lcov,cobertura"

Advanced Options (Supported via runsettings)

These are a list of options that are supported by coverlet. These can be specified as datacollector configurations in the runsettings.

How to specify these options via runsettings?

<?xml version="1.0" encoding="utf-8" ?>
<RunSettings>
 <DataCollectionRunSettings>
 <DataCollectors>
 <DataCollector friendlyName="XPlat code coverage">
 <Configuration>
 <Format>json,cobertura,lcov,teamcity,opencover</Format>
 <Exclude>[coverlet.*.tests?]*,[*]Coverlet.Core*</Exclude> 
 <Include>[coverlet.*]*,[*]Coverlet.Core*</Include> 
 <ExcludeByAttribute>Obsolete,GeneratedCodeAttribute,CompilerGeneratedAttribute</ExcludeByAttribute>
 <ExcludeByFile>**/dir1/class1.cs,**/dir2/*.cs,**/dir3/**/*.cs,</ExcludeByFile> 
 <IncludeDirectory>../dir1/,../dir2/,</IncludeDirectory>
 <SingleHit>false</SingleHit>
 <UseSourceLink>true</UseSourceLink>
 <IncludeTestAssembly>true</IncludeTestAssembly>
 <SkipAutoProps>true</SkipAutoProps>
 <DeterministicReport>false</DeterministicReport>
 <ExcludeAssembliesWithoutSources>MissingAll,MissingAny,None</ExcludeAssembliesWithoutSources>
 </Configuration>
 </DataCollector>
 </DataCollectors>
 </DataCollectionRunSettings>
</RunSettings>

Filtering details are present on .

This runsettings file can easily be provided using command line option as given :

• dotnet test --collect:"XPlat Code Coverage" --settings coverlet.runsettings
• dotnet vstest C:\project\bin\Debug\netcoreapp3.0\publish\testdll.dll --collect:"XPlat Code Coverage" --settings coverlet.runsettings

Take a look at our sample.

Passing runsettings arguments through commandline

You can avoid passing a runsettings file to dotnet test driver by using the xml flat syntax in the command line.

For instance if you want to set the Format element as a runsettings option you can use this syntax:

dotnet test --collect:"XPlat Code Coverage" -- DataCollectionRunSettings.DataCollectors.DataCollector.Configuration.Format=json,cobertura,lcov,teamcity,opencover

Take a look here for further information:https://github.com/microsoft/vstest/blob/main/docs/RunSettingsArguments.md

How it works

Coverlet integration is implemented with the help of datacollectors. When we specify --collect:"XPlat Code Coverage" VSTest platform tries to load coverlet collectors inside coverlet.collector.dll

1. Out-of-proc Datacollector: The outproc collector run in a separate process(datacollector.exe/datacollector.dll) than the process in which tests are being executed(testhost*.exe/testhost.dll). This datacollector is responsible for calling into Coverlet APIs for instrumenting dlls, collecting coverage results and sending the coverage output file back to test platform.

2. In-proc Datacollector: The in-proc collector is loaded in the testhost process executing the tests. This collector will be needed to remove the dependency on the process exit handler to flush the hit files and avoid to hit this

Architecture

coverlet.collector uses a controller-style integration where VSTest remains the orchestrator and Coverlet hooks into collector lifecycle callbacks.

Dependencies and functionality

flowchart LR
 VS["vstest.console / dotnet test"] --> OOP["Out-of-proc Data Collector\ncoverlet.collector"]
 VS --> TH["testhost"]
 TH --> IP["In-proc Data Collector\ncoverlet.collector"]
 OOP --> CORE["coverlet.core"]
 IP --> CORE
 CORE --> REP["coverage reports"]
 OOP --> ATT["VSTest attachments\nTestResults/<guid>"]

Limitations and constraints

• Output files are attached under TestResults/<guid> (platform-controlled, non-deterministic folder names).
• Feature parity with other modes is partial (for example, threshold validation and built-in merge are not provided by this integration mode).
• Coverage collection depends on VSTest data-collector lifecycle and testhost behavior.
• Requires compatible Microsoft.NET.Test.Sdk and collector setup.

Known Issues

For a comprehensive list of known issues check the detailed documentation