coverlet.MTP 8.0.0

Coverlet Microsoft Testing Platform Integration

Microsoft.Testing.Platform and Microsoft Test Framework is a lightweight alternative for VSTest.

More information is available here:

• Microsoft.Testing.Platform overview
• Microsoft.Testing.Platform extensibility

coverlet.MTP implements coverlet.collector functionality for Microsoft.Testing.Platform.

Supported Runtime Versions

Since version 8.0.0:

• .NET Core >= 8.0

Quick Start

Installation

Add the coverlet.MTP package to your test project:

dotnet add package coverlet.MTP

ToDo: Usage details

A sample project file looks like:

<Project Sdk="Microsoft.NET.Sdk">
   <PropertyGroup>
      <TargetFramework>net8.0</TargetFramework>
      <OutputType>Exe</OutputType>
      
      <UseMicrosoftTestingPlatformRunner>true</UseMicrosoftTestingPlatformRunner>
      <TestingPlatformDotnetTestSupport>true</TestingPlatformDotnetTestSupport> 
   </PropertyGroup>
      <ItemGroup>
      
      <PackageReference Include="xunit.v3.mtp-v2" Version="3.2.1" />
      <PackageReference Include="Microsoft.Testing.Platform" Version="2.0.2" />
      <PackageReference Include="coverlet.MTP" Version="8.0.0" />
   </ItemGroup>
</Project>

Basic Usage

To collect code coverage, run your test executable with the --coverlet flag:

dotnet exec <test-assembly.dll> --coverlet

Or using dotnet test with MTP enabled projects:

dotnet test --coverlet

After the test run, a coverage.json file containing the results will be generated in the current directory.

Command Line Options

The coverlet.MTP extension provides the following command line options. To see all available options, run:

dotnet exec <test-assembly.dll> --help

Coverage Options

Examples

Generate coverage in JSON format (default):

dotnet exec TestProject.dll --coverlet

Generate coverage in Cobertura format:

dotnet exec TestProject.dll --coverlet --coverlet-output-format cobertura

Generate coverage in multiple formats:

dotnet run TestProject.dll --coverlet --coverlet-output-format json --coverlet-output-format cobertura --coverlet-output-format lcov

Include only specific assemblies:

dotnet exec TestProject.dll --coverlet --coverlet-include "[MyApp.]"

Exclude test assemblies and specific namespaces:

dotnet exec TestProject.dll --coverlet --coverlet-exclude "[.Tests]" --coverlet-exclude "[]MyApp.Generated."

Exclude by attribute:

dotnet exec TestProject.dll --coverlet --coverlet-exclude-by-attribute "Obsolete" --coverlet-exclude-by-attribute "GeneratedCode"

Coverage Output

Coverlet can generate coverage results in multiple formats:

• json (default) - Coverlet's native JSON format
• lcov - LCOV format
• opencover - OpenCover XML format
• cobertura - Cobertura XML format
• teamcity - TeamCity service messages

Filter Expressions

Filter expressions allow fine-grained control over what gets included or excluded from coverage.

Syntax: [Assembly-Filter]Type-Filter

Wildcards:

• * matches zero or more characters
• ? makes the prefixed character optional

Examples:

• [*]* - All types in all assemblies
• [coverlet.*]Coverlet.Core.Coverage - Specific class in matching assemblies
• [*]Coverlet.Core.Instrumentation.* - All types in a namespace
• [coverlet.*.tests?]* - Assemblies ending with .test or .tests

Both --coverlet-include and --coverlet-exclude can be used together, but --coverlet-exclude takes precedence.

Excluding From Coverage

Using Attributes

Apply the ExcludeFromCodeCoverage attribute from System.Diagnostics.CodeAnalysis to exclude methods or classes:

[ExcludeFromCodeCoverage] public class NotCovered { // This class will be excluded from coverage }

Additional attributes can be specified using --coverlet-exclude-by-attribute.

Using Source File Patterns

Exclude source files using glob patterns with --coverlet-exclude-by-file:

dotnet exec TestProject.dll --coverlet --coverlet-exclude-by-file "**/Generated/*.cs"

How It Works

The coverlet.MTP extension integrates with the Microsoft Testing Platform using the extensibility model:

1. Test Host Controller Extension: Implements ITestHostProcessLifetimeHandler to instrument assemblies before tests run and collect coverage after tests complete.

2. Before Tests Run:

   • Locates the test assembly and referenced assemblies with PDBs
   • Instruments assemblies by inserting code to record sequence point hits

3. After Tests Run:

   • Restores original non-instrumented assemblies
   • Reads recorded hit information
   • Generates coverage report in the specified format(s)

Comparison with coverlet.collector (VSTest)

Known Limitations

• Threshold validation is not yet supported (planned for future releases)
• Report merging is not yet supported (use external tools like dotnet-coverage or reportgenerator)

dotnet-coverage merge coverage/**/coverage.cobertura.xml -f cobertura -o coverage/merged.xml

reportgenerator -reports:"**/*.cobertura.xml" -targetdir:"coverage/report" -reporttypes:"HtmlInline_AzurePipelines_Dark;Cobertura"

Architecture

Coverlet.MTP uses a two-process architecture:

flowchart LR
    subgraph Controller["CONTROLLER PROCESS"]
        direction TB
        THC["builder.TestHostControllers"]
        PLH["AddProcessLifetimeHandler"]
        EVP["AddEnvironmentVariableProvider"]
        THC --> PLH
        THC --> EVP
    end

    subgraph TestHost["TEST HOST PROCESS"]
        direction TB
        TH["builder.TestHost"]
        TSLH["AddTestSessionLifetimeHandle"]
        DC["AddDataConsumer"]
        TALC["AddTestApplicationLifecycleCallbacks"]
        TH --> TSLH
        TH --> DC
        TH --> TALC
    end

    Controller -->|"Environment Variables<br/>Process Lifecycle Events"| TestHost

    style Controller fill:#e6f3ff,stroke:#0066cc,stroke-width:2px
    style TestHost fill:#e6ffe6,stroke:#009900,stroke-width:2px

And here's a sequence diagram showing the coverlet.MTP flow:

sequenceDiagram
    participant C as Controller Process<br/>(CoverletExtensionCollector)
    participant E as Environment Variables
    participant T as Test Host Process<br/>(CoverletInProcessHandler)

    Note over C: BeforeTestHostProcessStartAsync
    C->>C: Instrument assemblies
    C->>E: Set COVERLET_MTP_COVERAGE_ENABLED=true
    C->>E: Set COVERLET_MTP_COVERAGE_IDENTIFIER
    C->>E: Set COVERLET_MTP_HITS_FILE_PATH

    Note over C: OnTestHostProcessStartedAsync
    C->>T: Start test host process

    Note over T: Constructor
    T->>E: Read environment variables
    T->>T: Initialize handler

    Note over T: OnTestSessionStartingAsync
    T->>T: Tests execute...

    Note over T: OnTestSessionFinishingAsync
    T->>T: FlushCoverageData()
    T->>T: Call ModuleTrackerTemplate.UnloadModule

    Note over C: OnTestHostProcessExitedAsync
    C->>C: Read hit files
    C->>C: Generate coverage reports

Environment Variables

Troubleshooting

Enable Diagnostic Output

Use the MTP diagnostic options to get detailed logs:

dotnet exec TestProject.dll --coverlet --diagnostic --diagnostic-verbosity trace --diagnostic-output-directory ./logs

Debug Coverlet Extension

Set the environment variable to attach a debugger:

set COVERLET_MTP_DEBUG=1 dotnet exec TestProject.dll --coverlet

Debugging and Troubleshooting (not tested - just defined)

Enable Debugger Launch

To launch a debugger when coverlet.MTP initializes:

Windows:

set COVERLET_MTP_DEBUG=1

Linux/macOS:

export COVERLET_MTP_DEBUG=1

Wait for Debugger Attach

To make coverlet.MTP wait for a debugger to attach (Windows):

set COVERLET_MTP_DEBUG_WAIT=1

The extension will display:

[Coverlet.MTP] CoverletExtension: Waiting for debugger to attach... [Coverlet.MTP] Process Id: 12345, Name: dotnet

Use Visual Studio's "Debug > Attach to Process" (Ctrl+Alt+P) to attach.

Enable Tracker Logging

To collect detailed logs from the injected coverage tracker (Windows):

set COVERLET_ENABLETRACKERLOG=1

Log files will be created near the instrumented module location:

• moduleName.dll_tracker.txt - Main tracker log
• TrackersHitsLog/ folder - Detailed hit information

Enable Instrumentation Debugging

For detailed instrumentation diagnostics (Windows):

set COVERLET_MTP_INSTRUMENTATION_DEBUG=1

Enable Exception Logging

To capture detailed exception information (Windows):

set COVERLET_MTP_EXCEPTIONLOG_ENABLED=1

Using MTP Built-in Diagnostics

Microsoft Testing Platform provides built-in diagnostic logging (Windows):

dotnet test --diagnostic --diagnostic-verbosity Trace

This creates detailed logs in the TestResults directory.

Combined Debugging Example

Enable all debugging features (Windows)

set COVERLET_MTP_DEBUG_WAIT=1 set COVERLET_ENABLETRACKERLOG=1 set COVERLET_MTP_EXCEPTIONLOG_ENABLED=1

Run tests with MTP diagnostics

dotnet test --coverlet --diagnostic --diagnostic-verbosity Trace

Requirements

• .NET 8.0 SDK or newer
• Microsoft.Testing.Platform 2.0.0 or newer
• Test framework with MTP support (e.g., xUnit v3 (xunit.v3.mtp-v2), MSTest v3, NUnit with MTP adapter)

Related Documentation

• VSTest Integration - For VSTest-based projects using coverlet.collector
• MSBuild Integration - For MSBuild-based coverage collection
• Global Tool - For standalone coverage collection
• Known Issues - Common issues and workarounds