Edit

Share via

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.

Tip

When functionality exists in both Assert and StringAssert/CollectionAssert, prefer the Assert class. The Assert class provides better discoverability and is the recommended choice for new code. StringAssert and CollectionAssert are maintained for backward compatibility.

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.

Note

All StringAssert methods have equivalents in the Assert class. Prefer the Assert methods for better discoverability. The StringAssert class is maintained for backward compatibility.

Available APIs are:

The CollectionAssert class

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

Note

When an equivalent method exists in the Assert class (such as Assert.Contains, Assert.DoesNotContain), prefer using Assert for better discoverability. The CollectionAssert class is maintained primarily for backward compatibility.

Available APIs are:

Best practices

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

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

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

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

  5. Prefer Assert over StringAssert/CollectionAssert: When functionality exists in both classes, use the Assert class for better discoverability and consistency.

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