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 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:

xml

<!-- 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:

json

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

xml

<!-- 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
```

csharp

[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

CollectionAssert

where both exist.

Equality and null checks

csharp

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]

csharp

// 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

csharp

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

String assertions

csharp

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

Type assertions

csharp

// 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

csharp

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

csharp

[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:

csharp

[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>

csharp

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+)

csharp

[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

```
[AssemblyInitialize]
```
— once per assembly
```
[ClassInitialize]
```
— once per class
Per test:
- With
```
TestContext
```
  property injection: Constructor → set
```
TestContext
```
  property →
```
[TestInitialize]
```
- With constructor injection of
```
TestContext
```
  : Constructor (receives
```
TestContext
```
  ) →
```
[TestInitialize]
```
Test method
```
[TestCleanup]
```
→
```
DisposeAsync
```
→
```
Dispose
```
— per test
```
[ClassCleanup]
```
— once per class
```
[AssemblyCleanup]
```
— once per assembly

Step 6: Apply cancellation and timeout patterns

Always use

TestContext.CancellationToken

with

[Timeout]

csharp

[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+)

csharp

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

Conditional execution (MSTest 3.10+)

csharp

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

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

Parallelization

csharp

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

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

Common Pitfalls

Pitfall	Solution
`Assert.AreEqual(actual, expected)` — swapped arguments	Always put expected first: `Assert.AreEqual(expected, actual)`
`[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

writing-mstest-tests

NPX Install

Tags

SKILL.md Content

Writing MSTest Tests

When to Use

When Not to Use

Inputs

Workflow

Step 1: Determine project setup

Step 2: Write test classes following conventions

Step 3: Use modern assertion APIs

Equality and null checks

Exception testing — use
`Assert.Throws`
instead of
`[ExpectedException]`

Collection assertions

String assertions

Type assertions

Comparison assertions

Step 4: Use data-driven tests for multiple inputs

DataRow for inline values

DynamicData with ValueTuples (preferred for complex data)

Step 5: Handle test lifecycle correctly

Execution order

Step 6: Apply cancellation and timeout patterns

Step 7: Use advanced features where appropriate

Retry flaky tests (MSTest 3.9+)

Conditional execution (MSTest 3.10+)

Parallelization

Common Pitfalls