From f181a0f04487c5285291bd123f17a9bf3a49f2f2 Mon Sep 17 00:00:00 2001 From: Sean Killeen Date: Thu, 22 Oct 2026 08:34:09 -0400 Subject: [PATCH] Clarify CollectionAssert.Contains parameters and failure message `CollectionAssert.Contains` and `DoesNotContain` were listed with `(IEnumerable expected, object actual)`, but the real parameter names are `(IEnumerable collection, object actual)`. Fixes the signatures and adds a short section explaining that the second argument is the item being looked for, why it appears on the **Expected** line of the failure message, that passing a collection as the second argument looks for it as a single element, and that the constraint-based `Does.Contain`/`Has.Member` read more naturally. Fixes #672 Co-Authored-By: Claude Fable 5.1 --- .../classic-assertions/Collection-Assert.md | 31 ++++++++++++++++--- 1 file changed, 27 insertions(+), 4 deletions(-) diff --git a/docs/articles/nunit/writing-tests/assertions/classic-assertions/Collection-Assert.md b/docs/articles/nunit/writing-tests/assertions/classic-assertions/Collection-Assert.md index 7e14700a8..235a9ec8e 100644 --- a/docs/articles/nunit/writing-tests/assertions/classic-assertions/Collection-Assert.md +++ b/docs/articles/nunit/writing-tests/assertions/classic-assertions/Collection-Assert.md @@ -46,13 +46,13 @@ CollectionAssert.AreNotEquivalent(IEnumerable expected, IEnumerable actual); CollectionAssert.AreNotEquivalent( IEnumerable expected, IEnumerable actual, string message, params object[] args); -CollectionAssert.Contains(IEnumerable expected, object actual); +CollectionAssert.Contains(IEnumerable collection, object actual); CollectionAssert.Contains( - IEnumerable expected, object actual, string message, params object[] args); + IEnumerable collection, object actual, string message, params object[] args); -CollectionAssert.DoesNotContain(IEnumerable expected, object actual); +CollectionAssert.DoesNotContain(IEnumerable collection, object actual); CollectionAssert.DoesNotContain( - IEnumerable expected, object actual, string message, params object[] args); + IEnumerable collection, object actual, string message, params object[] args); CollectionAssert.IsSubsetOf(IEnumerable subset, IEnumerable superset); CollectionAssert.IsSubsetOf( @@ -79,6 +79,29 @@ CollectionAssert.IsOrdered(IEnumerable collection, IComparer comparer, string message, params object[] args); ``` +## Contains and DoesNotContain + +The parameters of `Contains` and `DoesNotContain` do not follow the usual *expected, actual* pattern of the other +classic assertions. The first argument is the collection to search, and the second, named `actual`, is the single item +being looked for. Despite its name, that item is what the assertion *expects* to find, so the failure message reports it +on the **Expected** line and the collection on the **But was** line: + +```csharp +CollectionAssert.Contains(new[] { 1, 2 }, 3); + +// Expected: some item equal to 3 +// But was: < 1, 2 > +``` + +Passing a collection as the second argument does not check that one collection contains another. It checks whether the +collection contains that collection as a single element. The parameter names are kept for compatibility, since renaming +them would break callers that use named arguments. The constraint-based equivalents read more naturally: + +```csharp +Assert.That(new[] { 1, 2 }, Does.Contain(3)); +Assert.That(new[] { 1, 2 }, Has.Member(3)); +``` + ## See Also * [Collection Constraints](xref:constraints#collection-constraints)