/mtp-hot-reload

name: mtp-hot-reload
description: >
  Set up or recover MTP hot reload for a long-lived console-host edit/re-run
  loop in a Microsoft Testing Platform project. Use for explicit MTP console
  requests such as "enable hot reload", "dotnet run to rerun on edit", or
  unsupported/rude edits. Covers setup, run/watch, restarts, filters, and the
  VSTest no-mutation fallback. For one-time runs, exact commands, filter
  errors, TRX/dumps, or merely a failing test, use run-tests. Do not use when
  Test Explorer or an IDE should rerun tests without an MTP console host.
  Excludes editor integration, CI, and writing/debugging tests.
license: MIT

MTP Hot Reload for Iterative Test Fixing

Set up and use a long-lived Microsoft Testing Platform host that applies code edits and automatically reruns tests.

When to Use

• User explicitly asks for test hot reload
• User wants a host to stay running and automatically rerun after repeated edits
• User needs to set up MTP hot reload in their project

When Not to Use

• User needs to write new tests from scratch (use general coding assistance)
• User needs to diagnose why a test is failing (use diagnostic skills)
• User asks about Visual Studio or VS Code Test Explorer hot reload or an IDE-integrated rerun experience (different feature, not MTP console-host hot reload)
• User asks whether the editor can auto-rerun affected tests after source edits without using an MTP console host
• User wants one normal run without rebuilding (use `run-tests`)
• User needs CI/CD pipeline configuration

Inputs

| Input | Required | Description | |-------|----------|-------------| | Test project path | No | Path to the test project (.csproj). Defaults to current directory. | | Failing test name or filter | No | Specific test(s) to iterate on |

Response sizing

• If setup is already complete and the user asks only which command to use,

return one `dotnet run --project <path>` command and one sentence explaining that it starts the persistent host. Do not repeat package, launch profile, or rude-edit guidance.

• If the package is already installed, show only the remaining enable-and-run

steps. Do not suggest reinstalling it or add optional persistence/recovery paths unless requested.

• For a named test, identify the framework and return one runnable command with

that framework's filter syntax. Never substitute MSTest/NUnit `--filter` for xUnit v3 `--filter-method` or TUnit `--treenode-filter`.

• A directly launched MTP host is itself the persistent watcher: `dotnet run`

stays alive and the HotReload extension reacts to edits. Do not replace it with `dotnet watch run` for the normal MTP path; reserve `dotnet watch` for the explicit restart fallback below.

Workflow

Step 1: Detect the platform before changing anything

Hot reload requires MTP. It does **not** work with VSTest.

Follow the complete evaluated-property procedure in the `platform-detection` skill. Read imported props and package versions as well as the project file. Do this before installing packages, editing files, or returning an MTP launch command.

**Hard stop for VSTest:** report that MTP hot reload is unavailable for the project as configured and stop the MTP setup path. Do not install the extension, create `launchSettings.json`, set the environment variable, change runner properties/packages, or return a `dotnet run` hot-reload command. Never turn a setup request into an implicit VSTest-to-MTP migration.

Offer one valid non-MTP fallback that preserves the project:

dotnet watch --project <project-path> test

This rebuilds and reruns the existing VSTest project when files change; it is not MTP hot reload. Offer an explicit migration as a separate option, but do not perform it unless the user asks. Exact one-shot test commands remain owned by `run-tests`.

Step 2: Add the hot reload NuGet package

First inspect the effective package references. If `Microsoft.Testing.Extensions.HotReload` is already installed, preserve its version and skip this step. Otherwise install it:

dotnet add <project-path> package Microsoft.Testing.Extensions.HotReload

> **Note**: When using `Microsoft.Testing.Platform.MSBuild` (included transitively by MSTest, NUnit, and xUnit runners), the extension is auto-registered when you install its NuGet package -- no code changes needed.

Step 3: Enable hot reload

Hot reload is activated by setting the `TESTINGPLATFORM_HOTRELOAD_ENABLED` environment variable to `1`.

**Option A -- Set it in the shell before running tests:**

# PowerShell
$env:TESTINGPLATFORM_HOTRELOAD_ENABLED = "1"

# bash/zsh
export TESTINGPLATFORM_HOTRELOAD_ENABLED=1

**Option B -- Add it to `launchSettings.json` (recommended for repeatable use):**

Create or update `Properties/launchSettings.json` in the test project:

{
  "profiles": {
    "<ProjectName>": {
      "commandName": "Project",
      "environmentVariables": {
        "TESTINGPLATFORM_HOTRELOAD_ENABLED": "1"
      }
    }
  }
}

Step 4: Run the tests with hot reload

Run the test project directly (not through `dotnet test`) to use hot reload in console mode:

dotnet run --project <project-path>

To filter to specific failing tests, pass the filter after `--`. Read the supplied or runtime-listed `filter-syntax` catalog file only when the examples below do not resolve the framework's syntax; do not invoke this reference-only helper. Quick examples:

| Framework | Filter syntax | |-----------|--------------| | MSTest | `dotnet run --project <path> -- --filter "FullyQualifiedName~TestMethodName"` | | NUnit | `dotnet run --project <path> -- --filter "FullyQualifiedName~TestMethodName"` | | xUnit v3 | `dotnet run --project <path> -- --filter-method "*TestMethodName"` | | TUnit | `dotnet run --project <path> -- --treenode-filter "/*/*/ClassName/TestMethodName"` |

The test host will start, run the tests, and **remain running** waiting for code