Equality and containment

Describes how to compare a collection with another collection, and how to verify that it contains, starts with or ends with items.

Expectation	Negated	Summary
IsEqualTo	IsNotEqualTo	has the same items as the expected collection
Contains(item)	DoesNotContain	contains the item, optionally a number of times
Contains(predicate)	DoesNotContain	contains an item that satisfies the predicate
Contains(collection)	DoesNotContain	contains the expected items (a subset)
IsContainedIn	IsNotContainedIn	all its items are contained in the expected collection
StartsWith	DoesNotStartWith	starts with the expected items
EndsWith	DoesNotEndWith	ends with the expected items

Equality

You can verify that a collection is equal to another collection:

IEnumerable<int> values = Enumerable.Range(1, 3);

await Expect.That(values).IsEqualTo([1, 2, 3]);
await Expect.That(values).IsEqualTo([3, 2, 1]).InAnyOrder();
await Expect.That(values).IsEqualTo([1, 1, 2, 2, 3, 3]).IgnoringDuplicates();
await Expect.That(values).IsEqualTo([3, 3, 2, 2, 1, 1]).InAnyOrder().IgnoringDuplicates();

await Expect.That(values).IsNotEqualTo([2, 3]);
await Expect.That(values).IsNotEqualTo([4, 3, 2, 1]).InAnyOrder();

Without InAnyOrder() the items are compared in the order in which the collection enumerates them, which is not defined for a set.

Contained items

You can verify that the collection contains a specific item or not:

IEnumerable<string> songs = ["Come Together", "Something", "Let It Be"];

await Expect.That(songs).Contains("Let It Be");
await Expect.That(songs).DoesNotContain("Yesterday");

You can also set occurrence constraints on Contains:

using aweXpect.Core; // for `Times()`

IEnumerable<int> values = [1, 1, 1, 2];

await Expect.That(values).Contains(1).MoreThan(1.Times());
await Expect.That(values).Contains(1).AtLeast(2.Times());
await Expect.That(values).Contains(1).Exactly(3.Times());
await Expect.That(values).Contains(1).AtMost(4.Times());
await Expect.That(values).Contains(1).LessThan(5.Times());
await Expect.That(values).Contains(1).Between(1).And(5.Times());

Predicate

You can verify that the collection contains an item that satisfies a condition, with the same occurrence constraints:

IEnumerable<int> values = [1, 1, 1, 2];

await Expect.That(values).Contains(x => x > 1);
await Expect.That(values).Contains(x => x == 1).Exactly(3.Times());
await Expect.That(values).DoesNotContain(x => x >= 42);

Subset

You can verify that a collection contains another collection as a subset:

IEnumerable<int> values = Enumerable.Range(1, 3);

await Expect.That(values).Contains([1, 2]);
await Expect.That(values).Contains([3, 2]).InAnyOrder();
await Expect.That(values).Contains([1, 1, 2, 2]).IgnoringDuplicates();
await Expect.That(values).Contains([3, 3, 1, 1]).InAnyOrder().IgnoringDuplicates();
await Expect.That(values).Contains([1, 3]).IgnoringInterspersedItems();

Without InAnyOrder the values must appear in the subject in the same order and contiguous, i.e. without other items in between, so [1, 3] is not contained in [1, 2, 3] unless IgnoringInterspersedItems is used.

To check for a proper subset, append .Properly() (which would fail for equal collections). The negation is DoesNotContain.

Superset

You can verify that a collection is contained in another collection (the other collection is a superset):

IEnumerable<int> values = Enumerable.Range(1, 3);

await Expect.That(values).IsContainedIn([1, 2, 3, 4]);
await Expect.That(values).IsContainedIn([4, 3, 2, 1]).InAnyOrder();
await Expect.That(values).IsContainedIn([1, 1, 2, 2, 3, 3, 4, 4]).IgnoringDuplicates();
await Expect.That(values).IsContainedIn([1, 4, 2, 3]).IgnoringInterspersedItems();
await Expect.That(values).IsNotContainedIn([1, 2]);

Without InAnyOrder the values must appear in the expected collection in the same order and contiguous, i.e. without other items in between, so [1, 3] is not contained in [1, 2, 3] unless IgnoringInterspersedItems is used.

To check for a proper superset, append .Properly() (which would fail for equal collections). The negation is IsNotContainedIn.

Start / end

You can verify if a collection starts or ends with other items or not:

IEnumerable<string> songs = ["Come Together", "Something", "Let It Be"];

await Expect.That(songs).StartsWith("Come Together", "Something");
await Expect.That(songs).EndsWith("Let It Be");
await Expect.That(songs).DoesNotStartWith("Let It Be");
await Expect.That(songs).DoesNotEndWith("Something");

note

EndsWith and DoesNotEndWith always enumerate the complete collection.

Comparing items

The expectations on this page compare the items with the expected items by their default equality, unless you specify a custom comparer, equivalency, a tolerance or, for strings, one of the string options:

IEnumerable<Album> albums = //...
Album expected = //...

await Expect.That(albums).Contains(expected).Equivalent();
await Expect.That(albums).StartsWith(expected).Using(new AlbumComparer());
await Expect.That(["COME TOGETHER", "SOMETHING"]).EndsWith(["something"]).IgnoringCase();

The rules for sets with a custom comparer apply as well.