Run Tests

Run .NET Tests

Detect the test platform and framework, run tests, and apply filters using dotnet test.

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 writing-mstest-tests for MSTest, or general coding assistance for other frameworks)
• User needs to migrate from VSTest to MTP (use migrate-vstest-to-mtp)
• User wants to iterate on failing tests without rebuilding (use mtp-hot-reload)
• User needs CI/CD pipeline configuration (use CI-specific skills)
• User needs to debug a test (use debugging skills)

Inputs

Critical Rules — Avoid Cross-Platform Mistakes

These are the most common agent mistakes. Internalize before proceeding:

Workflow

Quick Reference

Detection files to always check (in order): global.json -> .csproj -> Directory.Build.props -> Directory.Packages.props

If the prompt names a subset of tests (e.g., "integration tests", "smoke tests", a specific class, a specific TFM), plan to apply the matching filter / --framework in Step 3 — do not run the whole suite.

Step 1: Detect the test platform and framework

1. Run dotnet --version in the project directory to determine the SDK version. This accounts for global.json SDK pinning.
2. Read global.json — on .NET SDK 10+, "test": { "runner": "Microsoft.Testing.Platform" } is the authoritative MTP signal. If present, the project uses MTP and SDK 10+ syntax (no -- separator).
3. Read .csproj, Directory.Build.props, and Directory.Packages.props for framework packages and MTP properties. Always check all three files — MTP properties are frequently set in Directory.Build.props rather than individual .csproj files.
4. For full detection logic (SDK 8/9 signals, framework identification), see the platform-detection skill.

What to look for in each file:

Quick detection summary:

Step 2: Run tests

VSTest (any .NET SDK version)

dotnet test [<PROJECT> | <SOLUTION> | <DIRECTORY> | <DLL> | <EXE>]

Common flags:

MTP with .NET SDK 8 or 9

With <TestingPlatformDotnetTestSupport>true</TestingPlatformDotnetTestSupport>, dotnet test bridges to MTP but uses VSTest-style argument parsing. MTP-specific arguments must be passed after --:

dotnet test [<PROJECT> | <SOLUTION> | <DIRECTORY> | <DLL> | <EXE>] -- <MTP_ARGUMENTS>

MTP with .NET SDK 10+

With the global.json runner set to Microsoft.Testing.Platform, dotnet test natively understands MTP arguments without --:

dotnet test
    [--project <PROJECT_OR_DIRECTORY>]
    [--solution <SOLUTION_OR_DIRECTORY>]
    [--test-modules <EXPRESSION>]
    [<MTP_ARGUMENTS>]

Examples:

# 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
dotnet test --solution path/to/MySolution.slnf
dotnet test --solution path/to/MySolution.slnx

# 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+ dotnet test syntax does not accept a bare positional argument like the VSTest syntax. Use --project, --solution, or --test-modules 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.

Important: dotnet test/MSBuild flags such as --framework, --no-build, --configuration, and --verbosity are consumed by dotnet test itself (they drive restore/build/host selection) and always go BEFORE --, regardless of platform or SDK. Only MTP test-platform arguments go after -- on SDK 8/9. For example: dotnet test --framework net9.0 -- --report-trx (built-in flag before --, MTP extension flag after).

Built-in flags (always available):

Extension-dependent flags (require the corresponding extension package to be registered):

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 dotnet test, they can be run directly:

# 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

See the filter-syntax skill for the complete filter syntax for each platform and framework combination. Key points:

• VSTest (MSTest, xUnit v2, NUnit): dotnet test --filter <EXPRESSION> with =, !=, ~, !~ operators
• MTP -- MSTest and NUnit: Same --filter syntax as VSTest; pass after -- on SDK 8/9, directly on SDK 10+
• MTP -- xUnit v3: Uses --filter-class, --filter-method, --filter-trait (not VSTest expression syntax). For a single combined expression (e.g., a class-name pattern AND a trait), use --filter-query with the xUnit v3 query filter language: path segments /<assembly>/<namespace>/<class>/<method> with * wildcards and a [Trait=Value] qualifier — for example dotnet test -- --filter-query "/*/*/*IntegrationTests*/*[Category=Smoke]". See the filter-syntax skill for the full query language.
• MTP -- TUnit: Uses --treenode-filter with path-based syntax

When the user names a test category, trait, or group

When the prompt names a subset of tests by category (e.g., "integration tests", "unit tests", "smoke tests", "fast tests"), do not run all tests — translate the user's vocabulary into the platform-appropriate filter:

1. Inspect the test source files for filter-attribute annotations that match the named group:

   Framework	Attribute	Filter property
   MSTest	[TestCategory("Integration")]	TestCategory
   NUnit	[Category("Integration")]	TestCategory (mapped)
   xUnit v2	[Trait("Category", "Integration")]	Category
   xUnit v3	[Trait("Category", "Integration")]	Category (use --filter-trait)
   TUnit	[Category("Integration")]	Category

2. Build the filter expression and combine it with the platform-correct invocation. For "run the integration tests" against an MSTest project:

   Platform	SDK	Command
   VSTest (MSTest)	any	dotnet test --filter "TestCategory=Integration"
   MTP (MSTest)	8 or 9	dotnet test -- --filter "TestCategory=Integration"
   MTP (MSTest)	10+	dotnet test --filter "TestCategory=Integration"
   MTP (xUnit v3)	8 or 9	dotnet test -- --filter-trait "Category=Integration"
   MTP (xUnit v3)	10+	dotnet test --filter-trait "Category=Integration"
   MTP (TUnit)	8 or 9	dotnet test -- --treenode-filter "/*/*/*/*[Category=Integration]"

3. If you cannot find a matching attribute, ask the user to confirm the category name or fall back to a name-pattern filter (e.g., --filter "FullyQualifiedName~Integration").

Validation

• Test platform (VSTest or MTP) was correctly identified
• Test framework (MSTest, xUnit, NUnit, TUnit) was correctly identified
• Correct dotnet test invocation was used for the detected platform and SDK version
• When the user named a test category/trait/group, the appropriate filter was applied (not "run all tests")
• Filter expressions used the syntax appropriate for the platform and framework
• Test results were clearly reported to the user

Common Pitfalls

Troubleshooting

Common error messages and how to resolve them: