Coverlet

Coverlet for .NET

Trigger On

• the repo uses or wants coverlet
• CI needs line or branch coverage for .NET tests
• the team needs to choose between coverlet.collector, coverlet.msbuild, or coverlet.console

Value

• produce a concrete project delta: code, docs, config, tests, CI, or review artifact
• reduce ambiguity through explicit planning, verification, and final validation skills
• leave reusable project context so future tasks are faster and safer

Do Not Use For

• coverage report rendering by itself
• repos that intentionally use a different coverage engine

Inputs

• the nearest AGENTS.md
• active runner model: VSTest or Microsoft.Testing.Platform
• target test projects

Quick Start

1. Read the nearest AGENTS.md and confirm scope and constraints. 2. Run this skill's Workflow through the Ralph Loop until outcomes are acceptable. 3. Return the Required Result Format with concrete artifacts and verification evidence.

Workflow

1. Choose the driver deliberately:

• coverlet.collector for VSTest dotnet test --collect
• coverlet.msbuild for MSBuild property-driven runs
• coverlet.console for standalone scenarios

2. Add coverage packages only to test projects. 3. Do not mix coverlet.collector and coverlet.msbuild in the same test project. 4. Pair raw coverage collection with ReportGenerator only when humans need rendered reports.

Bootstrap When Missing

If coverage is not configured yet:

1. Detect current state:

• rg -n "coverlet\\.(collector|msbuild)|CollectCoverage|XPlat Code Coverage" -g '*.csproj' -g '*.props' -g '*.targets' .
• dotnet tool list --local
• dotnet tool list --global
• command -v coverlet

2. Install exactly one driver path:

• VSTest collector: dotnet add TEST_PROJECT.csproj package coverlet.collector
• MSBuild driver: dotnet add TEST_PROJECT.csproj package coverlet.msbuild
• Console tool: dotnet new tool-manifest (if missing) and dotnet tool install coverlet.console

3. Record one concrete local and CI command in AGENTS.md:

• collector: dotnet test TEST_PROJECT.csproj --collect:"XPlat Code Coverage"
• msbuild: dotnet test TEST_PROJECT.csproj /p:CollectCoverage=true /p:CoverletOutputFormat=cobertura
• console: dotnet tool run coverlet TEST_ASSEMBLY.dll --target "dotnet" --targetargs "test TEST_PROJECT.csproj --no-build"

4. Run the chosen command once and return status: configured or status: improved. 5. If another coverage engine already owns coverage for this repo, return status: not_applicable.

Deliver

• explicit coverage driver selection
• reproducible coverage commands for local and CI runs

Validate

• coverage driver matches the runner model
• coverage files are stable and consumable by downstream reporting

Ralph Loop

Use the Ralph Loop for every task, including docs, architecture, testing, and tooling work.

1. Plan first (mandatory):

• analyze current state
• define target outcome, constraints, and risks
• write a detailed execution plan
• list final validation skills to run at the end, with order and reason

2. Execute one planned step and produce a concrete delta. 3. Review the result and capture findings with actionable next fixes. 4. Apply fixes in small batches and rerun the relevant checks or review steps. 5. Update the plan after each iteration. 6. Repeat until outcomes are acceptable or only explicit exceptions remain. 7. If a dependency is missing, bootstrap it or return status: not_applicable with explicit reason and fallback path.

Required Result Format

• status: complete | clean | improved | configured | not_applicable | blocked
• plan: concise plan and current iteration step
• actions_taken: concrete changes made
• validation_skills: final skills run, or skipped with reasons
• verification: commands, checks, or review evidence summary
• remaining: top unresolved items or none

For setup-only requests with no execution, return status: configured and exact next commands.

Load References

• references/commands.md
• references/patterns.md
• references/coverlet.md

Example Requests

• "Add Coverlet to this .NET solution."
• "Choose the right Coverlet driver for CI."

Coverlet Commands Reference

Coverlet Drivers Overview

Coverlet provides three drivers for collecting code coverage. Choose exactly one per test project.

---

Collector Driver (coverlet.collector)

Installation

dotnet add <TEST_PROJECT>.csproj package coverlet.collector

Basic Command

dotnet test <TEST_PROJECT>.csproj --collect:"XPlat Code Coverage"

Output Location

Coverage files are written to TestResults/<guid>/coverage.cobertura.xml by default.

Common Options

# Specify output directory
dotnet test --collect:"XPlat Code Coverage" --results-directory ./coverage

# With runsettings file
dotnet test --collect:"XPlat Code Coverage" --settings coverlet.runsettings

Runsettings Configuration

Create coverlet.runsettings:

<?xml version="1.0" encoding="utf-8"?>
<RunSettings>
  <DataCollectionRunSettings>
    <DataCollectors>
      <DataCollector friendlyName="XPlat Code Coverage">
        <Configuration>
          <Format>cobertura,opencover</Format>
          <Exclude>[*]*.Generated.*</Exclude>
          <ExcludeByAttribute>Obsolete,GeneratedCodeAttribute,CompilerGeneratedAttribute</ExcludeByAttribute>
          <ExcludeByFile>**/Migrations/*.cs</ExcludeByFile>
          <IncludeDirectory>../src/*</IncludeDirectory>
          <SingleHit>false</SingleHit>
          <UseSourceLink>true</UseSourceLink>
          <IncludeTestAssembly>false</IncludeTestAssembly>
          <SkipAutoProps>true</SkipAutoProps>
          <DeterministicReport>true</DeterministicReport>
        </Configuration>
      </DataCollector>
    </DataCollectors>
  </DataCollectionRunSettings>
</RunSettings>

---

MSBuild Driver (coverlet.msbuild)

Installation

dotnet add <TEST_PROJECT>.csproj package coverlet.msbuild

Basic Command

dotnet test <TEST_PROJECT>.csproj /p:CollectCoverage=true

Output Formats

# Cobertura (default for CI)
dotnet test /p:CollectCoverage=true /p:CoverletOutputFormat=cobertura

# OpenCover format
dotnet test /p:CollectCoverage=true /p:CoverletOutputFormat=opencover

# Multiple formats
dotnet test /p:CollectCoverage=true /p:CoverletOutputFormat=\"opencover,cobertura\"

# JSON format
dotnet test /p:CollectCoverage=true /p:CoverletOutputFormat=json

# LCOV format
dotnet test /p:CollectCoverage=true /p:CoverletOutputFormat=lcov

Output Location

# Custom output file
dotnet test /p:CollectCoverage=true /p:CoverletOutput=./coverage/

# With specific filename
dotnet test /p:CollectCoverage=true /p:CoverletOutput=./coverage/coverage.xml

MSBuild Properties

Coverage Thresholds

# Fail if line coverage below 80%
dotnet test /p:CollectCoverage=true /p:Threshold=80

# Fail if branch coverage below 70%
dotnet test /p:CollectCoverage=true /p:Threshold=70 /p:ThresholdType=branch

# Multiple threshold types
dotnet test /p:CollectCoverage=true /p:Threshold=\"80,70,90\" /p:ThresholdType=\"line,branch,method\"

# Average instead of minimum
dotnet test /p:CollectCoverage=true /p:Threshold=80 /p:ThresholdStat=average

Merging Coverage

# Merge with existing coverage file
dotnet test /p:CollectCoverage=true /p:MergeWith="./coverage/previous.json"

# Typical multi-project merge workflow
dotnet test Project1.Tests.csproj /p:CollectCoverage=true /p:CoverletOutput=./coverage/
dotnet test Project2.Tests.csproj /p:CollectCoverage=true /p:CoverletOutput=./coverage/ /p:MergeWith="./coverage/coverage.json"

Directory.Build.props Configuration

Set defaults across all test projects:

<Project>
  <PropertyGroup Condition="'$(CollectCoverage)' == 'true'">
    <CoverletOutputFormat>cobertura</CoverletOutputFormat>
    <CoverletOutput>$(MSBuildThisFileDirectory)coverage/</CoverletOutput>
    <ExcludeByAttribute>Obsolete,GeneratedCodeAttribute,CompilerGeneratedAttribute,ExcludeFromCodeCoverage</ExcludeByAttribute>
    <ExcludeByFile>**/Migrations/*.cs</ExcludeByFile>
    <SkipAutoProps>true</SkipAutoProps>
    <DeterministicReport>true</DeterministicReport>
  </PropertyGroup>
</Project>

---

Console Tool (coverlet.console)

Installation

# As local tool (recommended)
dotnet new tool-manifest  # if not present
dotnet tool install coverlet.console

# As global tool
dotnet tool install --global coverlet.console

Basic Command

# Local tool
dotnet tool run coverlet <TEST_ASSEMBLY>.dll --target "dotnet" --targetargs "test <TEST_PROJECT>.csproj --no-build"

# Global tool
coverlet <TEST_ASSEMBLY>.dll --target "dotnet" --targetargs "test <TEST_PROJECT>.csproj --no-build"

Common Options

coverlet <TEST_ASSEMBLY>.dll \
  --target "dotnet" \
  --targetargs "test <TEST_PROJECT>.csproj --no-build" \
  --output ./coverage/ \
  --format cobertura \
  --exclude "[*]*.Migrations.*" \
  --exclude-by-attribute "Obsolete,GeneratedCode" \
  --threshold 80 \
  --threshold-type line

Console Tool Arguments

---

CI Integration Examples

GitHub Actions

- name: Run tests with coverage
  run: dotnet test --collect:"XPlat Code Coverage" --results-directory ./coverage

- name: Upload coverage
  uses: codecov/codecov-action@v4
  with:
    directory: ./coverage
    files: "**/*.cobertura.xml"

Azure Pipelines

- task: DotNetCoreCLI@2
  inputs:
    command: test
    arguments: '--collect:"XPlat Code Coverage" --results-directory $(Build.SourcesDirectory)/coverage'

- task: PublishCodeCoverageResults@2
  inputs:
    codeCoverageTool: Cobertura
    summaryFileLocation: '$(Build.SourcesDirectory)/coverage/**/coverage.cobertura.xml'

GitLab CI

test:
  script:
    - dotnet test --collect:"XPlat Code Coverage" --results-directory ./coverage
  artifacts:
    reports:
      coverage_report:
        coverage_format: cobertura
        path: coverage/**/coverage.cobertura.xml

---

ReportGenerator Integration

Generate HTML reports from coverage files:

# Install
dotnet tool install dotnet-reportgenerator-globaltool

# Generate HTML report
reportgenerator \
  -reports:"./coverage/**/coverage.cobertura.xml" \
  -targetdir:"./coverage/report" \
  -reporttypes:Html

# Multiple formats
reportgenerator \
  -reports:"./coverage/**/coverage.cobertura.xml" \
  -targetdir:"./coverage/report" \
  -reporttypes:"Html;Badges;TextSummary"

Coverlet

Open/Free Status

• open source
• free to use

Install

VSTest collector:

dotnet add package coverlet.collector

MSBuild driver:

dotnet add package coverlet.msbuild

Console tool:

dotnet tool install --global coverlet.console

Verify First

Before installing a coverage driver, check what the repo already uses:

rg -n "coverlet\\.(collector|msbuild)|CollectCoverage|XPlat Code Coverage" -g '*.csproj' -g '*.props' -g '*.targets' .
dotnet tool list --local
dotnet tool list --global
command -v coverlet

Common Usage

Collector:

dotnet test --collect:"XPlat Code Coverage"

MSBuild:

dotnet test /p:CollectCoverage=true

Console:

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

CI Fit

• add coverage packages only to test projects
• do not combine coverlet.collector and coverlet.msbuild in one test project
• render the resulting files with ReportGenerator if humans need HTML or Markdown output

When Not To Use

• when the repo already standardized on another coverage engine

Sources

• Coverlet

Coverlet Coverage Patterns Reference

Filter Expression Syntax

Coverlet uses filter expressions to include or exclude assemblies and types from coverage.

Basic Syntax

[<ASSEMBLY_FILTER>]<TYPE_FILTER>

• * matches any sequence of characters
• ? matches any single character
• Assembly filter is enclosed in []
• Type filter follows the assembly filter

Examples

---

Common Exclusion Patterns

Generated Code

# MSBuild
/p:Exclude="[*]*.Generated.*,[*]*.Designer.*,[*]*.g.cs"

# Runsettings
<Exclude>[*]*.Generated.*,[*]*.Designer.*</Exclude>

# Console
--exclude "[*]*.Generated.*" --exclude "[*]*.Designer.*"

Entity Framework Migrations

# By file path
/p:ExcludeByFile="**/Migrations/*.cs"

# By namespace
/p:Exclude="[*]*.Migrations.*"

Auto-Generated Properties

# Skip auto-properties (getters/setters)
/p:SkipAutoProps=true

Test Assemblies

# Exclude test projects from coverage
/p:Exclude="[*.Tests]*,[*.UnitTests]*,[*.IntegrationTests]*"

# Do not include test assembly itself
/p:IncludeTestAssembly=false

Third-Party Code

# Exclude specific vendor namespaces
/p:Exclude="[*]AutoMapper.*,[*]FluentValidation.*"

---

Attribute-Based Exclusions

Built-in .NET Attributes

/p:ExcludeByAttribute="Obsolete,GeneratedCodeAttribute,CompilerGeneratedAttribute"

ExcludeFromCodeCoverage Attribute

Apply [ExcludeFromCodeCoverage] to types or members:

using System.Diagnostics.CodeAnalysis;

[ExcludeFromCodeCoverage]
public class GeneratedDto
{
    public string Name { get; set; }
}

public class Service
{
    [ExcludeFromCodeCoverage]
    public void DebugOnlyMethod()
    {
        // Not covered
    }
}

Then exclude:

/p:ExcludeByAttribute="ExcludeFromCodeCoverage"

Custom Exclusion Attributes

Define a custom attribute:

[AttributeUsage(AttributeTargets.All)]
public sealed class ExcludeFromCoverageAttribute : Attribute { }

Apply and exclude:

/p:ExcludeByAttribute="ExcludeFromCoverageAttribute"

---

File-Based Exclusions

ExcludeByFile Patterns

# Single pattern
/p:ExcludeByFile="**/Migrations/*.cs"

# Multiple patterns
/p:ExcludeByFile="**/Migrations/*.cs,**/Generated/*.cs,**/obj/**/*.cs"

Common File Exclusions

---

Include Patterns

Limiting Coverage Scope

# Only specific assemblies
/p:Include="[MyApp.Core]*,[MyApp.Services]*"

# Only specific namespaces
/p:Include="[MyApp]*MyApp.Domain.*"

Source Directory Inclusion

For projects with source code in non-standard locations:

/p:IncludeDirectory="../src/*,../lib/*"

---

Combined Pattern Examples

Typical Application Coverage

dotnet test /p:CollectCoverage=true \
  /p:CoverletOutputFormat=cobertura \
  /p:Exclude="[*.Tests]*,[*.IntegrationTests]*,[*]*.Migrations.*,[*]*.Generated.*" \
  /p:ExcludeByAttribute="Obsolete,GeneratedCodeAttribute,CompilerGeneratedAttribute,ExcludeFromCodeCoverage" \
  /p:ExcludeByFile="**/Migrations/*.cs,**/*.Designer.cs" \
  /p:SkipAutoProps=true

Runsettings Example

<?xml version="1.0" encoding="utf-8"?>
<RunSettings>
  <DataCollectionRunSettings>
    <DataCollectors>
      <DataCollector friendlyName="XPlat Code Coverage">
        <Configuration>
          <Format>cobertura</Format>

          <!-- Assembly and type exclusions -->
          <Exclude>
            [*.Tests]*,
            [*.IntegrationTests]*,
            [*]*.Migrations.*,
            [*]*.Generated.*
          </Exclude>

          <!-- Attribute exclusions -->
          <ExcludeByAttribute>
            Obsolete,
            GeneratedCodeAttribute,
            CompilerGeneratedAttribute,
            ExcludeFromCodeCoverage
          </ExcludeByAttribute>

          <!-- File path exclusions -->
          <ExcludeByFile>
            **/Migrations/*.cs,
            **/*.Designer.cs,
            **/*.g.cs,
            **/GlobalSuppressions.cs
          </ExcludeByFile>

          <!-- Additional options -->
          <SkipAutoProps>true</SkipAutoProps>
          <DeterministicReport>true</DeterministicReport>
          <IncludeTestAssembly>false</IncludeTestAssembly>
        </Configuration>
      </DataCollector>
    </DataCollectors>
  </DataCollectionRunSettings>
</RunSettings>

Directory.Build.props Example

<Project>
  <PropertyGroup Condition="'$(CollectCoverage)' == 'true'">
    <CoverletOutputFormat>cobertura</CoverletOutputFormat>
    <CoverletOutput>$(MSBuildThisFileDirectory)coverage/</CoverletOutput>

    <!-- Exclusions -->
    <Exclude>[*.Tests]*,[*.IntegrationTests]*,[*]*.Migrations.*</Exclude>
    <ExcludeByAttribute>Obsolete,GeneratedCodeAttribute,CompilerGeneratedAttribute,ExcludeFromCodeCoverage</ExcludeByAttribute>
    <ExcludeByFile>**/Migrations/*.cs,**/*.Designer.cs</ExcludeByFile>

    <!-- Options -->
    <SkipAutoProps>true</SkipAutoProps>
    <DeterministicReport>true</DeterministicReport>
    <IncludeTestAssembly>false</IncludeTestAssembly>
  </PropertyGroup>
</Project>

---

Framework-Specific Patterns

ASP.NET Core

/p:Exclude="[*]*.Migrations.*,[*]Program,[*]Startup" \
/p:ExcludeByFile="**/Migrations/*.cs,**/wwwroot/**"

Blazor

/p:Exclude="[*]*.Migrations.*,[*]App,[*]*.razor.g.cs" \
/p:ExcludeByFile="**/*.razor.g.cs,**/*.razor.css.g.cs"

Worker Services

/p:Exclude="[*]Program,[*]*.Worker" \
/p:ExcludeByAttribute="ExcludeFromCodeCoverage"

---

Troubleshooting Patterns

Verify Exclusions Work

Run with verbose output to see what is being excluded:

# Console tool
coverlet ... --verbosity detailed

# Check generated coverage file for excluded types

Common Issues

Debug Filter Expressions

Test patterns incrementally:

# Start broad
/p:Exclude="[*]*"  # Excludes everything

# Narrow down
/p:Exclude="[MyApp.Tests]*"  # Exclude specific assembly

# Verify with coverage report