# Coverlet Commands Reference

## Coverlet Drivers Overview

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

| Driver | Package | Use Case |
|--------|---------|----------|
| Collector | `coverlet.collector` | VSTest integration via `--collect` |
| MSBuild | `coverlet.msbuild` | MSBuild property-driven coverage |
| Console | `coverlet.console` | Standalone CLI tool |

---

## Collector Driver (`coverlet.collector`)

### Installation

```bash
dotnet add <TEST_PROJECT>.csproj package coverlet.collector
```

### Basic Command

```bash
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

```bash
# 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
<?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

```bash
dotnet add <TEST_PROJECT>.csproj package coverlet.msbuild
```

### Basic Command

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

### Output Formats

```bash
# 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

```bash
# 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

| Property | Description | Default |
|----------|-------------|---------|
| `CollectCoverage` | Enable coverage collection | `false` |
| `CoverletOutputFormat` | Output format(s) | `json` |
| `CoverletOutput` | Output path | `./` |
| `Threshold` | Minimum coverage percentage | none |
| `ThresholdType` | `line`, `branch`, `method` | `line` |
| `ThresholdStat` | `minimum`, `total`, `average` | `minimum` |
| `ExcludeByFile` | Files to exclude | none |
| `ExcludeByAttribute` | Attributes to exclude | none |
| `Exclude` | Filter expressions | none |
| `Include` | Filter expressions | none |
| `IncludeDirectory` | Source directories | none |
| `UseSourceLink` | Use SourceLink URIs | `false` |
| `SingleHit` | Count hits as 0 or 1 | `false` |
| `IncludeTestAssembly` | Include test assembly | `false` |
| `SkipAutoProps` | Skip auto-properties | `false` |
| `DeterministicReport` | Deterministic output | `false` |
| `MergeWith` | Merge with existing file | none |

### Coverage Thresholds

```bash
# 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

```bash
# 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:

```xml
<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

```bash
# 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

```bash
# 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

```bash
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

| Argument | Description |
|----------|-------------|
| `--target` | Executable to run tests |
| `--targetargs` | Arguments for target executable |
| `--output` | Output path |
| `--format` | Output format(s) |
| `--threshold` | Minimum coverage |
| `--threshold-type` | `line`, `branch`, `method` |
| `--threshold-stat` | `minimum`, `total`, `average` |
| `--exclude` | Filter expressions |
| `--include` | Filter expressions |
| `--exclude-by-file` | File patterns to exclude |
| `--exclude-by-attribute` | Attributes to exclude |
| `--include-directory` | Source directories |
| `--use-source-link` | Use SourceLink |
| `--single-hit` | Count hits as 0 or 1 |
| `--include-test-assembly` | Include test assembly |
| `--skip-auto-props` | Skip auto-properties |
| `--merge-with` | Merge with existing file |
| `--verbosity` | `quiet`, `minimal`, `normal`, `detailed` |

---

## CI Integration Examples

### GitHub Actions

```yaml
- 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

```yaml
- 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

```yaml
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:

```bash
# 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:

```bash
dotnet add package coverlet.collector
```

MSBuild driver:

```bash
dotnet add package coverlet.msbuild
```

Console tool:

```bash
dotnet tool install --global coverlet.console
```

## Verify First

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

```bash
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:

```bash
dotnet test --collect:"XPlat Code Coverage"
```

MSBuild:

```bash
dotnet test /p:CollectCoverage=true
```

Console:

```bash
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](https://github.com/coverlet-coverage/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

| Pattern | Description |
|---------|-------------|
| `[*]*` | All types in all assemblies |
| `[MyApp]*` | All types in MyApp assembly |
| `[MyApp]MyApp.Services.*` | All types in Services namespace |
| `[*]MyApp.Models.User` | Specific type in any assembly |
| `[MyApp.?]*` | Assemblies matching MyApp.* |
| `[MyApp.*]*.Tests.*` | Test types in MyApp.* assemblies |

---

## Common Exclusion Patterns

### Generated Code

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

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

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

### Entity Framework Migrations

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

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

### Auto-Generated Properties

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

### Test Assemblies

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

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

### Third-Party Code

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

---

## Attribute-Based Exclusions

### Built-in .NET Attributes

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

### ExcludeFromCodeCoverage Attribute

Apply `[ExcludeFromCodeCoverage]` to types or members:

```csharp
using System.Diagnostics.CodeAnalysis;

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

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

Then exclude:

```bash
/p:ExcludeByAttribute="ExcludeFromCodeCoverage"
```

### Custom Exclusion Attributes

Define a custom attribute:

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

Apply and exclude:

```bash
/p:ExcludeByAttribute="ExcludeFromCoverageAttribute"
```

---

## File-Based Exclusions

### ExcludeByFile Patterns

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

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

### Common File Exclusions

| Pattern | Description |
|---------|-------------|
| `**/Migrations/*.cs` | EF Core migrations |
| `**/Generated/*.cs` | Generated code folders |
| `**/obj/**/*.cs` | Build output |
| `**/*.Designer.cs` | Designer files |
| `**/*.g.cs` | Source generators |
| `**/GlobalSuppressions.cs` | Analyzer suppressions |
| `**/AssemblyInfo.cs` | Assembly metadata |

---

## Include Patterns

### Limiting Coverage Scope

```bash
# 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:

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

---

## Combined Pattern Examples

### Typical Application Coverage

```bash
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
<?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

```xml
<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

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

### Blazor

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

### Worker Services

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

---

## Troubleshooting Patterns

### Verify Exclusions Work

Run with verbose output to see what is being excluded:

```bash
# Console tool
coverlet ... --verbosity detailed

# Check generated coverage file for excluded types
```

### Common Issues

| Issue | Solution |
|-------|----------|
| Pattern not matching | Check assembly name vs namespace |
| Wildcards not working | Ensure proper escaping in shell |
| Files still covered | Use absolute paths in ExcludeByFile |
| Attributes ignored | Check attribute full name |

### Debug Filter Expressions

Test patterns incrementally:

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

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

# Verify with coverage report
```