Dotnet Test

.NET Test Execution

Basic Test Commands

# Run all tests in solution
dotnet test

# Run tests in specific project
dotnet test tests/MyApp.Tests/MyApp.Tests.csproj

# Run without build (faster if already built)
dotnet test --no-build

# Run without restore
dotnet test --no-restore

Test Filtering

By Name

# Filter by fully qualified name (contains)
dotnet test --filter "FullyQualifiedName~OrderService"

# Filter by test name (exact match)
dotnet test --filter "Name=CreateOrder_ValidInput_ReturnsOrder"

# Filter by display name
dotnet test --filter "DisplayName~Create Order"

By Category/Trait

# Filter by trait (xUnit)
dotnet test --filter "Category=Unit"
dotnet test --filter "Category!=Integration"

# Multiple trait filters
dotnet test --filter "Category=Unit&Priority=High"
dotnet test --filter "Category=Unit|Category=Integration"

By Class/Namespace

# Filter by class name
dotnet test --filter "ClassName=OrderServiceTests"

# Filter by namespace
dotnet test --filter "FullyQualifiedName~MyApp.Tests.Services"

Complex Filters

# Combine with operators
# & (and), | (or), ! (not), ~ (contains), = (equals)

# Unit tests except slow ones
dotnet test --filter "Category=Unit&Category!=Slow"

# All tests in namespace containing "Order"
dotnet test --filter "FullyQualifiedName~Order&Category!=Integration"

Test Output

Verbosity Levels

# Quiet (minimal output)
dotnet test --verbosity quiet
dotnet test -v q

# Normal (default)
dotnet test --verbosity normal

# Detailed (shows all test names)
dotnet test --verbosity detailed
dotnet test -v d

# Diagnostic (maximum output)
dotnet test --verbosity diagnostic

Logger Options

# Console logger with verbosity
dotnet test --logger "console;verbosity=detailed"

# TRX (Visual Studio Test Results)
dotnet test --logger trx

# JUnit format (for CI systems)
dotnet test --logger "junit;LogFileName=results.xml"

# HTML report
dotnet test --logger "html;LogFileName=results.html"

# Multiple loggers
dotnet test --logger trx --logger "console;verbosity=detailed"

Results Directory

# Specify results output directory
dotnet test --results-directory ./TestResults

Code Coverage

Collect Coverage

# Basic coverage collection
dotnet test --collect:"XPlat Code Coverage"

# With Coverlet
dotnet test /p:CollectCoverage=true

# Coverlet with specific format
dotnet test /p:CollectCoverage=true /p:CoverletOutputFormat=cobertura

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

Coverage Thresholds

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

# Per-type thresholds
dotnet test /p:CollectCoverage=true /p:ThresholdType=line /p:Threshold=80

Coverage Reports

# Install report generator
dotnet tool install -g dotnet-reportgenerator-globaltool

# Generate HTML report
reportgenerator -reports:coverage.cobertura.xml -targetdir:coveragereport

Parallel Execution

# Control parallelism
dotnet test --parallel

# Limit parallel workers
dotnet test -- RunConfiguration.MaxCpuCount=4

# Disable parallel execution
dotnet test -- RunConfiguration.DisableParallelization=true

Test Timeouts

# Set test timeout (milliseconds)
dotnet test -- RunConfiguration.TestSessionTimeout=60000

// Per-test timeout (xUnit)
[Fact(Timeout = 5000)]
public void SlowTest() { }

// Per-test timeout (NUnit)
[Test, Timeout(5000)]
public void SlowTest() { }

Configuration Files

runsettings

<!-- test.runsettings -->
<?xml version="1.0" encoding="utf-8"?>
<RunSettings>
  <RunConfiguration>
    <MaxCpuCount>4</MaxCpuCount>
    <ResultsDirectory>./TestResults</ResultsDirectory>
    <TestSessionTimeout>600000</TestSessionTimeout>
  </RunConfiguration>
  <DataCollectionRunSettings>
    <DataCollectors>
      <DataCollector friendlyName="XPlat Code Coverage">
        <Configuration>
          <Format>cobertura</Format>
          <Exclude>[*]*.Migrations.*</Exclude>
        </Configuration>
      </DataCollector>
    </DataCollectors>
  </DataCollectionRunSettings>
</RunSettings>

# Use runsettings file
dotnet test --settings test.runsettings

Test Failure Analysis

Common Failure Patterns

Debugging Failed Tests

# Run single failing test with detailed output
dotnet test --filter "FullyQualifiedName~FailingTest" -v d

# Enable blame mode to catch hangs
dotnet test --blame

# Blame with hang detection
dotnet test --blame-hang --blame-hang-timeout 60s

Watch Mode

# Run tests on file changes
dotnet watch test

# Watch specific project
dotnet watch --project tests/MyApp.Tests test

# Watch with filter
dotnet watch test --filter "Category=Unit"

CI/CD Integration

Exit Codes

CI Examples

# Azure DevOps
- task: DotNetCoreCLI@2
  inputs:
    command: test
    arguments: '--configuration Release --logger trx'

# GitHub Actions
- run: dotnet test --configuration Release --logger "trx;LogFileName=test-results.trx"

See test-filtering.md for advanced filtering patterns.

Advanced Test Filtering

Filter Syntax

Operators

Properties

xUnit Traits

Defining Traits

public class OrderServiceTests
{
    [Fact]
    [Trait("Category", "Unit")]
    [Trait("Priority", "1")]
    public void CreateOrder_Valid_ReturnsOrder() { }

    [Fact]
    [Trait("Category", "Integration")]
    [Trait("Feature", "Orders")]
    public void CreateOrder_PersistsToDatabase() { }
}

Custom Trait Attributes

// Create reusable trait attribute
public class UnitTestAttribute : FactAttribute
{
    public UnitTestAttribute()
    {
        DisplayName = "Unit Test";
    }
}

[AttributeUsage(AttributeTargets.Method)]
public class CategoryAttribute : Attribute, ITraitAttribute
{
    public CategoryAttribute(string category) { }
}

// Usage
[UnitTest]
[Category("Orders")]
public void MyTest() { }

NUnit Categories

Defining Categories

[TestFixture]
public class OrderServiceTests
{
    [Test]
    [Category("Unit")]
    public void CreateOrder_Valid_ReturnsOrder() { }

    [Test]
    [Category("Integration")]
    [Category("Database")]
    public void CreateOrder_PersistsToDatabase() { }
}

Filter NUnit Tests

# Single category
dotnet test --filter "TestCategory=Unit"

# Exclude category
dotnet test --filter "TestCategory!=Integration"

MSTest Categories

Defining Categories

[TestClass]
public class OrderServiceTests
{
    [TestMethod]
    [TestCategory("Unit")]
    public void CreateOrder_Valid_ReturnsOrder() { }

    [TestMethod]
    [TestCategory("Integration")]
    [Priority(1)]
    public void CreateOrder_PersistsToDatabase() { }
}

Filter MSTest

# Category filter
dotnet test --filter "TestCategory=Unit"

# Priority filter
dotnet test --filter "Priority=1"

Common Filter Patterns

Development Workflow

# Run only unit tests (fast feedback)
dotnet test --filter "Category=Unit"

# Run smoke tests
dotnet test --filter "Category=Smoke"

# Run everything except slow tests
dotnet test --filter "Category!=Slow"

Feature-Based

# Run tests for specific feature
dotnet test --filter "FullyQualifiedName~Orders"

# Run tests for multiple features
dotnet test --filter "FullyQualifiedName~Orders|FullyQualifiedName~Payments"

CI Pipeline Stages

# Stage 1: Fast unit tests
dotnet test --filter "Category=Unit" --parallel

# Stage 2: Integration tests
dotnet test --filter "Category=Integration"

# Stage 3: E2E tests
dotnet test --filter "Category=E2E" -- RunConfiguration.DisableParallelization=true

Class-Based

# Run all tests in specific class
dotnet test --filter "ClassName=OrderServiceTests"

# Run tests in multiple classes
dotnet test --filter "ClassName=OrderServiceTests|ClassName=PaymentServiceTests"

Excluding Tests

# Exclude integration tests
dotnet test --filter "Category!=Integration"

# Exclude multiple categories
dotnet test --filter "Category!=Integration&Category!=E2E"

# Exclude by namespace
dotnet test --filter "FullyQualifiedName!~Integration"

Project-Level Filtering

xunit.runner.json

{
  "$schema": "https://xunit.net/schema/current/xunit.runner.schema.json",
  "parallelizeAssembly": false,
  "parallelizeTestCollections": true,
  "maxParallelThreads": 4
}

.runsettings Filter

<RunSettings>
  <RunConfiguration>
    <TestCaseFilter>Category=Unit</TestCaseFilter>
  </RunConfiguration>
</RunSettings>

Complex Filter Examples

# Unit tests for Orders feature, excluding slow ones
dotnet test --filter "(Category=Unit&FullyQualifiedName~Orders)&Category!=Slow"

# High priority tests across multiple categories
dotnet test --filter "Priority=1&(Category=Unit|Category=Integration)"

# Specific namespace, specific category
dotnet test --filter "FullyQualifiedName~MyApp.Tests.Services&Category=Unit"

# Everything except database tests in CI
dotnet test --filter "Category!=Database&Category!=E2E"

Tips

1. Quote filters with special characters

   dotnet test --filter "FullyQualifiedName~MyApp.Tests"

2. Escape pipe on Unix

   dotnet test --filter "Category=Unit\|Category=Fast"

3. Use contains (~) over equals (=) for flexibility

   dotnet test --filter "FullyQualifiedName~Service"  # More flexible

4. Combine with verbosity for debugging filters

   dotnet test --filter "Category=Unit" -v d  # See which tests match