dotnet-test

# .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: ```bash 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: ```bash dotnet test path/to/project --no-build --verbosity minimal ``` ### Step 3: Filter When Targeting Specific Tests Narrow down to specific tests using filter expressions: ```bash # 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 ```bash # 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: ```bash 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): ```bash 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