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