.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 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) |
| minimal | -v m | Clean summary, no test output |
| normal | -v n | Default, shows discovered tests |
| detailed | -v d | Shows more details |
| diagnostic | -v diag | Most verbose |
To see test output, use grep to filter out discovery messages (for xUnit):
dotnet test --no-build --logger "console;verbosity=detailed" 2>&1 | grep -v "Discovered \[execution\]"
Framework Differences
This skill focuses on xUnit. For MSTest or NUnit, filter property names differ:
| Property | xUnit | MSTest | NUnit |
|---|---|---|---|
| Method name | Name | Name | Name |
| Class name | ClassName | ClassName | ClassName |
| Category/Trait | Category | TestCategory | Category |
| Priority | - | Priority | Priority |
Progressive Disclosure
For advanced scenarios, load additional references:
- references/theory-parameter-filtering.md - Filtering xUnit Theory tests by parameter values (string, numeric, boolean, etc.)
- references/blame-mode.md - Debugging test crashes and hangs with
--blame - references/parallel-execution.md - Controlling parallel test execution
Load these references when:
- Working with xUnit Theory tests and need to filter by specific parameter values
- Tests are crashing or hanging unexpectedly
- Diagnosing test isolation issues
- Optimizing test run performance
When to Use This Skill
Invoke when the user needs to:
- Run targeted tests during development
- Filter tests by method or class name
- Filter xUnit Theory tests by specific parameter values (e.g., run only admin user test cases)
- Understand test output and filtering options
- Debug failing or hanging tests