Run .NET Tests
Detect the test platform and framework, run tests, and apply filters using
.
When to Use
- User wants to run tests in a .NET project
- User needs to run a subset of tests using filters
- User needs help detecting which test platform (VSTest vs MTP) or framework is in use
- User wants to understand the correct filter syntax for their setup
When Not to Use
- User needs to write or generate test code (use general coding assistance)
- User needs CI/CD pipeline configuration (use CI-specific skills)
- User needs to debug a test (use debugging skills)
Inputs
| Input | Required | Description |
|---|
| Project or solution path | No | Path to the test project (.csproj) or solution (.sln). Defaults to current directory. |
| Filter expression | No | Filter expression to select specific tests |
| Target framework | No | Target framework moniker to run against (e.g., ) |
Workflow
Quick Reference
| Platform | SDK | Command pattern |
|---|
| VSTest | Any | dotnet test [<path>] [--filter <expr>] [--logger trx]
|
| MTP | 8 or 9 | dotnet test [<path>] -- <MTP_ARGS>
|
| MTP | 10+ | dotnet test --project <path> <MTP_ARGS>
|
Detection files to always check (in order):
→
→
→
Step 1: Detect the test platform and framework
Determine which test platform (VSTest or Microsoft.Testing.Platform) and which test framework (MSTest, xUnit, NUnit, TUnit) the project uses.
Detecting the test framework
Read the
file
and /
(for centrally managed dependencies) and look for:
| Package or SDK reference | Framework |
|---|
| (metapackage, recommended) or | MSTest |
| + | MSTest (also valid for v3/v4) |
| , , , , , | xUnit |
| + | NUnit |
| TUnit (MTP only) |
Detecting the test platform
The detection logic depends on the .NET SDK version. Run
to determine it.
.NET SDK 10+
On .NET 10+, the
setting is the
authoritative source:
- If contains
"test": { "runner": "Microsoft.Testing.Platform" }
- If has , or no section exists → VSTest
Important: On .NET 10+,
<TestingPlatformDotnetTestSupport>
alone does
not switch to MTP. The
runner setting takes precedence. If the runner is VSTest (or unset), the project uses VSTest regardless of
TestingPlatformDotnetTestSupport
.
.NET SDK 8 or 9
On older SDKs, check these signals in priority order:
1. Check the <TestingPlatformDotnetTestSupport>
Look in the
,
,
and . If set to
in
any of these files, the project uses
MTP.
Critical: Always read
and
if they exist. MTP properties are frequently set there instead of in the
, so checking only the project file will miss them.
2. Check project-level signals:
| Signal | Platform |
|---|
| as project SDK | MTP by default |
<UseMicrosoftTestingPlatformRunner>true</UseMicrosoftTestingPlatformRunner>
| MTP runner (xUnit) |
<EnableMSTestRunner>true</EnableMSTestRunner>
| MTP runner (MSTest) |
<EnableNUnitRunner>true</EnableNUnitRunner>
| MTP runner (NUnit) |
Microsoft.Testing.Platform
| MTP |
| package referenced | MTP (TUnit is MTP-only) |
Note: The presence of
does
not necessarily mean VSTest. Some frameworks (e.g., MSTest) pull it in transitively for compatibility, even when MTP is enabled. Do not use this package as a signal on its own — always check the MTP signals above first.
Key distinction: VSTest is the classic platform that uses
under the hood. Microsoft.Testing.Platform (MTP) is the newer, faster platform. Both can be invoked via
, but their filter syntax and CLI options differ.
Step 2: Run tests
VSTest (any .NET SDK version)
bash
dotnet test [<PROJECT> | <SOLUTION> | <DIRECTORY> | <DLL> | <EXE>]
Common flags:
| Flag | Description |
|---|
| Target a specific framework in multi-TFM projects (e.g., ) |
| Skip build, use previously built output |
| Run selected tests (see Step 3) |
| Generate TRX results file |
--collect "Code Coverage"
| Collect code coverage using Microsoft Code Coverage (built-in, always available) |
| Enable blame mode to detect tests that crash the host |
| Collect a crash dump when the test host crashes |
--blame-hang-timeout <duration>
| Abort test if it hangs longer than duration (e.g., ) |
| Verbosity: , , , , |
MTP with .NET SDK 8 or 9
With
<TestingPlatformDotnetTestSupport>true</TestingPlatformDotnetTestSupport>
,
bridges to MTP but uses VSTest-style argument parsing. MTP-specific arguments must be passed after
:
bash
dotnet test [<PROJECT> | <SOLUTION> | <DIRECTORY> | <DLL> | <EXE>] -- <MTP_ARGUMENTS>
MTP with .NET SDK 10+
With the
runner set to
Microsoft.Testing.Platform
,
natively understands MTP arguments without
:
bash
dotnet test
[--project <PROJECT_OR_DIRECTORY>]
[--solution <SOLUTION_OR_DIRECTORY>]
[--test-modules <EXPRESSION>]
[<MTP_ARGUMENTS>]
Examples:
bash
# Run all tests in a project
dotnet test --project path/to/MyTests.csproj
# Run all tests in a directory containing a project
dotnet test --project path/to/
# Run all tests in a solution (sln, slnf, slnx)
dotnet test --solution path/to/MySolution.sln
# Run all tests in a directory containing a solution
dotnet test --solution path/to/
# Run with MTP flags
dotnet test --project path/to/MyTests.csproj --report-trx --blame-hang-timeout 5min
Note: The .NET 10+
syntax does
not accept a bare positional argument like the VSTest syntax. Use
,
, or
to specify the target.
Common MTP flags
These flags apply to MTP on both SDK versions. On SDK 8/9, pass after
; on SDK 10+, pass directly.
Built-in flags (always available):
| Flag | Description |
|---|
| Skip build, use previously built output |
| Target a specific framework in multi-TFM projects |
| Enable diagnostic logging for the test platform |
--diagnostic-output-directory <DIR>
| Directory for diagnostic log output |
Extension-dependent flags (require the corresponding extension package to be registered):
| Flag | Requires | Description |
|---|
| Framework-specific (not all frameworks support this) | Run selected tests (see Step 3) |
| Microsoft.Testing.Extensions.TrxReport
| Generate TRX results file |
--report-trx-filename <FILE>
| Microsoft.Testing.Extensions.TrxReport
| Set TRX output filename |
--blame-hang-timeout <duration>
| Microsoft.Testing.Extensions.HangDump
| Abort test if it hangs longer than duration (e.g., ) |
| Microsoft.Testing.Extensions.CrashDump
| Collect a crash dump when the test host crashes |
| Microsoft.Testing.Extensions.CodeCoverage
| Collect code coverage using Microsoft Code Coverage |
Some frameworks (e.g., MSTest) bundle common extensions by default. Others may require explicit package references. If a flag is not recognized, check that the corresponding extension package is referenced in the project.
Alternative MTP invocations
MTP test projects are standalone executables. Beyond
, they can be run directly:
bash
# Build and run
dotnet run --project <PROJECT_PATH>
# Run a previously built DLL
dotnet exec <PATH_TO_DLL>
# Run the executable directly (Windows)
<PATH_TO_EXE>
These alternative invocations accept MTP command line arguments directly (no
separator needed).
Step 3: Run filtered tests
The filter syntax depends on the platform and test framework.
VSTest filters (MSTest, xUnit, NUnit on VSTest)
bash
dotnet test --filter <EXPRESSION>
Expression syntax:
<Property><Operator><Value>[|&<Expression>]
Operators:
| Operator | Meaning |
|---|
| Exact match |
| Not exact match |
| Contains |
| Does not contain |
Combinators: (OR),
(AND). Parentheses for grouping:
Supported properties by framework:
| Framework | Properties |
|---|
| MSTest | , , , , |
| xUnit | , , |
| NUnit | , , , |
An expression without an operator is treated as
FullyQualifiedName~<value>
.
Examples (VSTest):
bash
# Run tests whose name contains "LoginTest"
dotnet test --filter "Name~LoginTest"
# Run a specific test class
dotnet test --filter "ClassName=MyNamespace.MyTestClass"
# Run tests in a category
dotnet test --filter "TestCategory=Integration"
# Exclude a category
dotnet test --filter "TestCategory!=Slow"
# Combine: class AND category
dotnet test --filter "ClassName=MyNamespace.MyTestClass&TestCategory=Unit"
# Either of two classes
dotnet test --filter "ClassName=MyNamespace.ClassA|ClassName=MyNamespace.ClassB"
MTP filters — MSTest and NUnit
MSTest and NUnit on MTP use the
same syntax as VSTest (same properties, operators, and combinators). The only difference is how the flag is passed:
bash
# .NET SDK 8/9 (after --)
dotnet test -- --filter "Name~LoginTest"
# .NET SDK 10+ (direct)
dotnet test --filter "Name~LoginTest"
MTP filters — xUnit (v3)
xUnit v3 on MTP uses
framework-specific filter flags instead of the generic
expression:
| Flag | Description |
|---|
| Run all tests in a given class |
--filter-not-class "name"
| Exclude all tests in a given class |
| Run a specific test method |
--filter-not-method "name"
| Exclude a specific test method |
--filter-namespace "name"
| Run all tests in a namespace |
--filter-not-namespace "name"
| Exclude all tests in a namespace |
--filter-trait "name=value"
| Run tests with a matching trait |
--filter-not-trait "name=value"
| Exclude tests with a matching trait |
Multiple values can be specified with a single flag:
.
bash
# .NET SDK 8/9
dotnet test -- --filter-class "MyNamespace.LoginTests"
# .NET SDK 10+
dotnet test --filter-class "MyNamespace.LoginTests"
# Combine: namespace + trait
dotnet test --filter-namespace "MyApp.Tests.Integration" --filter-trait "Category=Smoke"
MTP filters — TUnit
TUnit uses
with a path-based syntax:
--treenode-filter "/<Assembly>/<Namespace>/<ClassName>/<TestName>"
Wildcards (
) are supported in any segment. Filter operators can be appended to test names for property-based filtering.
| Operator | Meaning |
|---|
| Wildcard match |
| Exact property match (e.g., ) |
| Exclude property value |
| AND (combine conditions) |
| OR (within a segment, requires parentheses) |
Examples (TUnit):
bash
# All tests in a class
dotnet run --treenode-filter "/*/*/LoginTests/*"
# A specific test
dotnet run --treenode-filter "/*/*/*/AcceptCookiesTest"
# By namespace prefix (wildcard)
dotnet run --treenode-filter "/*/MyProject.Tests.Api*/*/*"
# By custom property
dotnet run --treenode-filter "/*/*/*/*[Category=Smoke]"
# Exclude by property
dotnet run --treenode-filter "/*/*/*/*[Category!=Slow]"
# OR across classes
dotnet run --treenode-filter "/*/*/(LoginTests)|(SignupTests)/*"
# Combined: namespace + property
dotnet run --treenode-filter "/*/MyProject.Tests.Integration/*/*/*[Priority=Critical]"
Validation
Common Pitfalls
| Pitfall | Solution |
|---|
| Missing in a VSTest project | Tests won't be discovered. Add <PackageReference Include="Microsoft.NET.Test.Sdk" />
|
| Using VSTest syntax with xUnit v3 on MTP | xUnit v3 on MTP uses , , etc. — not the VSTest expression syntax |
| Passing MTP args without on .NET SDK 8/9 | Before .NET 10, MTP args must go after : dotnet test -- --report-trx
|
| Using for MTP args on .NET SDK 10+ | On .NET 10+, MTP args are passed directly: (using still works but is unnecessary) |
| Multi-TFM project runs tests for all frameworks | Use to target a specific framework |
| runner setting ignored | Requires .NET 10+ SDK. On older SDKs, use <TestingPlatformDotnetTestSupport>
|
| TUnit not recognized | TUnit is MTP-only and requires , not with VSTest |