MSTest v1/v2 -> v3 Migration

Workflow

Step 1: Assess the project

1. Identify which MSTest version is currently in use:

- Assembly reference: Look for Microsoft.VisualStudio.QualityTools.UnitTestFramework in project references -> MSTest v1 - NuGet packages: Check MSTest.TestFramework and MSTest.TestAdapter package versions -> v1 if 1.x, v2 if 2.x

1. Check if the project uses a .testsettings file (indicated by <LegacySettings> in test configuration)
2. Check if the target framework is dropped in v3 (see Step 4)
3. Run a clean build to establish a baseline of existing errors/warnings

Step 2: Remove v1 assembly references (if applicable)

If the project uses MSTest v1 via assembly references:

1. Remove the reference to Microsoft.VisualStudio.QualityTools.UnitTestFramework.dll

- In SDK-style projects, remove the <Reference> element from the .csproj - In non-SDK-style projects, remove via Visual Studio Solution Explorer -> References -> right-click -> Remove

1. Save the project file

Step 3: Update packages to MSTest v3

Choose one of these approaches:

Option A -- Install the MSTest metapackage (recommended):

Remove individual MSTest.TestFramework and MSTest.TestAdapter package references and replace with the unified MSTest metapackage:

<PackageReference Include="MSTest" Version="3.8.0" />

Also ensure Microsoft.NET.Test.Sdk is referenced (or update individual MSTest.TestFramework + MSTest.TestAdapter packages to 3.8.0 if you prefer not using the metapackage).

Option B -- Use MSTest.Sdk (SDK-style projects only):

Change <Project Sdk="Microsoft.NET.Sdk"> to <Project Sdk="MSTest.Sdk/3.8.0">. MSTest.Sdk automatically provides MSTest.TestFramework, MSTest.TestAdapter, MSTest.Analyzers, and Microsoft.NET.Test.Sdk.

> Important: MSTest.Sdk defaults to Microsoft.Testing.Platform (MTP) instead of VSTest. For VSTest compatibility (e.g., vstest.console in CI), add <PackageReference Include="Microsoft.NET.Test.Sdk" Version="17.13.0" />.

When switching to MSTest.Sdk, remove these (SDK provides them automatically):

• Packages: MSTest, MSTest.TestFramework, MSTest.TestAdapter, MSTest.Analyzers, Microsoft.NET.Test.Sdk
• Properties: <EnableMSTestRunner>, <OutputType>Exe</OutputType>, <IsPackable>false</IsPackable>, <IsTestProject>true</IsTestProject>

Step 4: Update target frameworks if needed

MSTest v3 supports .NET 6+, .NET Core 3.1, .NET Framework 4.6.2+, .NET Standard 2.0, UWP 16299+, and WinUI 18362+. If the project targets a dropped framework version, update to a supported one:

| Dropped | Recommended replacement | |---------|------------------------| | .NET 5 | .NET 8.0 (current LTS) or .NET 6+ | | .NET Framework < 4.6.2 | .NET Framework 4.6.2 | | .NET Standard 1.0 | .NET Standard 2.0 | | UWP < 16299 | UWP 16299 | | WinUI < 18362 | WinUI 18362 |

> Note: .NET 6, .NET 8, and .NET 9 are all supported by MSTest v3. Do not change TFMs that are already supported.

Step 5: Resolve build errors and breaking changes

Run dotnet build and fix errors using the Breaking Changes Summary above. Key fixes:

Assertion overloads -- MSTest v3 removed Assert.AreEqual(object, object) and Assert.AreNotEqual(object, object). Add explicit generic type parameters:

// Before (v1/v2)                           // After (v3)
Assert.AreEqual(expected, actual);        -> Assert.AreEqual<MyType>(expected, actual);
Assert.AreNotEqual(a, b);                -> Assert.AreNotEqual<MyType>(a, b);
Assert.AreSame(expected, actual);         -> Assert.AreSame<MyType>(expected, actual);

DataRow strict type matching -- argument types must exactly match parameter types. Implicit conversions that worked in v2 fail in v3:

// Error: 1L (long) won't convert to int parameter -> fix: use 1 (int)
// Error: 1.0 (double) won't convert to float parameter -> fix: use 1.0f (float)

Timeout behavior -- unified across .NET Core and .NET Framework. Verify [Timeout] values still work.

Step 6: Replace .testsettings with .runsettings

The .testsettings file and <LegacySettings> are no longer supported in MSTest v3. Delete the `.testsettings` file and create a .runsettings file -- do not keep both.

Key mappings:

| .testsettings | .runsettings equivalent | |---|---| | TestTimeout property | <MSTest><TestTimeout>30000</TestTimeout></MSTest> | | Deployment config | <MSTest><DeploymentEnabled>true</DeploymentEnabled></MSTest> or remove | | Assembly resolution settings | Remove -- not needed in modern .NET | | Data collectors | <DataCollectionRunSettings><DataCollectors> section |

> Important: Map timeout to <MSTest><TestTimeout> (per-test), not <TestSessionTimeout> (session-wide). Remove <LegacySettings> entirely.

Step 7: Verify

1. Run dotnet build -- confirm zero errors and review any new warnings
2. Run dotnet test -- confirm all tests pass
3. Compare test results (pass/fail counts) to the pre-migration baseline
4. Check that no tests were silently dropped due to discovery changes

Related skills