skip to content

In NUnit 5, why is Assert.That with Is, Has, Does and Throws the primary assertion model, and where did Assert.AreEqual go?

level: middleimportance: must knowfreq 57%

answer

  1. one entry point, composable constraints
  2. actual first, expected inside the constraint
  3. caller expressions in failure messages
  4. NUnit.Framework.Legacy.ClassicAssert
  5. C# 14 extension forwards in NUnit 5

basics

~20 s

NUnit's constraint model puts every check behind Assert.That(actual, constraint), with constraints built from Is, Has, Does and Throws that compose and explain failures. NUnit 4 moved classic asserts to ClassicAssert; NUnit 5 adds C# 14 extensions forwarding Assert.AreEqual to it.

solid answer

~30 s

`Assert.That(actual, Is.EqualTo(expected))` is NUnit's one assertion entry point; the second argument is a **constraint** built from the `Is`, `Has`, `Does`, `Throws` and `Contains` helpers. Constraints compose (`Is.Not.Null`, `Has.Count.EqualTo(3)`, `Is.EqualTo(9.60m).Within(0.01m)`, `Does.StartWith("EU-")`) and carry their own failure text, and NUnit captures the caller's expressions so a failure shows the code that failed. The actual value always comes first, which removes the expected/actual swap of `AreEqual`. NUnit 4 moved the classic methods to `NUnit.Framework.Legacy.ClassicAssert`. In NUnit 5 (assumed here) the same `NUnit` package also ships C# 14 extension members, so `Assert.AreEqual(...)` compiles again as a forward to `ClassicAssert` in projects compiled as C# 14.

code

csharp · 12 lines
csharp
var quote = calculator.Quote(2m, Zone.Europe, express: true);

Assert.That(quote, Is.Not.Null);
Assert.That(quote.Total, Is.EqualTo(16.40m));
Assert.That(quote.Lines, Has.Count.EqualTo(3));
Assert.That(quote.Reference, Does.StartWith("EU-"));
Assert.That(quote.Zones, Is.EquivalentTo(new[] { Zone.Europe }));
Assert.That(() => calculator.Calculate(-1m, Zone.Europe, false),
    Throws.InstanceOf<ArgumentException>());

// Legacy form, still available through NUnit.Framework.Legacy
ClassicAssert.AreEqual(16.40m, quote.Total);

go deeper

for a junior

Recall the Assert.That(actual, constraint) shape and the common constraints: Is.EqualTo, Is.Null, Has.Count, Does.Contain.

for a middle

Explain why the constraint model replaced classic asserts, where ClassicAssert lives since NUnit 4, and the exact-type versus instance-of split for exceptions.

for a senior

Plan a migration of a large classic-assert suite: when NUnit 5's C# 14 forwards are an acceptable bridge and when to convert to Assert.That.

for a principal

Decide whether the team standardises on the constraint model or an external assertion library, and enforce it consistently across repositories.

## One entry point, many constraints NUnit's **constraint model** reduces assertions to one shape: ```csharp Assert.That(actual, constraint); ``` The **constraint** is an object that knows how to test a value and how to describe a failure. NUnit builds them with static helper classes: | Helper | Examples | Checks | |---|---|---| | `Is` | `Is.EqualTo(9.60m)`, `Is.Null`, `Is.Positive`, `Is.InRange(1, 30)`, `Is.EquivalentTo(list)`, `Is.Ordered` | value, range, type, collection order | | `Has` | `Has.Count.EqualTo(3)`, `Has.Property("Carrier")`, `Has.Some.EqualTo(Zone.Europe)`, `Has.Exactly(1).Items` | properties and collection members | | `Does` | `Does.StartWith("EU-")`, `Does.Contain("express")`, `Does.Match(@"^\d{5}$")`, `Does.ContainKey("EU")` | strings, collections, dictionaries | | `Throws` | `Throws.TypeOf<ArgumentOutOfRangeException>()`, `Throws.InstanceOf<ArgumentException>()`, `Throws.Nothing` | exceptions from a delegate | | `Contains` | `Contains.Item(Zone.Europe)` | collection membership | Constraints **compose**: `Is.Not.Null`, `Is.EqualTo(9.60m).Within(0.01m)`, `Has.All.GreaterThan(0)`, `Is.EqualTo("eu").IgnoreCase`, and `.And` / `.Or` / `.With` to chain conditions. ## Why it became the primary model 1. **Actual first, every time.** `ClassicAssert.AreEqual(expected, actual)` invites swapped arguments, which produce misleading "expected X but was Y" messages. In `Assert.That(actual, Is.EqualTo(expected))` the roles cannot be confused. 2. **Better failure messages.** NUnit 5's `Assert.That` captures the caller's argument expressions, so a failure shows text such as `Assert.That(quote.Total, Is.EqualTo(16.40m))` beside the expected and actual values. 3. **One vocabulary.** Instead of dozens of methods (`AreEqual`, `IsTrue`, `Greater`, `IsInstanceOf`, `CollectionAssert.AreEquivalent`, `StringAssert.StartsWith`), a single method takes composable constraints. New checks are new constraints, not new `Assert` methods. 4. **Modifiers on the expectation.** Tolerance (`Within`, `Percent`), case (`IgnoreCase`), custom comparers (`Using`) and property-by-property equality (`UsingPropertiesComparer`) attach to the constraint. ## Exceptions through constraints Exception checks use the same model with a delegate as the actual value: ```csharp Assert.That(() => calculator.Calculate(-1m, Zone.Europe, false), Throws.TypeOf<ArgumentOutOfRangeException>()); ``` The distinction to remember is **exact type versus instance-of**: - `Throws.TypeOf<T>()` and shortcuts such as `Throws.ArgumentException` require **exactly** `T`. An `ArgumentOutOfRangeException` does **not** satisfy `Throws.ArgumentException`. - `Throws.InstanceOf<ArgumentException>()` accepts `ArgumentException` **or any derived type**. The method forms follow the same split: `Assert.Throws<T>` checks the exact type and returns the exception; `Assert.Catch<T>` accepts derived types. For `async` code use `Assert.ThrowsAsync<T>` or `Assert.ThatAsync`; passing an async lambda to `Assert.Throws` is rejected because it is an `async void` delegate. ## Where the classic asserts went | Release | Where `AreEqual`, `IsTrue`, `Greater` live | |---|---| | NUnit 3 | on `Assert` itself | | NUnit 4 | moved to `ClassicAssert` in the `NUnit.Framework.Legacy` namespace | | NUnit 5 | still `ClassicAssert`, plus C# 14 **extension members** on `Assert` that forward to it | The NUnit 5 package ships `nunit.framework.legacy.dll` beside the main framework assembly. Its `ClassicAssertExtensions` class uses a C# 14 `extension(Assert)` block, so `Assert.AreEqual(expected, actual)` resolves again, one-to-one, to `ClassicAssert.AreEqual`. A project needs to compile as **C# 14** (the default for `net10.0`) to see them. This is a migration convenience for old suites, not a change of direction: the extensions forward to the legacy methods, and new tests are expected to use `Assert.That`. ## Migrating a classic-assert suite An upgrade from NUnit 3 usually meets thousands of `Assert.AreEqual` calls. The options, from least to most work: 1. **Keep compiling with NUnit 5's forwards.** On a C# 14 project, `Assert.AreEqual` and friends resolve to the extension members and the suite builds unchanged. 2. **Switch the receiver.** Replace `Assert.AreEqual` with `ClassicAssert.AreEqual` (and add `using NUnit.Framework.Legacy;`), which works on any language version. 3. **Convert to constraints.** Rewrite to `Assert.That(actual, Is.EqualTo(expected))`, fixing swapped arguments as you go. Most teams take step 1 or 2 to get onto the new version quickly, then convert files to the constraint model as they touch them, so that new tests never add classic calls. ## Reading a constraint failure A failing constraint reports three things: what was expected (from the constraint's own description), what was actually found, and the expression that was asserted. For a collection or string mismatch NUnit also points at the first differing index. That is enough to diagnose most failures straight from a CI log, which is a large part of why the constraint form is preferred.

  • Why does Throws.ArgumentException fail when the code throws ArgumentOutOfRangeException?
    `Throws.ArgumentException` is a shortcut for `Throws.TypeOf<ArgumentException>()`, which demands the exact type. `ArgumentOutOfRangeException` derives from `ArgumentException` but is not that type. Use `Throws.InstanceOf<ArgumentException>()`, or `Assert.Catch<ArgumentException>`, to accept derived exceptions.
  • What do you need for Assert.AreEqual to compile in an NUnit 5 project?
    Either call `ClassicAssert.AreEqual` with `using NUnit.Framework.Legacy;`, or compile the project as C# 14 (the default for `net10.0`) so the NUnit 5 extension members on `Assert` are visible. Those extensions simply forward to `ClassicAssert`.
  • How do you compare two lists ignoring order with NUnit constraints?
    Use `Is.EquivalentTo(expected)`. `Is.EqualTo` on collections compares element by element in order, while `Is.EquivalentTo` checks that both contain the same items with the same counts, in any order.

  • Assert.That(expected, Is.EqualTo(actual)) is the right argument order
  • Throws.ArgumentException also matches ArgumentOutOfRangeException
  • Assert.Throws<T> accepts any exception derived from T
  • NUnit 5 deleted the classic asserts entirely
  • The NUnit 5 Assert.AreEqual is a new implementation, not a forward to ClassicAssert
  • Is.EqualTo on two lists ignores element order

Assumes NUnit 5.0.0: classic asserts live in NUnit.Framework.Legacy.ClassicAssert since NUnit 4, and the 5 line adds C# 14 extension forwards on Assert.