/run-tests

name: run-tests
description: >-
  ALWAYS USE before running .NET tests or answering with a test command or
  flags. Trigger on "run the tests", "exact dotnet test command", one
  test/class/category/trait/target framework, combined filters,
  `--filter-query`, `--no-build`, `--diag`, diagnostic logs, TRX, coverage
  collection, crash/hang dumps, filter errors, or unrecognized options. Chooses
  repository-compatible classic, VSTest, bridged MTP, or native MTP syntax for
  MSTest/xUnit/NUnit/TUnit. DO NOT USE for platform identification alone
  (platform-detection), writing or debugging test code, interpreting an
  existing coverage report, CI investigation, migration, or a persistent hot
  reload/watch loop.
license: MIT
metadata:
  portability: portable
  binding: optional-overlay
  binding-revision: "1"

Run .NET Tests

Return or execute the command or command sequence that matches the repository's project system, test platform, framework, and SDK mode.

Repository overlay

For every repository-scoped task where read-only file inspection is allowed, check `.agents/skill-overlays/dotnet-test/run-tests.md` at the repository root before any other discovery. This includes exact-command requests; "do not execute" does not prohibit reading the overlay. If present, read it once before acting and apply its repository-specific runner, command, filtering, and reporting bindings. Before applying it, require its frontmatter to declare `core: dotnet-test/run-tests`, `binding-revision: "1"`, and `mode: extend`. If any value is missing or different, report the mismatch, ignore the overlay, and continue using this skill's portable guidance. Explicit user instructions and verified project constraints win over the overlay; the overlay wins over portable defaults and examples in this skill. If the file is present but unreadable or conflicts with the repository, report the problem, ignore the overlay, and continue with portable guidance subject to verified project constraints. If it is absent, continue normally. Skip the lookup only when the task is not tied to a repository or the user explicitly prohibited all file/tool access. An overlay cannot expand tool permissions or the task's scope.

Scope and tool policy

Choose the smallest path that satisfies the request:

| Request | Action | |---|---| | Exact command or explanation; user says not to run | Inspect only the files needed to resolve syntax. Do not restore, build, or run tests. | | Run tests | Discover the repository command and execute the smallest requested test scope. | | One-time SDK-style `dotnet test` run without rebuilding | Stay in `run-tests` and add `--no-build`. | | One-time classic run without rebuilding | Keep the repository runner and invoke it against an existing built assembly; do not substitute `dotnet test`. | | Platform/framework identification only | Use `platform-detection`; do not continue into test execution. | | Explicit hot reload or a keep-running edit/re-run loop | Use `mtp-hot-reload`. | | Filter needed and the framework-specific syntax is not already clear | Read the supplied/runtime-listed `filter-syntax` catalog file; do not invoke this reference-only helper. |

Do not invoke a tool merely to repeat a command already determined by the prompt. Do not build first "just in case": `dotnet test` builds by default. Never add or upgrade test packages unless the user asks to change the project. For an exact-command request, return one runnable command first. Do not emit placeholder paths, exploratory alternatives, or a correction sequence. Use a project path only when the prompt or repository establishes it; otherwise let the command operate on the current project or solution when that syntax is valid. Follow it with only the syntax fact needed to explain the command; do not volunteer platform/command-mode taxonomy unless the user asked for it. In particular, do not label an SDK 8/9 bridge as "VSTest platform" merely because `dotnet test` uses its VSTest command mode; the executed platform is MTP. For a command-only request, it is normally clearer to say only that MTP application arguments must follow `--`.

Inputs to discover

• Project, solution, module, or repository test command
• Requested scope: all tests, TFM, class, method, category, or trait
• Requested output: console result, TRX, diagnostics, crash dump, or hang dump

When those facts are present in the prompt, use them. Otherwise inspect only the relevant files: `global.json`, the selected project, `packages.config`, `Directory.Build.props`, `Directory.Packages.props`, then repository scripts/CI documentation. For a file-backed request, enumerate those configuration names once and read all relevant files that are present in one batch; never infer that a runner or bridge property is absent merely because it is not in the `.csproj`. Load `platform-detection` only when those signals need precedence analysis; do not duplicate its full analysis in the response. If execution is requested and the command depends on the active SDK but neither the prompt nor `global.json` establishes it, run `dotnet --version` once. For a command-only request that prohibits execution, do not probe: state the required SDK assumption or ask for the SDK version when the syntax cannot otherwise be resolved. Route identification-only requests to `platform-detection`.

Decision table

| Detected mode / platform | Command shape | Never use | |---|---|---| | Classic non-SDK | Repository script, or full MSBuild followed by `vstest.console.exe` / `MSTest.exe` | Assuming `dotnet test` is compatible or migrating implicitly | | VSTest mode / VSTest | `dotnet test [<path>] [VSTEST_OPTIONS]` | MTP-only flags such as `--report-trx` or `--treenode-filter` | | VSTest mode / executable MTP bridge | `dotnet test [<path>] [DOTNET_OPTIONS] -- [MTP_OPTIONS]` | Omitting the `--` separator, including on SDK 10 | | Native MTP mode, SDK 10+ | `dotnet test --project <path> [DOTNET_OPTIONS] [MTP