Migrate MSTest v1 or v2 test project to MSTest v3. Use when user says "upgrade MSTest", "upgrade to MSTest v3", "migrate to MSTest v3", "update test framework", "modernize tests", "MSTest v3 migration", "MSTest compatibility", "MSTest v2 to v3", or build errors after updating MSTest packages from 1.x/2.x to 3.x. USE FOR: upgrading from MSTest v1 assembly references (Microsoft.VisualStudio.QualityTools.UnitTestFramework) or MSTest v2 NuGet (MSTest.TestFramework 1.x-2.x) to MSTest v3, fixing assertion overload errors (AreEqual/AreNotEqual), updating DataRow constructors, replacing .testsettings with .runsettings, timeout behavior changes, target framework compatibility (.NET 5 dropped -- use .NET 6+; .NET Fx older than 4.6.2 dropped), adopting MSTest.Sdk. First step toward MSTest v4 -- after this, use migrate-mstest-v3-to-v4. DO NOT USE FOR: migrating to MSTest v4 (use migrate-mstest-v3-to-v4), migrating between frameworks (MSTest to xUnit/NUnit), or general .NET upgrades unrelated to MSTest.
Migrate MSTest v1 or v2 test project to MSTest v3. Use when user says "upgrade MSTest", "upgrade to MSTest v3", "migrate to MSTest v3", "update test framework", "modernize tests", "MSTest v3 migration", "MSTest compatibility", "MSTest v2 to v3", or build errors after updating MSTest packages from 1.x/2.x to 3.x. USE FOR: upgrading from MSTest v1 assembly references (Microsoft.VisualStudio.QualityTools.UnitTestFramework) or MSTest v2 NuGet (MSTest.TestFramework 1.x-2.x) to MSTest v3, fixing assertion overload errors (AreEqual/AreNotEqual), updating DataRow constructors, replacing .testsettings with .runsettings, timeout behavior changes, target framework compatibility (.NET 5 dropped -- use .NET 6+; .NET Fx older than 4.6.2 dropped), adopting MSTest.Sdk. First step toward MSTest v4 -- after this, use migrate-mstest-v3-to-v4. DO NOT USE FOR: migrating to MSTest v4 (use migrate-mstest-v3-to-v4), migrating between frameworks (MSTest to xUnit/NUnit), or general .NET upgrades unrelated to MSTest.
license
MIT
MSTest v1/v2 -> v3 Migration
Migrate a test project from MSTest v1 (assembly references) or MSTest v2 (NuGet 1.x-2.x) to MSTest v3. MSTest v3 is not binary compatible with v1/v2 -- libraries compiled against v1/v2 must be recompiled.
Update TFM: .NET 5 -> net8.0 (LTS) or net6.0+, netfx -> net462+, netstandard1.0 -> netstandard2.0. Note: net6.0, net8.0, net9.0 are all supported
Not binary compatible with v1/v2
Libraries compiled against v1/v2 must be recompiled
Recompile all dependencies against v3
Response Guidelines
Always identify the current version first: Before recommending any migration steps, explicitly state the current MSTest version detected in the project (e.g., "Your project uses MSTest v2 (2.2.10)" or "This is an MSTest v1 project using QualityTools assembly references"). This grounds the migration advice and confirms you've read the project files.
Focused fix requests (user has specific compilation errors after upgrading): Address only the relevant breaking change from the table above. Show a concise before/after fix. Do not walk through the full migration workflow.
Specific feature migration (user asks about one aspect like .testsettings, DataRow, or assertions): Address only that specific aspect with a concrete fix. Do not walk through the entire migration workflow or unrelated breaking changes.
"What to expect" questions (user asks about breaking changes before upgrading): Present only the breaking changes that are clearly relevant to the user's visible code and configuration. For each, give a one-line fix summary. Do not include every possible breaking change -- only the ones that apply. Do not walk through the full workflow.
Full migration requests (user wants complete migration): Follow the complete workflow below.
Comparison questions (user asks about v1 vs v2 differences): Explain concisely -- v1 uses assembly references and requires removing them first; v2 uses NuGet and just needs a version bump. Both converge on the same v3 packages and breaking changes.
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):
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:
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
