/run-tests

name: run-tests
description: >
  Recommend or run the exact `dotnet test` command. ALWAYS use when the
  user asks to run, filter, or troubleshoot .NET tests or wants the precise
  command, flags, or argument order — the right syntax depends on the test
  platform (VSTest vs Microsoft.Testing.Platform) and SDK version and is
  easy to get wrong from memory. USE FOR: running all tests or a subset (a
  specific class, category, or trait) via filters; a single framework in a
  multi-TFM project (`--framework`); TRX reports; crash or hang dumps;
  whether MTP args need the `--` separator (SDK 8/9) or pass directly
  (SDK 10+); diagnosing why `dotnet test` fails or uses wrong argument
  syntax. Detects the platform (VSTest vs MTP) and framework
  (MSTest/xUnit/NUnit/TUnit), then picks the matching command and filter
  flag (--filter, --filter-class, --filter-trait, --filter-query,
  --treenode-filter). DO NOT USE FOR: writing test code (use
  code-testing-agent), iterating on failing tests without rebuilding (use
  mtp-hot-reload), CI/CD config, or debugging test logic.
license: MIT

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

| Input | Required | Description | |-------|----------|-------------| | Project or solution path | No | Path to the test project (.csproj) or solution (.sln, .slnf, .slnx). Defaults to current directory. | | Filter expression | No | Filter expression to select specific tests | | Target framework | No | Target framework moniker to run against (e.g., `net8.0`) |

Critical Rules — Avoid Cross-Platform Mistakes

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

| Rule | Why | |------|-----| | **Do NOT use `--logger trx`** for MTP projects | MTP uses `--report-trx` (requires the TrxReport extension package) | | **Do NOT use `--report-trx`** for VSTest projects | VSTest uses `--logger trx` | | **Do NOT use `-- --arg`** on .NET SDK 10+ | SDK 10+ passes MTP args directly: `dotnet test --project . --report-trx` | | **Do NOT omit `--`** on .NET SDK 8/9 with MTP | SDK 8/9 requires the separator: `dotnet test -- --report-trx` | | **Do NOT use `--filter "ClassName=..."`** with xUnit v3 on MTP | xUnit v3 on MTP uses `--filter-class`, `--filter-method`, `--filter-trait` | | **Do NOT use bare positional path** on SDK 10+ | Use `--project <path>` or `--solution <path>` instead | | **Do NOT use `--blame`** for MTP projects | MTP uses `--blame-crash` and `--blame-hang-timeout` separately (each requires its extension package) | | **Do NOT use `--collect "Code Coverage"`** for MTP | MTP uses `--coverage` (requires the CodeCoverage extension package) |

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): `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](#step-3-run-filtered-tests) — 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:**

| File | Look for | Indicates | |------|----------|-----------| | `global.json` | `"test": { "runner": "Microsoft.Testing.Platform" }` | MTP on SDK 10+ | | `global.json` | `"sdk": { "version": "..." }` | SDK version (determines `--` separator behavior) | | `.csproj` | `<TestingPlatformDotnetTestSupport>true` | MTP on SDK 8/9 | | `.csproj` | `MSTest`, `xunit.v3`, `NUnit`, `TUnit` packages | Framework identity | | `.csproj` | `Microsoft.NET.Test.Sdk` + test adapter | VSTest (unless overridden by MTP signals above) | | `.csproj` | `<TargetFrameworks>` (plural) | Multi-TFM — may need `--framework` | | `Directory.Build.props` | `<TestingPlatformDotnetTestSupport>true` | MTP on SDK 8/9 (often set here, not in .csproj) | | `Directory.Packages.props` | Centrally managed test package versions | Framework identity for CPM repos |

**Quick detection summary:**

| Signal | Means | |--------|-------| | `global.json` has `"test": { "runner": "Microsoft.Testing.Platform" }` | **MTP on SDK 10+** — pass args directly, no `--` | | `<TestingPlatformDotnetTestSupport>true` in csproj or Directory.Build.props | **MTP on SDK 8/9** — pass arg