microsoft/writing-mstest-tests

Writing MSTest Tests

Help users write effective, modern unit tests with MSTest 3.x/4.x using current APIs and best practices.

When to Use

• User wants to write new MSTest unit tests
• User wants to improve or modernize existing MSTest tests
• User asks about MSTest assertion APIs, data-driven patterns, or test lifecycle
• User needs to review MSTest test code for anti-patterns

When Not to Use

• User needs to run or execute tests (use the run-tests skill)
• User needs to upgrade from MSTest v1/v2 to v3 (use migrate-mstest-v1v2-to-v3)
• User needs to upgrade from MSTest v3 to v4 (use migrate-mstest-v3-to-v4)
• User needs CI/CD pipeline configuration
• User is using xUnit, NUnit, or TUnit (not MSTest)

Inputs

| Input | Required | Description | |-------|----------|-------------| | Code under test | No | The production code to be tested | | Existing test code | No | Current tests to review or improve | | Test scenario description | No | What behavior the user wants to test |

Workflow

Step 1: Determine project setup

Check the test project for MSTest version and configuration:

• If using MSTest.Sdk (<Sdk Name="MSTest.Sdk">): modern setup, all features available
• If using MSTest metapackage: modern setup (MSTest 3.x+)
• If using MSTest.TestFramework + MSTest.TestAdapter: check version for feature availability

Recommend MSTest.Sdk or the MSTest metapackage for new projects:

<!-- Option 1: MSTest SDK (simplest, recommended for new projects) -->
<Project Sdk="MSTest.Sdk">
  <PropertyGroup>
    <TargetFramework>net9.0</TargetFramework>
  </PropertyGroup>
</Project>

When using MSTest.Sdk, put the version in global.json instead of the project file so all test projects get bumped together:

{
  "msbuild-sdks": {
    "MSTest.Sdk": "3.8.2"
  }
}

<!-- Option 2: MSTest metapackage -->
<Project Sdk="Microsoft.NET.Sdk">
  <PropertyGroup>
    <TargetFramework>net9.0</TargetFramework>
  </PropertyGroup>
  <ItemGroup>
    <PackageReference Include="MSTest" Version="3.8.2" />
  </ItemGroup>
</Project>

Step 2: Write test classes following conventions

Apply these structural conventions:

• Seal test classes with sealed for performance and design clarity
• Use [TestClass] on the class and [TestMethod] on test methods
• Follow the Arrange-Act-Assert (AAA) pattern
• Name tests using MethodName_Scenario_ExpectedBehavior
• Use separate test projects with naming convention [ProjectName].Tests

[TestClass]
public sealed class OrderServiceTests
{
    [TestMethod]
    public void CalculateTotal_WithDiscount_ReturnsReducedPrice()
    {
        // Arrange
        var service = new OrderService();
        var order = new Order { Price = 100m, DiscountPercent = 10 };

        // Act
        var total = service.CalculateTotal(order);

        // Assert
        Assert.AreEqual(90m, total);
    }
}

Step 3: Use modern assertion APIs

Use the correct assertion for each scenario. Prefer Assert class methods over StringAssert or CollectionAssert where both exist.

Equality and null checks

Assert.AreEqual(expected, actual);      // Value equality
Assert.AreSame(expected, actual);       // Reference equality
Assert.IsNull(value);
Assert.IsNotNull(value);

Exception testing -- use Assert.Throws instead of [ExpectedException]

// Synchronous
var ex = Assert.ThrowsExactly<ArgumentNullException>(() => service.Process(null));
Assert.AreEqual("input", ex.ParamName);

// Async
var ex = await Assert.ThrowsExactlyAsync<InvalidOperationException>(
    async () => await service.ProcessAsync(null));

• Assert.Throws<T> matches T or any derived type
• Assert.ThrowsExactly<T> matches only the exact type T

Collection assertions

Assert.Contains(expectedItem, collection);
Assert.DoesNotContain(unexpectedItem, collection);
var single = Assert.ContainsSingle(collection);  // Returns the single element
Assert.HasCount(3, collection);
Assert.IsEmpty(collection);
Assert.IsNotEmpty(collection);

Replace generic Assert.IsTrue with specialized assertions -- they give better failure messages:

| Instead of | Use | |---|---| | Assert.IsTrue(list.Count > 0) | Assert.IsNotEmpty(list) | | Assert.IsTrue(list.Count() == 3) | Assert.HasCount(3, list) | | Assert.IsTrue(x != null) | Assert.IsNotNull(x) | | list.Single(predicate) + Assert.IsNotNull | Assert.ContainsSingle(list) | | Assert.IsTrue(list.Contains(item)) | Assert.Contains(item, list) |

String assertions

Assert.Contains("expected", actualString);
Assert.StartsWith("prefix", actualString);
Assert.EndsWith("suffix", actualString);
Assert.MatchesRegex(@"\d{3}-\d{4}", phoneNumber);

Type assertions

// MSTest 3.x -- out parameter
Assert.IsInstanceOfType<MyHandler>(result, out var typed);
typed.Handle();

// MSTest 4.x -- returns directly
var typed = Assert.IsInstanceOfType<MyHandler>(result);

Comparison assertions

Assert.IsGreaterThan(lowerBound, actual);
Assert.IsLessThan(upperBound, actual);
Assert.IsInRange(actual, low, high);

Step 4: Use data-driven tests for multiple inputs

DataRow for inline values

[TestMethod]
[DataRow(1, 2, 3)]
[DataRow(0, 0, 0, DisplayName = "Zeros")]
[DataRow(-1, 1, 0)]
public void Add_ReturnsExpectedSum(int a, int b, int expected)
{
    Assert.AreEqual(expected, Calculator.Add(a, b));
}

DynamicData with ValueTuples (preferred for complex data)

Prefer ValueTuple return types over IEnumerable<object[]> for type safety:

[TestMethod]
[DynamicData(nameof(DiscountTestData))]
public void ApplyDiscount_ReturnsExpectedPrice(decimal price, int percent, decimal expected)
{
    var result = PriceCalculator.ApplyDiscount(price, percent);
    Assert.AreEqual(expected, result);
}

// ValueTuple -- preferred (MSTest 3.7+)
public static IEnumerable<(decimal price, int percent, decimal expected)> DiscountTestData =>
[
    (100m, 10, 90m),
    (200m, 25, 150m),
    (50m, 0, 50m),
];

When you need metadata per test case, use TestDataRow<T>:

public static IEnumerable<TestDataRow<(decimal price, int percent, decimal expected)>> DiscountTestDataWithMetadata =>
[
    new((100m, 10, 90m)) { DisplayName = "10% discount" },
    new((200m, 25, 150m)) { DisplayName = "25% discount" },
    new((50m, 0, 50m)) { DisplayName = "No discount" },
];

Step 5: Handle test lifecycle correctly

• Always initialize in the constructor -- this enables readonly fields and works correctly with nullability analyzers (fields are guaranteed non-null after construction)
• Use [TestInitialize] only for async initialization, combined with the constructor for sync parts
• Use [TestCleanup] for cleanup that must run even on failure
• Inject TestContext via constructor (MSTest 3.6+)

[TestClass]
public sealed class RepositoryTests
{
    private readonly TestContext _testContext;
    private readonly FakeDatabase _db;  // readonly -- guaranteed by constructor

    public RepositoryTests(TestContext testContext)
    {
        _testContext = testContext;
        _db = new FakeDatabase();  // sync init in ctor
    }

    [TestInitialize]
    public async Task InitAsync()
    {
        // Use TestInitialize ONLY for async setup
        await _db.SeedAsync();
    }

    [TestCleanup]
    public void Cleanup() => _db.Reset();
}

Execution order

1. [AssemblyInitialize] -- once per assembly
2. [ClassInitialize] -- once per class
3. Per test:
   • With TestContext property injection: Constructor -> set TestContext property -> [TestInitialize]
   • With constructor injection of TestContext: Constructor (receives TestContext) -> [TestInitialize]
4. Test method
5. [TestCleanup] -> DisposeAsync -> Dispose -- per test
6. [ClassCleanup] -- once per class
7. [AssemblyCleanup] -- once per assembly

Step 6: Apply cancellation and timeout patterns

Always use TestContext.CancellationToken with [Timeout]:

[TestMethod]
[Timeout(5000)]
public async Task FetchData_ReturnsWithinTimeout()
{
    var result = await _client.GetDataAsync(_testContext.CancellationToken);
    Assert.IsNotNull(result);
}

Step 7: Use advanced features where appropriate

Retry flaky tests (MSTest 3.9+)

Use only for genuinely flaky external dependencies (network, file system), not to paper over race conditions or shared state issues.

[TestMethod]
[Retry(3)]
public void ExternalService_EventuallyResponds() { }

Conditional execution (MSTest 3.10+)

[TestMethod]
[OSCondition(OperatingSystems.Windows)]
public void WindowsRegistry_ReadsValue() { }

[TestMethod]
[CICondition(ConditionMode.Exclude)]
public void LocalOnly_InteractiveTest() { }

Parallelization

[assembly: Parallelize(Workers = 4, Scope = ExecutionScope.MethodLevel)]

[TestClass]
[DoNotParallelize]  // Opt out specific classes
public sealed class DatabaseIntegrationTests { }

Validation

• [ ] Test classes are sealed
• [ ] Test methods follow MethodName_Scenario_ExpectedBehavior naming
• [ ] Assert.ThrowsExactly<T> used instead of [ExpectedException]
• [ ] Specialized assertions used instead of Assert.IsTrue (e.g., Assert.IsNotNull, Assert.AreEqual)
• [ ] DynamicData uses ValueTuple return types instead of IEnumerable<object[]>
• [ ] Sync initialization done in the constructor, not [TestInitialize]
• [ ] TestContext.CancellationToken passed to async calls in tests with [Timeout]
• [ ] Project builds with zero errors and all tests pass

Common Pitfalls

| Pitfall | Solution | |---------|----------| | Assert.AreEqual(actual, expected) -- swapped arguments | Always put expected first: Assert.AreEqual(expected, actual). Failure messages show "Expected: X, Actual: Y" so wrong order makes messages confusing | | [ExpectedException] -- obsolete, cannot assert message | Use Assert.Throws<T> or Assert.ThrowsExactly<T> | | items.Single() -- unclear exception on failure | Use Assert.ContainsSingle(items) for better failure messages | | Hard cast (MyType)result -- unclear exception | Use Assert.IsInstanceOfType<MyType>(result) | | IEnumerable<object[]> for DynamicData | Use IEnumerable<(T1, T2, ...)> ValueTuples for type safety | | Sync setup in [TestInitialize] | Initialize in the constructor instead -- enables readonly fields and satisfies nullability analyzers | | CancellationToken.None in async tests | Use TestContext.CancellationToken for cooperative timeout | | public TestContext? TestContext { get; set; } | Drop the ? -- MSTest suppresses CS8618 for this property | | TestContext TestContext { get; set; } = null! | Remove = null! -- unnecessary, MSTest handles assignment | | Non-sealed test classes | Seal test classes by default for performance |