Editja

MSTest assertions

Use the Assert classes of the Microsoft.VisualStudio.TestTools.UnitTesting namespace to verify specific functionality. A test method exercises the code in your application but reports correctness only when you include Assert statements.

Overview

MSTest provides three assertion classes:

Class Purpose
Assert General-purpose assertions for values, types, and exceptions.
StringAssert String-specific assertions for patterns, substrings, and comparisons.
CollectionAssert Collection assertions for comparing and validating collections.

Important

For new code, always use the Assert class. The StringAssert and CollectionAssert classes are likely to be deprecated in a future release. They're maintained primarily for backward compatibility, but they're not recommended because splitting assertions across three types hurts discoverability.

All assertion methods accept an optional message parameter that displays when the assertion fails, helping you identify the cause:

Assert.AreEqual(expected, actual, "Values should match after processing");

The Assert class

Use the Assert class to verify that the code under test behaves as expected.

Common assertion methods

[TestMethod]
public async Task AssertExamples()
{
    // Equality
    Assert.AreEqual(5, calculator.Add(2, 3));
    Assert.AreNotEqual(0, result);

    // Reference equality
    Assert.AreSame(expected, actual);
    Assert.AreNotSame(obj1, obj2);

    // Boolean conditions
    Assert.IsTrue(result > 0);
    Assert.IsFalse(string.IsNullOrEmpty(name));

    // Null checks
    Assert.IsNull(optionalValue);
    Assert.IsNotNull(requiredValue);

    // Type checks
    Assert.IsInstanceOfType<IDisposable>(obj);
    Assert.IsNotInstanceOfType<string>(obj);

    // Exception testing (MSTest v3.8+)
    Assert.ThrowsExactly<ArgumentNullException>(() => service.Process(null!));
    await Assert.ThrowsExactlyAsync<InvalidOperationException>(
        async () => await service.ProcessAsync());
}

Available APIs

The StringAssert class

Use the StringAssert class to compare and examine strings.

Warning

The StringAssert class is likely to be deprecated in a future release. It's maintained for backward compatibility only and isn't recommended for new code. All StringAssert methods have equivalents on the Assert class, which offers better discoverability. To migrate existing usages, see analyzer MSTEST0046.

Available APIs are:

The CollectionAssert class

Use the CollectionAssert class to compare collections of objects, or to verify the state of a collection.

Warning

The CollectionAssert class is likely to be deprecated in a future release. It's maintained primarily for backward compatibility and isn't recommended for new code. When an equivalent method exists on Assert (such as Assert.Contains, Assert.DoesNotContain, or Assert.HasCount), use Assert for better discoverability.

Available APIs are:

Create custom assertions with Assert.That

The built-in assertion methods don't cover every scenario. To extend the assertion infrastructure with your own checks, MSTest exposes the Assert.That singleton property as an extensibility hook. You add custom assertions as C# extension methods on the Assert instance type, and callers invoke them with the familiar Assert.That.MyAssertion(...) syntax.

For better discoverability, organize project-wide assertions in a dedicated static class. Custom assertions reached through Assert.That show up alongside the built-in methods in IntelliSense, so consumers don't have to remember a separate helper type.

Author a custom assertion

Add an extension method that targets the Assert type and throws AssertFailedException when the condition fails:

using System;
using System.Linq;
using Microsoft.VisualStudio.TestTools.UnitTesting;

public static class CustomAssertExtensions
{
    public static void IsPrime(this Assert assert, int value)
    {
        if (value < 2 || Enumerable.Range(2, (int)Math.Sqrt(value) - 1).Any(i => value % i == 0))
        {
            throw new AssertFailedException($"Assert.That.IsPrime failed. Value <{value}> is not a prime number.");
        }
    }
}

Use a custom assertion

After you import the namespace that contains your extension methods, call your custom assertion through Assert.That:

[TestMethod]
public void Compute_ReturnsPrime()
{
    int result = _calculator.NextPrime(10);
    Assert.That.IsPrime(result);
}

Extension hooks on StringAssert and CollectionAssert

The StringAssert.That and CollectionAssert.That properties expose the same singleton pattern for backward compatibility. For new custom assertions, always target Assert.That. Otherwise, your helpers inherit the same discoverability problems as the legacy classes, and they'll need migration if StringAssert and CollectionAssert are deprecated.

Assert.That property versus Assert.That(...) method

Note

Don't confuse the Assert.That singleton property—used as an extensibility hook—with the Assert.That(() => condition) method added in MSTest 3.8. The latter accepts a Boolean expression and produces detailed failure messages by analyzing the expression tree (for example, Assert.That(() => order.Total > 0)). The two APIs share a name but serve different purposes.

Best practices

  • Use specific assertions: Prefer AreEqual over IsTrue(a == b) for better failure messages.

  • Include descriptive messages: Help identify failures quickly with clear assertion messages.

  • Test one thing at a time: Each test method should verify a single behavior.

  • Use Throws/ThrowsExactly for exceptions: In MSTest v3.8+, prefer Assert.Throws, Assert.ThrowsExactly, and their async counterparts (ThrowsAsync, ThrowsExactlyAsync) over the ExpectedException attribute.

  • Prefer Assert over StringAssert/CollectionAssert: For better discoverability and consistency, use the Assert class. The StringAssert and CollectionAssert classes are likely to be deprecated in a future release.

  • Extend Assert.That for custom assertions: For consistent discoverability, add custom assertions as extension methods on Assert and invoke them through Assert.That. Don't target StringAssert.That or CollectionAssert.That in new code.

The following analyzers help ensure proper usage of assertions:

  • MSTEST0006 - Avoid ExpectedException attribute, use Assert.Throws methods instead.
  • MSTEST0017 - Assertion arguments should be passed in the correct order.
  • MSTEST0023 - Do not negate boolean assertions.
  • MSTEST0025 - Prefer Assert.Fail over always-false conditions.
  • MSTEST0026 - Assertion arguments should avoid conditional access.
  • MSTEST0032 - Review always-true assert conditions.
  • MSTEST0037 - Use proper assert methods.
  • MSTEST0038 - Avoid Assert.AreSame with value types.
  • MSTEST0039 - Use newer Assert.Throws methods.
  • MSTEST0040 - Avoid using asserts in async void context.
  • MSTEST0046 - Use Assert instead of StringAssert.
  • MSTEST0051 - Assert.Throws should contain a single statement.
  • MSTEST0053 - Avoid Assert format parameters.
  • MSTEST0058 - Avoid asserts in catch blocks.

See also

  • Last updated on