Upgrade from MSTestV1 to MSTestV2

Applies to: yesVisual Studio noVisual Studio for Mac noVisual Studio Code

You can upgrade your test project by retargeting the MSTest version referenced in your .csproj from the MSTestV1 to MSTestV2. Not all features in MSTestV1 were brought forward into MSTestV2, so some changes may be required to resolve errors. See MSTestV1 features that are not supported in MSTestV2 to understand what features will no longer function. Some of these may need to be removed from your tests.

  1. Remove the assembly reference to Microsoft.VisualStudio.QualityTools.UnitTestFramework from your unit test project.

  2. Add NuGet package references to MSTestV2 including the MSTest.TestFramework and the MSTest.TestAdapter packages on nuget.org. You can install packages in the NuGet Package Manager Console with the following commands:

    PM> Install-Package MSTest.TestAdapter -Version 2.1.2
    PM> Install-Package MSTest.TestFramework -Version 2.1.2
    

Old style csproj example

Sample .csproj targeting MSTestV1:

<Reference Include="Microsoft.VisualStudio.QualityTools.UnitTestFramework, Version=10.0.0.0, Culture=neutral, PublicKeyToken=b03f5f7f11d50a3a, processorArchitecture=MSIL">
  <Private>False</Private>
</Reference>

Sample .csproj now targeting MSTestV2:

<Reference Include="Microsoft.VisualStudio.TestPlatform.TestFramework, Version=14.0.0.0, Culture=neutral, PublicKeyToken=b03f5f7f11d50a3a, processorArchitecture=MSIL">
  <HintPath>..\packages\MSTest.TestFramework.2.1.2\lib\net45\Microsoft.VisualStudio.TestPlatform.TestFramework.dll</HintPath>
</Reference>

Note

Test projects that are Coded UI tests or Web Load Tests are not compatible with MSTestV2. These project types have been deprecated. Read more on Coded UI Test deprecation and Web Load Test deprecation.

SDK-style csproj (.NET Core and .NET 5 or later)

If your .csproj is the newer SDK-style .csproj you're most likely already using MSTestV2. You can find the NuGet packages for MSTestV2 and the MSTestV2 Adapter on NuGet.

Example:

<ItemGroup>
  <PackageReference Include="Microsoft.NET.Test.Sdk" Version="16.7.1" />
  <PackageReference Include="MSTest.TestAdapter" Version="2.1.1" />
  <PackageReference Include="MSTest.TestFramework" Version="2.1.1" />
</ItemGroup>

Why Upgrade to MSTestV2?

In 2016, we released the next step in evolving the MSTest framework with MSTestV2. You can read more about this change in the announcement blog post.

  • MSTestV2 is more easily acquired and updated because it's delivered as a NuGet Package.

  • MSTestV2 is open source.

  • Uniform app-platform support – MSTestV2 is a converged implementation that offers uniform app-platform support across .NET Framework, .NET Core, ASP.NET Core, and UWP. Read more.

  • The implementation is fully cross platform (Windows, Linux, Mac). Read more.

  • MSTestV2 supports targeting .NET Framework 4.5.0 and later, .NET Core 1.0 and later (Universal Windows Apps 10+), ASP.NET Core 1.0 and later, and .NET 5 and later.

  • Provides a uniform, single end-user extensibility mechanism. Read more.

  • Provides a uniform DataRow support for all MSTest based test projects. Read more.

  • Enables placing the TestCategory attribute at the level of a class or assembly. Read more.

  • Test methods from base classes defined in another assembly are now discovered and run from the derived Test class. This change brings in a consistent behavior with derived test class types. If this behavior isn't required for compatibility reasons, it can be changed back using the following run settings:

    <RunSettings>    
    <MSTest> 
      <EnableBaseClassTestMethodsFromOtherAssemblies>false</EnableBaseClassTestMethodsFromOtherAssemblies> 
    </MSTest> 
    </RunSettings>
    
  • Provides finer-grained control over parallel execution via in-assembly parallel execution of tests. This enables running tests within an assembly in parallel.

  • The TestCleanup method on a TestClass is invoked even if its corresponding TestInitialize method fails. Issue details.

  • The time taken by AssemblyInitialize and ClassInitialize isn't counted towards the test duration. This change limits their impact on a test timing out.

  • Tests that aren't runnable can be configured to be marked as failed via the MapNotRunnableToFailed tag, which is part of the adapter node in the .runsettings file.

    <RunSettings>    
    <MSTest> 
      <MapNotRunnableToFailed>true</MapNotRunnableToFailed> 
    </MSTest> 
    </RunSettings>
    

MSTestV1 features that are not supported in MSTestV2

  • Tests cannot be included into an "Ordered Test".
  • The adapter doesn't support being configured via a .testsettings file. Use the new .runsettings file for test run configuration.
  • The adapter doesn't support test lists specified as a .vsmdi file.
  • The "Coded UI Test Project" and the "Web Performance and Load Test Project" types are not supported. Read more on Coded UI Test deprecation and Web Load Test deprecation.

See also