--- name: dotnet/migrate-vstest-to-mtp source: https://app.decimal.ai/s/dotnet-migrate-vstest-to-mtp@1/SKILL.md source_sha256: 8935a091cff0 --- # VSTest -> Microsoft.Testing.Platform Migration Migrate a .NET test solution from VSTest to Microsoft.Testing.Platform (MTP). The outcome is a solution where all test projects run on MTP, `dotnet test` works correctly, and CI/CD pipelines are updated. > **Important**: Do not mix VSTest-based and MTP-based .NET test projects in the same solution or run configuration -- this is an unsupported scenario. ## When to Use - Switching from VSTest to Microsoft.Testing.Platform for any supported test framework - Enabling `dotnet run` / `dotnet watch` / direct executable execution for test projects - Enabling Native AOT or trimmed test execution - Replacing `vstest.console.exe` with `dotnet test` on MTP - Updating CI/CD pipelines from the VSTest task to the .NET Core CLI task - Updating `dotnet test` arguments from VSTest syntax to MTP syntax ## When Not to Use - The project already runs on Microsoft.Testing.Platform and there is no remaining MTP behavioral difference to resolve (e.g., exit code 8 for zero tests discovered) - Migrating between test frameworks (e.g., MSTest to xUnit.net) -- different effort entirely - The project builds UWP or packaged WinUI test projects -- MTP does not support these yet - The solution mixes .NET and non-.NET test adapters (e.g., JavaScript or C++ adapters) -- VSTest is required - Upgrading MSTest versions -- use `migrate-mstest-v1v2-to-v3` or `migrate-mstest-v3-to-v4` ## Inputs | Input | Required | Description | |-------|----------|-------------| | Project or solution path | No | The `.csproj`, `.sln`, or `.slnx` entry point containing test projects. **Discover it yourself** by globbing the working directory; ask only when nothing is found or the choice is genuinely ambiguous | | Test framework | No | MSTest, NUnit, xUnit.net v2, or xUnit.net v3. Auto-detected from package references | | .NET SDK version | No | Determines `dotnet test` integration mode. Auto-detected via `dotnet --version` | | CI/CD pipeline files | No | Paths to pipeline definitions that invoke `vstest.console` or `dotnet test` | ## Workflow ### Step 1: Assess the solution 1. Identify the test framework for each test project -- see the `platform-detection` skill for the package-to-framework mapping. Key indicators: - **MSTest**: References `MSTest` or `MSTest.TestAdapter`, or uses `MSTest.Sdk` (with `` not set to `false`). Note: `MSTest.TestFramework` alone is a library dependency, not a test project. - **NUnit**: References `NUnit3TestAdapter` - **xUnit.net**: References `xunit` and `xunit.runner.visualstudio` 2. Check the .NET SDK version (`dotnet --version`) -- this determines how `dotnet test` integrates with MTP 3. Check whether a `Directory.Build.props` file exists at the solution or repo root -- all MTP properties should go there for consistency 4. Check for `vstest.console.exe` usage in CI scripts or pipeline definitions 5. Check for VSTest-specific `dotnet test` arguments in CI scripts: `--filter`, `--logger`, `--collect`, `--settings`, `--blame*` 6. Run `dotnet test` to establish a baseline of test pass/fail counts ### Step 2: Set up Directory.Build.props > **Critical**: Set MTP runner properties in `Directory.Build.props` at the solution or repo root whenever possible, rather than per-project. This prevents inconsistent configuration where some projects use VSTest and others use MTP (an unsupported scenario). > **Note**: MTP also requires test projects to have `Exe`. Only `MSTest.Sdk` sets this automatically. For all other setups (MSTest NuGet packages with `EnableMSTestRunner`, NUnit with `EnableNUnitRunner`, xUnit.net with `YTest.MTP.XUnit2`), prefer setting `Exe` centrally in `Directory.Build.props` with a condition that targets only test projects. If you cannot reliably target only test projects from `Directory.Build.props`, setting `Exe` per-project is an acceptable exception. > > **Conditioning in `Directory.Build.props`**: Do NOT use `Condition="'$(IsTestProject)' == 'true'"` -- `IsTestProject` is set by the test SDK targets later in evaluation and is not available when `Directory.Build.props` is imported. Use a property that is available early, such as `MSBuildProjectName`, to target test projects by naming convention. For example, if all test projects end in `.Tests`: > > ```xml > > Exe > > ``` > > Adjust the condition (e.g., `.EndsWith('Tests')`, `.Contains('.Test')`) to match the test project naming convention used in the repository. ### Step 3: Enable the framework-specific MTP runner Each framework has its own opt-in property. Add these in `Directory.Build.props` for consistency. #### MSTest **Option A -- MSTest NuGet packages (3.2.0+):** ```xml true Exe ``` Ensure the project references MSTest 3.2.0 or later. If the version is already 3.2.0+, no MSTest version upgrade is needed for MTP migration. **Option B -- MSTest.Sdk:** When using `MSTest.Sdk`, MTP is enabled by default -- no `EnableMSTestRunner` or `OutputType Exe` property is needed (the SDK sets both automatically). The only action is: if the project has `true`, **remove it**. That property forces the project to use VSTest instead of MTP. #### NUnit Requires `NUnit3TestAdapter` **5.0.0** or later. 1. Update `NUnit3TestAdapter` to 5.0.0+: ```xml ``` 1. Enable the NUnit runner: ```xml true Exe ``` #### xUnit.net Add a reference to `YTest.MTP.XUnit2` -- this package provides MTP support for xUnit.net v2 projects without requiring an upgrade to xunit.v3. You must also set `OutputType` to `Exe`: ```xml ``` ```xml Exe ``` > **Note**: `YTest.MTP.XUnit2` preserves the VSTest `--filter` syntax, so no filter migration is needed for xUnit.net v2. It also supports `--settings` for runsettings (xunit-specific configurations only), `xunit.runner.json`, TRX reporting via `--report-trx`, and `--treenode-filter`. #### xUnit.net v3 xUnit.net v3 (`xunit.v3` package) has built-in MTP support. Enable it with: ```xml true ``` > **Important**: xUnit.net v3 on MTP does NOT support the VSTest `--filter` syntax. You must translate filters to xUnit.net v3's native filter options (see Step 5). ### Step 4: Configure dotnet test integration The `dotnet test` integration depends on the .NET SDK version. #### .NET 10 SDK and later (recommended) Use the native MTP mode by adding a `test` section to `global.json`: ```json { "sdk": { "version": "10.0.100" }, "test": { "runner": "Microsoft.Testing.Platform" } } ``` In this mode, `dotnet test` arguments are passed directly -- for example, `dotnet test --report-trx`. > **Important**: `global.json` does not support trailing commas. Ensure the JSON is strictly valid. #### .NET 9 SDK and earlier Use the VSTest mode of `dotnet test` command to run MTP test projects by adding this property in `Directory.Build.props`: ```xml true ``` > **Important**: In this mode, you must use `--` to separate `dotnet test` build arguments from MTP arguments. For example: `dotnet test --no-build -- --list-tests`. ### Step 5: Update dotnet test command-line arguments VSTest-specific arguments must be translated to MTP equivalents. Build-related arguments (`-c`, `-f`, `--no-build`, `--nologo`, `-v`, etc.) are unchanged. | VSTest argument | MTP equivalent | Notes | |-----------------|----------------|-------| | `--test-adapter-path` | Not applicable | MTP does not use external adapter discovery | | `--blame` | Not applicable | | | `--blame-crash` | `--crashdump` | Requires `Microsoft.Testing.Extensions.CrashDump` NuGet package | | `--blame-crash-dump-type ` | `--crashdump-type ` | Requires CrashDump extension | | `--blame-hang` | `--hangdump` | Requires `Microsoft.Testing.Extensions.HangDump` NuGet package | | `--blame-hang-dump-type ` | `--hangdump-type ` | Requires HangDump extension | | `--blame-hang-timeout ` | `--hangdump-timeout ` | Requires HangDump extension | | `--collect "Code Coverage;Format=cobertura"` | `--coverage --coverage-output-format cobertura` | Per-extension arguments | | `-d\|--diag ` | `--diagnostic` | | | `--filter ` | `--filter ` | Same syntax for MSTest, NUnit, and xUnit.net v2 (with `YTest.MTP.XUnit2`). For xUnit.net v3, see filter migration below | | `-l\|--logger trx` | `--report-trx` | Requires `Microsoft.Testing.Extensions.TrxReport` NuGet package | | `--results-directory ` | `--results-directory ` | Same | | `-s\|--settings ` | `--settings ` | MSTest and NUnit still support `.runsettings` | | `-t\|--list-tests` | `--list-tests` | Same | | `-- ` | `--test-parameter` | Applicable only to MSTest and NUnit | #### Filter migration **MSTest, NUnit, and xUnit.net v2 (with `YTest.MTP.XUnit2`)**: The VSTest `--filter` syntax is identical on both VSTest and MTP. No changes needed. **xUnit.net v3 (native MTP)**: xUnit.net v3 does NOT support the VSTest `--filter` syntax on MTP. You must translate filters to xUnit.net v3's native filter options. #### xUnit.net v3 filter flags | Flag | Description | |------|-------------| | `--filter-class "name"` | Run all tests in a given class. Supports wildcards (`*`). | | `--filter-not-class "name"` | Exclude all tests in a given class | | `--filter-method "name"` | Run a specific test method | | `--filter-not-method "name"` | Exclude a specific test method | | `--filter-namespace "name"` | Run all tests in a namespace | | `--filter-not-namespace "name"` | Exclude all tests in a namespace | | `--filter-trait "name=value"` | Run tests with a matching trait | | `--filter-not-trait "name=value"` | Exclude tests with a matching trait | Multiple values can be specified with a single flag: `--filter-class Foo Bar`. #### VSTest → xUnit.net v3 filter translation table | VSTest `--filter` syntax | xUnit.net v3 MTP equivalent | Notes | |---|---|---| | `FullyQualifiedName~ClassName` | `--filter-class *ClassName*` | Wildcards required for substring match | | `FullyQualifiedName=Ns.Class.Method` | `--filter-method Ns.Class.Method` | Exact match on fully qualified method | | `Name=MethodName` | `--filter-method *MethodName*` | Wildcards for substring match | | `Category=Value` (trait) | `--filter-trait "Category=Value"` | Filter by trait name/value pair | | Complex expressions | `--filter-query "expr"` | Uses xUnit.net query filter language (see below) | #### xUnit.net v3 query filter language For complex expressions, use `--filter-query` with a path-segment syntax: ```text ////[traitName=traitValue] ``` Each segment matches against: assembly name, namespace, class name, method name. Use `*` for "match all" in any segment. Documentation: #### Translation example ```shell # VSTest dotnet test --filter "FullyQualifiedName~IntegrationTests&Category=Smoke" # xUnit.net v3 MTP -- using individual filters (AND behavior) dotnet test -- --filter-class *IntegrationTests* --filter-trait "Category=Smoke" # xUnit.net v3 MTP -- using query language (assembly/namespace/class/method[trait]) dotnet test -- --filter-query "/*/*/*IntegrationTests*/*[Category=Smoke]" ``` > **Note**: When combining `--filter-class` and `--filter-trait`, both conditions must match (AND behavior). For complex expressions, use `--filter-query` with the path-segment syntax. See the [xUnit.net query filter language docs](https://xunit.net/docs/query-filter-language) for full reference. ### Step 6: Install MTP extension packages (if needed) If CI scripts use TRX reporting, crash dumps, or hang dumps, add the corresponding NuGet packages: ```xml ``` ### Step 7: Update CI/CD pipelines #### Azure DevOps **If using the VSTest task (`VSTest@3`)**: Replace with the .NET Core CLI task (`DotNetCoreCLI@2`): ```yaml # Before (VSTest task) - task: VSTest@3 inputs: testAssemblyVer2: '**/*Tests.dll' runSettingsFile: 'test.runsettings' # After (.NET Core CLI task) - task: DotNetCoreCLI@2 displayName: Run tests inputs: command: 'test' arguments: '--no-build --configuration Release' ``` **If already using DotNetCoreCLI@2**: Update arguments per Step 5 translations. Remember the `--` separator on .NET 9 and earlier: ```yaml - task: DotNetCoreCLI@2 displayName: Run tests inputs: command: 'test' arguments: '--no-build -- --report-trx --results-directory $(Agent.TempDirectory)' ``` #### GitHub Actions Update `dotnet test` invocations in workflow files with the same argument translations from Step 5. #### Replace vstest.console.exe If any script invokes `vstest.console.exe` directly, replace it with `dotnet test`. The test projects are now executables and can also be run directly. ### Step 8: Handle behavioral differences #### Zero tests exit code VSTest silently succeeds when zero tests are discovered. MTP fails with **exit code 8**. Options: - Pass `--ignore-exit-code 8` when running tests - Add to `Directory.Build.props`: ```xml $(TestingPlatformCommandLineArguments) --ignore-exit-code 8 ``` - Use environment variable: `TESTINGPLATFORM_EXITCODE_IGNORE=8` ### Step 9: Remove VSTest-only packages (optional) Once migration is complete and verified, remove packages that are only needed for VSTest: - `Microsoft.NET.Test.Sdk` -- not needed for MTP (MSTest.Sdk v4 already omits it by default) - `xunit.runner.visualstudio` -- only needed for VSTest discovery of xUnit.net (not needed when using `YTest.MTP.XUnit2`) - `NUnit3TestAdapter` VSTest-only features -- the adapter is still needed but only for the MTP runner > **Note**: If you need to maintain VSTest compatibility during a transition period, keep these packages. ### Step 10: Verify 1. Run `dotnet build` -- confirm zero errors 2. Run `dotnet test` -- confirm all tests pass 3. Compare test pass/fail counts to the pre-migration baseline 4. Run the test executable directly (e.g., `./bin/Debug/net8.0/MyTests.exe`) -- confirm it works 5. Verify CI pipeline produces the expected test result artifacts (TRX files, code coverage, crash dumps) 6. Test that Test Explorer in Visual Studio (17.14+) or VS Code discovers and runs tests ## Validation - [ ] All test projects use MTP runner (no VSTest-only configuration remains) - [ ] `dotnet build` completes with zero errors - [ ] `dotnet test` passes all tests and test counts match pre-migration baseline - [ ] Test executable runs directly (e.g., `./bin/Debug/net8.0/MyTests.exe`) - [ ] CI pipeline produces expected test result artifacts (TRX files, code coverage, crash dumps) - [ ] Test Explorer in Visual Studio or VS Code discovers and runs tests - [ ] No `vstest.console.exe` invocations remain in CI scripts - [ ] `Exe` is set for all non-MSTest.Sdk test projects ## Common Pitfalls | Pitfall | Solution | |---------|----------| | Mixing VSTest and MTP projects in the same solution | Migrate all test projects together -- mixed mode is unsupported | | `dotnet test` arguments ignored on .NET 9 and earlier | Use `--` to separate build args from MTP args: `dotnet test -- --report-trx` | | Exit code 8 on CI without failures | MTP fails when zero tests run; use `--ignore-exit-code 8` or fix test discovery | | MSTest.Sdk v4 + vstest.console no longer works | MSTest.Sdk v4 no longer adds `Microsoft.NET.Test.Sdk` -- add it explicitly or switch to `dotnet test` | | Missing `Exe` | Required for all setups except MSTest.Sdk (which sets it automatically) | | Using `Condition="'$(IsTestProject)' == 'true'"` in `Directory.Build.props` | `IsTestProject` is not yet defined when `Directory.Build.props` is evaluated -- use `$(MSBuildProjectName.EndsWith('.Tests'))` (or a similar name-based check) instead | ## Next Steps - Use `run-tests` for running tests on the new MTP platform - Use `mtp-hot-reload` for iterative test fixing with hot reload on MTP ## More Info - [Test platforms overview](https://learn.microsoft.com/dotnet/core/testing/test-platforms-overview) - [Migrate from VSTest to Microsoft.Testing.Platform](https://learn.microsoft.com/dotnet/core/testing/migrating-vstest-microsoft-testing-platform) - [Microsoft.Testing.Platform overview](https://learn.microsoft.com/dotnet/core/testing/microsoft-testing-platform-intro) - [Testing with dotnet test](https://learn.microsoft.com/dotnet/core/testing/unit-testing-with-dotnet-test) - [Microsoft.Testing.Platform CLI options](https://learn.microsoft.com/dotnet/core/testing/microsoft-testing-platform-cli-options) - [Microsoft.Testing.Platform extensions](https://learn.microsoft.com/dotnet/core/testing/unit-testing-platform-extensions)