MTP Hot Reload for Iterative Test Fixing

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 changes.

Step 5: Iterate on the fix

1. Edit the source code (test code or production code) in your editor
2. The test host detects the changes and re-runs the affected tests automatically
3. Review the updated results in the console
4. Repeat until all targeted tests pass

> Important: Hot reload currently works in console mode only. There is no support for hot reload in Test Explorer for Visual Studio or Visual Studio Code.

#### Unsupported edits and rude edits

Method-signature changes, new types, and other unsupported edits cannot be applied to the active process. Never imply that the stale host picked them up.

For a directly launched MTP host:

1. Preserve the exact command, profile, environment, filter, and arguments that

started the current host.

1. Stop it with Ctrl+C.
2. Rebuild the same project: dotnet build <project-path>.
3. Rerun the same original host command. Do not replace an unknown existing

invocation with a generic dotnet run command.

If repeated unsupported edits are expected, offer a watch-managed restart fallback:

# PowerShell
$env:TESTINGPLATFORM_HOTRELOAD_ENABLED = "1"
$env:DOTNET_WATCH_RESTART_ON_RUDE_EDIT = "1"
dotnet watch --project <project-path> run -- <existing-MTP-arguments>

dotnet watch restarts the process when a rude edit cannot be applied. Without the auto-restart variable, accept the restart prompt or press Ctrl+R. Preserve any existing test filter after --. DOTNET_WATCH_RESTART_ON_RUDE_EDIT is a documented .NET SDK switch, not an MTP extension setting. When correctness may be questioned, cite the dotnet watch documentation and say that it makes the watcher restart instead of prompting. Never omit the original filter or replace the requested watch-managed fallback with a one-shot dotnet run.

Step 6: Finalize

Once all tests pass:

1. Stop the test host (Ctrl+C)
2. Use run-tests when the user requests an exact one-shot validation command,

flags, filter, TRX, or dump

1. Optionally remove TESTINGPLATFORM_HOTRELOAD_ENABLED from the environment or keep launchSettings.json for future use

Related skills