/dotnet-test

name: dotnet-test
description: This skill should be used when running .NET tests selectively with a build-first, test-targeted workflow. Use it for running tests with xUnit focus.
allowed-tools: Bash(dotnet build:*), Bash(dotnet test:*), Read, Grep, Glob

.NET Test Runner

Run .NET tests selectively using a build-first, test-targeted workflow optimized for development speed.

Core Workflow

Follow this workflow to run tests efficiently:

Step 1: Build Solution First

Build the entire solution with minimal output to catch compile errors early:

dotnet build -p:WarningLevel=0 /clp:ErrorsOnly --verbosity minimal

Step 2: Run Specific Project Tests

Run tests for the specific test project with `--no-build` to skip redundant compilation:

dotnet test path/to/project --no-build --verbosity minimal

Step 3: Filter When Targeting Specific Tests

Narrow down to specific tests using filter expressions:

# By method name using FullyQualifiedName (recommended)
dotnet test --no-build --filter "FullyQualifiedName~MyTestMethod"

# By class name using FullyQualifiedName (recommended)
dotnet test --no-build --filter "FullyQualifiedName~MyTestClass"

# By parameter values in Theory tests (xUnit)
dotnet test --no-build --filter "DisplayName~paramValue"

# Combined filters
dotnet test --no-build --filter "FullyQualifiedName~Create|FullyQualifiedName~Update"

**Note**: Properties `Name~` and `ClassName=` may not work reliably. Use `FullyQualifiedName~` instead.

Quick Reference

Commands

| Command | Purpose | | -------------------------------------------------------------------- | ------------------------------------ | | `dotnet build -p:WarningLevel=0 /clp:ErrorsOnly --verbosity minimal` | Build solution with minimal output | | `dotnet test path/to/Tests.csproj --no-build` | Run project tests (skip build) | | `dotnet test --no-build --logger "console;verbosity=detailed"` | Show ITestOutputHelper output | | `dotnet test --no-build --filter "..."` | Run filtered tests | | `dotnet test --no-build --list-tests` | List available tests without running |

Filter Operators

| Operator | Meaning | Example | | -------- | ---------------- | -------------------------------------------------------------- | | `=` | Exact match | `ClassName=MyTests` | | `!=` | Not equal | `Name!=SkipThis` | | `~` | Contains | `Name~Create` | | `!~` | Does not contain | `Name!~Integration` | | `\|` | OR | `Name~Test1\|Name~Test2` (note '\|' is an escape for markdown) | | `&` | AND | `Name~User&Category=Unit` |

xUnit Filter Properties

| Property | Description | Reliability | Example | | -------------------- | ---------------------------------------------- | ------------ | ------------------------------------------------------ | | `FullyQualifiedName` | Full test name with namespace | ✅ Reliable | `FullyQualifiedName~MyNamespace.MyClass` | | `DisplayName` | Test display name (includes Theory parameters) | ✅ Reliable | `DisplayName~My_Test_Name` or `DisplayName~paramValue` | | `Name` | Method name | ⚠️ Unreliable | Use `FullyQualifiedName~` instead | | `ClassName` | Class name | ⚠️ Unreliable | Use `FullyQualifiedName~` instead | | `Category` | Trait category | ✅ Reliable | `Category=Unit` |

**When to use DisplayName**: Essential for filtering Theory tests by their parameter values. xUnit includes all parameter values in the DisplayName (e.g., `MyTest(username: "admin", age: 30)`), making it ideal for running specific test cases. See [references/theory-parameter-filtering.md](references/theory-parameter-filtering.md) for detailed guidance.

Common Filter Patterns

# Run tests containing "Create" in method name
dotnet test --no-build --filter "FullyQualifiedName~Create"

# Run tests in a specific class
dotnet test --no-build --filter "FullyQualifiedName~UserServiceTests"

# Run tests matching namespace pattern
dotnet test --no-build --filter "FullyQualifiedName~MyApp.Tests.Unit"

# Run Theory tests with specific parameter value
dotnet test --no-build --filter "DisplayName~admin_user"

# Run tests with specific trait
dotnet test --no-build --filter "Category=Integration"

# Exclude slow tests
dotnet test --no-build --filter "Category!=Slow"

# Combined: class AND parameter value (Theory tests)
dotnet test --no-build --filter "FullyQualifiedName~OrderTests&DisplayName~USD"

# Multiple parameter values (OR condition)
dotnet test --no-build --filter "DisplayName~EUR|DisplayName~GBP"

ITestOutputHelper Output

To see output from xUnit's `ITestOutputHelper`, use the console logger with detailed verbosity:

dotnet test --no-build --logger "console;verbosity=detailed"

Reducing Output Noise

Verbosity levels for `dotnet test`:

| Level | Flag | Description | | ---------- | --------- | ------------------------------- | | quiet | `-v q` | Minimal output (pass/fail only) |