In NUnit 5, why is Assert.That with Is, Has, Does and Throws the primary assertion model, and where did Assert.AreEqual go?
answer
- one entry point, composable constraints
- actual first, expected inside the constraint
- caller expressions in failure messages
- NUnit.Framework.Legacy.ClassicAssert
- C# 14 extension forwards in NUnit 5
basics
~20 sNUnit'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 linesvar 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
Recall the Assert.That(actual, constraint) shape and the common constraints: Is.EqualTo, Is.Null, Has.Count, Does.Contain.
Explain why the constraint model replaced classic asserts, where ClassicAssert lives since NUnit 4, and the exact-type versus instance-of split for exceptions.
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.
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.