FluentAssertions
The code fix of aweXpectM002 rewrites the entire .Should() chain in one step: the Should() call is dropped, Expect.That(subject) becomes the new root, the assertion methods are renamed, any trailing because argument is moved into a .Because(...) suffix, and .And chains are preserved.
string title = // ...
string[] tracks = // ...
int playCount = // ...
double rating = // ...
DateTime releaseDate = // ...
Action play = // ...
title.Should().NotBeNullOrEmpty();
title.Should().StartWith("Abbey", "the album title was set");
tracks.Should().HaveCount(17).And.Contain("Come Together");
tracks.Should().ContainInOrder("Something", "Octopus's Garden");
tracks.Should().OnlyHaveUniqueItems();
playCount.Should().BeGreaterThan(0);
rating.Should().BeApproximately(4.5, 0.1);
releaseDate.Should().HaveYear(1969);
play.Should().Throw<InvalidOperationException>().WithMessage("*no tracks*");
The examples show the code as the code fix writes it; the await is added in a second step.
The tables below are grouped by target concept (equality, containment and so on), not by the FluentAssertions documentation pages. Most of the basic assertions (Be, NotBe, BeEmpty, Contain, StartWith and others) are not specific to one subject type; they apply to any compatible subject.
A chain that continues on a second .Should(), e.g. after .Which, is left for manual migration, as is any call the code fix cannot translate without losing an argument (see Manual review).
A note in the last column marks a rewrite that behaves differently in some cases; it links to the matching entry on Behavioral differences from FluentAssertions.
Equality
| FluentAssertions construct | Rewritten to | Note |
|---|---|---|
subject.Should().Be(expected) | Expect.That(subject).IsEqualTo(expected) | DateTime kind |
subject.Should().NotBe(unexpected) | Expect.That(subject).IsNotEqualTo(unexpected) | DateTime kind |
subject.Should().BeApproximately(expected, tolerance) | Expect.That(subject).IsEqualTo(expected).Within(tolerance) | NaN |
subject.Should().NotBeApproximately(expected, tolerance) | Expect.That(subject).IsNotEqualTo(expected).Within(tolerance) | NaN |
subject.Should().BeCloseTo(expected, delta) | Expect.That(subject).IsEqualTo(expected).Within(delta) | integral deltas, DateTime kind |
subject.Should().NotBeCloseTo(expected, delta) | Expect.That(subject).IsNotEqualTo(expected).Within(delta) | integral deltas, DateTime kind |
subject.Should().BeOneOf(a, b, c) | Expect.That(subject).IsOneOf(a, b, c) | mixed number types, DateTime kind |
subject.Should().BeOneOf(collection) | Expect.That(subject).IsOneOf(collection) | mixed number types, empty expectations, DateTime kind |
subject.Should().BeSameAs(expected) | Expect.That(subject).IsSameAs(expected) | |
subject.Should().NotBeSameAs(unexpected) | Expect.That(subject).IsNotSameAs(unexpected) |
For an integral subject, FluentAssertions takes the delta of BeCloseTo as the unsigned counterpart of the subject type (uint for int). When the delta does not convert implicitly, the code fix casts it to the subject type, e.g. Within((int)delta). A constant delta that does not fit the subject type, such as uint.MaxValue for an int, is left for manual migration.
Be, NotBe and BeOneOf with an IEqualityComparer<T> are left for manual migration as well. FluentAssertions fails for a subject that is not a T, such as null, without calling the comparer, whereas Using(comparer) in aweXpect passes every subject to the comparer.
double rating = // ...
DateTime releaseDate = // ...
DateTime expected = // ...
rating.Should().BeApproximately(4.5, 0.1);
releaseDate.Should().BeCloseTo(expected, TimeSpan.FromDays(1));
Equivalency
Should().BeEquivalentTo(...) and Should().NotBeEquivalentTo(...) dispatch on the called overload and the type of the expected items:
| Subject | BeEquivalentTo(expected) rewrites to |
|---|---|
string | IsEqualTo(expected).IgnoringCase() |
| collection of items that are compared by value (see below) | IsEqualTo(expected).InAnyOrder() |
| object that is compared by value (see below) | IsEqualTo(expected) |
| any other collection, and any other object | IsEquivalentTo(expected, o => o.IgnoringCollectionOrder()) |
Items are compared by value when FluentAssertions compares them with Equals as well: primitives, enums, strings, structs and classes that override Equals, but not records and anonymous types. All other items are compared structurally, like FluentAssertions does. FluentAssertions also ignores the order of nested collections, which IgnoringCollectionOrder() restores; the code fix adds using aweXpect.Equivalency; for it when necessary. With o => o.WithStrictOrdering() the rewrite omits InAnyOrder() and IgnoringCollectionOrder().
Unlike a single string, the strings in a collection are compared case-sensitively, as in FluentAssertions. The expected strings can also be listed one by one: BeEquivalentTo("Something", "Come Together") rewrites to IsEqualTo(["Something", "Come Together"]).InAnyOrder(). Without any expected string (BeEquivalentTo() or BeEquivalentTo([])) no code fix is offered.
For string subjects and collections of items that are compared by value, the o => o... options are translated as well. As in FluentAssertions, a string compared with options ignores case only when the options contain IgnoringCase():
| FluentAssertions option | Appended to the rewrite |
|---|---|
o => o.IgnoringCase() | .IgnoringCase() |
o => o.IgnoringLeadingWhitespace() | .IgnoringLeadingWhiteSpace() |
o => o.IgnoringTrailingWhitespace() | .IgnoringTrailingWhiteSpace() |
o => o.IgnoringNewlineStyle() | .IgnoringNewlineStyle() |
For these, the code fix translates only an o => o... lambda that chains the options above, WithStrictOrdering() and WithoutStrictOrdering(). For structural comparisons and objects that are compared by value, options other than WithStrictOrdering() and WithoutStrictOrdering() have no automatic translation. Any other option, such as Using<T>(...), or options that are not passed as such a lambda, would be lost in the rewrite, so no code fix is offered. NotBeEquivalentTo is translated symmetrically (IsNotEqualTo / IsNotEquivalentTo). See also Structural equivalency under the behavioral differences.
string title = // ...
string[] tracks = // ...
string[] expected = // ...
object album = // ...
title.Should().BeEquivalentTo("abbey road");
tracks.Should().BeEquivalentTo(expected);
album.Should().BeEquivalentTo(new { Title = "Abbey Road", Year = 1969 });
Null and emptiness
| FluentAssertions construct | Rewritten to | Note |
|---|---|---|
subject.Should().BeNull() | Expect.That(subject).IsNull() | |
subject.Should().NotBeNull() | Expect.That(subject).IsNotNull() | |
subject.Should().BeEmpty() | Expect.That(subject).IsEmpty() | |
subject.Should().NotBeEmpty() | Expect.That(subject).IsNotEmpty() | null subjects |
subject.Should().BeNullOrEmpty() (string) | Expect.That(subject).IsNullOrEmpty() | |
subject.Should().BeNullOrEmpty() (collection) | Expect.That(subject).IsNull().Or.IsEmpty() | |
subject.Should().NotBeNullOrEmpty() (string) | Expect.That(subject).IsNotNullOrEmpty() | |
subject.Should().NotBeNullOrEmpty() (collection) | Expect.That(subject).IsNotEmpty() | |
subject.Should().BeNullOrWhiteSpace() | Expect.That(subject).IsNullOrWhiteSpace() | |
subject.Should().NotBeNullOrWhiteSpace() | Expect.That(subject).IsNotNullOrWhiteSpace() |
string[] bonusTracks = // ...
string[] tracks = // ...
bonusTracks.Should().BeNullOrEmpty();
tracks.Should().NotBeNullOrEmpty();
Booleans
| FluentAssertions construct | Rewritten to |
|---|---|
subject.Should().BeTrue() | Expect.That(subject).IsTrue() |
subject.Should().BeFalse() | Expect.That(subject).IsFalse() |
subject.Should().NotBeTrue() | Expect.That(subject).IsNotTrue() |
subject.Should().NotBeFalse() | Expect.That(subject).IsNotFalse() |
subject.Should().Imply(other) | Expect.That(subject).Implies(other) |
Type checks
The generic forms (<T>) and the non-generic (typeof(T)) overloads are both supported; the code fix keeps whichever form was used.
| FluentAssertions construct | Rewritten to |
|---|---|
subject.Should().BeAssignableTo<T>() | Expect.That(subject).Is<T>() |
subject.Should().BeAssignableTo(typeof(T)) | Expect.That(subject).Is(typeof(T)) |
subject.Should().NotBeAssignableTo<T>() | Expect.That(subject).IsNot<T>() |
subject.Should().NotBeAssignableTo(typeof(T)) | Expect.That(subject).IsNot(typeof(T)) |
subject.Should().BeOfType<T>() | Expect.That(subject).IsExactly<T>() |
subject.Should().BeOfType(typeof(T)) | Expect.That(subject).IsExactly(typeof(T)) |
subject.Should().NotBeOfType<T>() | Expect.That(subject).IsNotExactly<T>() |
subject.Should().NotBeOfType(typeof(T)) | Expect.That(subject).IsNotExactly(typeof(T)) |
On a System.Type subject, BeAssignableTo and NotBeAssignableTo are not rewritten; see Assertions on a Type.
Exception error = // ...
error.Should().BeAssignableTo<ArgumentException>();
error.Should().BeOfType<ArgumentNullException>();
Numbers
| FluentAssertions construct | Rewritten to | Note |
|---|---|---|
subject.Should().BePositive() | Expect.That(subject).IsPositive() | |
subject.Should().BeNegative() | Expect.That(subject).IsNegative() | |
subject.Should().BeGreaterThan(expected) | Expect.That(subject).IsGreaterThan(expected) | |
subject.Should().BeGreaterThanOrEqualTo(expected) | Expect.That(subject).IsGreaterThanOrEqualTo(expected) | |
subject.Should().BeGreaterOrEqualTo(expected) (legacy FluentAssertions 7) | Expect.That(subject).IsGreaterThanOrEqualTo(expected) | |
subject.Should().BeLessThan(expected) | Expect.That(subject).IsLessThan(expected) | |
subject.Should().BeLessThanOrEqualTo(expected) | Expect.That(subject).IsLessThanOrEqualTo(expected) | |
subject.Should().BeLessOrEqualTo(expected) (legacy FluentAssertions 7) | Expect.That(subject).IsLessThanOrEqualTo(expected) | |
subject.Should().BeInRange(low, high) | Expect.That(subject).IsBetween(low).And(high) | reversed ranges |
subject.Should().NotBeInRange(low, high) | Expect.That(subject).IsNotBetween(low).And(high) | reversed ranges |
int rating = // ...
rating.Should().BeInRange(1, 5);
Containment, ordering and predicates
These cover both string and collection subjects; the code fix dispatches on the called overload where it matters, so an item that is itself a collection is still treated as a single item.
| FluentAssertions construct | Rewritten to | Note |
|---|---|---|
subject.Should().Contain(expected) | Expect.That(subject).Contains(expected) | |
subject.Should().Contain(item).And.Contain(other) | Expect.That(subject).Contains(item).And.Contains(other) | |
subject.Should().Contain(collection) | Expect.That(subject).Contains(collection).InAnyOrder().IgnoringDuplicates() | |
subject.Should().NotContain(unexpected) | Expect.That(subject).DoesNotContain(unexpected) | null subjects |
subject.Should().NotContain(collection) | Expect.That(subject).None().ComplyWith(x => x.IsOneOf(collection)) | mixed number types |
subject.Should().StartWith(expected) | Expect.That(subject).StartsWith(expected) | empty expectations |
subject.Should().NotStartWith(unexpected) | Expect.That(subject).DoesNotStartWith(unexpected) | empty expectations |
subject.Should().EndWith(expected) | Expect.That(subject).EndsWith(expected) | empty expectations |
subject.Should().NotEndWith(unexpected) | Expect.That(subject).DoesNotEndWith(unexpected) | empty expectations |
subject.Should().ContainInOrder(collection) | Expect.That(subject).Contains(collection).IgnoringInterspersedItems() | empty expectations |
subject.Should().ContainInOrder(a, b, c) | Expect.That(subject).Contains([a, b, c]).IgnoringInterspersedItems() | |
subject.Should().ContainInConsecutiveOrder(collection) | Expect.That(subject).Contains(collection) | empty expectations |
subject.Should().ContainInConsecutiveOrder(a, b, c) | Expect.That(subject).Contains([a, b, c]) | |
subject.Should().ContainEquivalentOf(expected) | Expect.That(subject).Contains(expected).Equivalent(o => o.IgnoringCollectionOrder()) | structural equivalency |
subject.Should().NotContainEquivalentOf(unexpected) | Expect.That(subject).DoesNotContain(unexpected).Equivalent(o => o.IgnoringCollectionOrder()) | structural equivalency |
subject.Should().BeSubsetOf(expected) | Expect.That(subject).IsContainedIn(expected).InAnyOrder().IgnoringDuplicates() | |
subject.Should().NotBeSubsetOf(expected) | Expect.That(subject).IsNotContainedIn(expected).InAnyOrder() | |
subject.Should().HaveCount(n) | Expect.That(subject).HasCount(n) | |
subject.Should().ContainSingle() | Expect.That(subject).HasSingle() | |
subject.Should().ContainSingle(predicate) | Expect.That(subject).HasSingle().Matching(predicate) | |
subject.Should().OnlyContain(predicate) | Expect.That(subject).All().Satisfy(predicate) | |
subject.Should().OnlyHaveUniqueItems() | Expect.That(subject).All().AreUnique() | |
subject.Should().BeInAscendingOrder() | Expect.That(subject).IsInAscendingOrder() | |
subject.Should().BeInAscendingOrder(comparer) | Expect.That(subject).IsInAscendingOrder().Using(comparer) | |
subject.Should().BeInAscendingOrder(x => x.Key) | Expect.That(subject).IsInAscendingOrder(x => x.Key) | |
subject.Should().BeInDescendingOrder() | Expect.That(subject).IsInDescendingOrder() | |
subject.Should().NotBeInAscendingOrder() / NotBeInDescendingOrder() | Expect.That(subject).IsNotInAscendingOrder() / IsNotInDescendingOrder() | |
subject.Should().Match(predicate) (non-string subject) | Expect.That(subject).Satisfies(predicate) | |
subject.Should().Match(pattern) (string subject) | Expect.That(subject).IsEqualTo(pattern).AsWildcard() | empty patterns |
For items that are compared by value (see Equivalency), ContainEquivalentOf and NotContainEquivalentOf are rewritten to Contains(expected) and DoesNotContain(unexpected) without Equivalent(). With o => o.WithStrictOrdering() they use Equivalent() without options.
Items passed one by one to ContainInOrder or ContainInConsecutiveOrder become a collection expression, also a single item: ContainInOrder(a) is rewritten to Contains([a]).IgnoringInterspersedItems().
The ordering assertions with a comparison delegate, such as BeInAscendingOrder((a, b) => a.CompareTo(b)), are left for manual migration, because Using in aweXpect takes an IComparer<T>. Wrap the delegate in Comparer<T>.Create(...).
string[] tracks = // ...
string[] favorites = // ...
tracks.Should().Contain(favorites);
tracks.Should().ContainInOrder("Something", "Octopus's Garden");
Occurrence constraints on Contain (string subjects)
Should().Contain(expected, occurrence) translates the full FluentAssertions occurrence family. The Thrice and Times(n) cases are emitted as numeric arguments, not as a chained .Thrice(). Occurrences are counted without overlap.
| FluentAssertions occurrence | Appended to the rewrite | Note |
|---|---|---|
AtLeast.Once() | .AtLeast().Once() | |
AtLeast.Twice() | .AtLeast().Twice() | |
AtLeast.Thrice() | .AtLeast(3) | |
AtLeast.Times(n) | .AtLeast(n) | |
AtMost.Once() | .AtMost().Once() | null subjects |
AtMost.Twice() | .AtMost().Twice() | null subjects |
AtMost.Thrice() | .AtMost(3) | null subjects |
AtMost.Times(n) | .AtMost(n) | null subjects |
Exactly.Once() | .Once() | |
Exactly.Twice() | .Twice() | |
Exactly.Thrice() | .Exactly(3) | |
Exactly.Times(n) | .Exactly(n) | |
LessThan.Twice() | .LessThan().Twice() | null subjects |
LessThan.Thrice() | .LessThan(3) | null subjects |
LessThan.Times(n) | .LessThan(n) | null subjects |
MoreThan.Once() | .MoreThan().Once() | |
MoreThan.Twice() | .MoreThan().Twice() | |
MoreThan.Thrice() | .MoreThan(3) | |
MoreThan.Times(n) | .MoreThan(n) |
string lyrics = // ...
lyrics.Should().Contain("love", AtLeast.Twice());
lyrics.Should().Contain("yesterday", Exactly.Once());
lyrics.Should().Contain("help", AtMost.Thrice());
Collections
In addition to the containment and ordering assertions above, these collection-specific forms are recognized:
| FluentAssertions construct | Rewritten to | Note |
|---|---|---|
subject.Should().AllBeAssignableTo<T>() / (typeof(T)) | Expect.That(subject).All().Are<T>() / All().Are(typeof(T)) | Type items |
subject.Should().AllBeOfType<T>() / (typeof(T)) | Expect.That(subject).All().AreExactly<T>() / All().AreExactly(typeof(T)) | Type items |
subject.Should().AllBeEquivalentTo(expected) (non-string elements) | Expect.That(subject).All().AreEquivalentTo(expected, o => o.IgnoringCollectionOrder()) | structural equivalency |
subject.Should().AllBeEquivalentTo(expected) (IEnumerable<string>) | Expect.That(subject).All().AreEqualTo(expected) |
For elements that are compared by value (see Equivalency), AllBeEquivalentTo is rewritten to All().AreEqualTo(expected); with o => o.WithStrictOrdering() it is rewritten to All().AreEquivalentTo(expected) without the options lambda. For IEnumerable<string> collections, the o => o... options are translated as well:
| FluentAssertions option | Appended to the rewrite |
|---|---|
o => o.IgnoringCase() | .IgnoringCase() |
o => o.IgnoringLeadingWhitespace() | .IgnoringLeadingWhiteSpace() |
o => o.IgnoringTrailingWhitespace() | .IgnoringTrailingWhiteSpace() |
o => o.IgnoringNewlineStyle() | .IgnoringNewlineStyle() |
o => o.WithoutStrictOrdering() | .InAnyOrder() |
Options that are not such a lambda, or any other option, such as Using<T>(...), would be lost in the rewrite, so no code fix is offered.
string[] genres = // ...
Exception[] errors = // ...
genres.Should().AllBeEquivalentTo("rock", o => o.IgnoringCase());
errors.Should().AllBeOfType<ArgumentException>();
Object equivalency
| FluentAssertions construct | Rewritten to | Note |
|---|---|---|
subject.Should().BeEquivalentTo(expected) (arbitrary object) | Expect.That(subject).IsEquivalentTo(expected, o => o.IgnoringCollectionOrder()) | structural equivalency |
subject.Should().NotBeEquivalentTo(unexpected) (arbitrary object) | Expect.That(subject).IsNotEquivalentTo(unexpected, o => o.IgnoringCollectionOrder()) | structural equivalency |
subject.Should().BeEquivalentTo(expected) (object compared by value) | Expect.That(subject).IsEqualTo(expected) | |
subject.Should().NotBeEquivalentTo(unexpected) (object compared by value) | Expect.That(subject).IsNotEqualTo(unexpected) |
Exceptions
| FluentAssertions construct | Rewritten to | Note |
|---|---|---|
callback.Should().NotThrow() / NotThrowAsync() | Expect.That(callback).DoesNotThrow() | |
callback.Should().NotThrow<T>() / NotThrowAsync<T>() | Expect.That(callback).DoesNotThrow<T>() | AggregateException |
callback.Should().Throw<T>() / ThrowAsync<T>() | Expect.That(callback).Throws<T>() | AggregateException |
callback.Should().ThrowExactly<T>() / ThrowExactlyAsync<T>() | Expect.That(callback).ThrowsExactly<T>() | |
callback.Should().ThrowWithinAsync<T>(timeout) | Expect.That(callback).Throws<T>().Within(timeout) | AggregateException |
callback.Should().CompleteWithinAsync(timeout) | Expect.That(callback).ExecutesIn().AtMost(timeout) | canceled tasks |
.WithMessage(pattern) | .WithMessage(pattern).AsWildcard().IgnoringCase().IgnoringNewlineStyle() | empty patterns |
.WithInnerException<T>() / (typeof(T)) | .WithInner<T>() / .WithInner(typeof(T)) | |
.WithParameterName(name) | .WithParamName(name) |
Action addTrack = // ...
addTrack.Should().Throw<ArgumentException>().WithMessage("*track number*");
A chained call without an aweXpect counterpart, such as Where(...) or WithInnerExceptionExactly<T>(), leaves the assertion for manual migration. So does a call chained after WithInnerException, because FluentAssertions continues on the inner exception there, whereas WithInner returns to the outer one.
Dates and times
| FluentAssertions construct | Rewritten to | Note |
|---|---|---|
subject.Should().BeAfter(expected) | Expect.That(subject).IsAfter(expected) | DateTime kind |
subject.Should().BeOnOrAfter(expected) | Expect.That(subject).IsOnOrAfter(expected) | DateTime kind |
subject.Should().BeBefore(expected) | Expect.That(subject).IsBefore(expected) | DateTime kind |
subject.Should().BeOnOrBefore(expected) | Expect.That(subject).IsOnOrBefore(expected) | DateTime kind |
subject.Should().NotBeAfter(unexpected) / NotBeOnOrAfter(...) | Expect.That(subject).IsNotAfter(unexpected) / IsNotOnOrAfter(...) | DateTime kind |
subject.Should().NotBeBefore(unexpected) / NotBeOnOrBefore(...) | Expect.That(subject).IsNotBefore(unexpected) / IsNotOnOrBefore(...) | DateTime kind |
subject.Should().HaveYear(n) (also Month/Day/Hour/Minute/Second/Offset) | Expect.That(subject).HasYear().EqualTo(n) (etc.) | |
subject.Should().NotHaveYear(n) (and the other parts) | Expect.That(subject).HasYear().NotEqualTo(n) (etc.) |
Be, NotBe, BeCloseTo, NotBeCloseTo and BeOneOf on dates are listed under Equality; the kind of a DateTime matters there as well.
DateTime releaseDate = // ...
releaseDate.Should().HaveYear(1969);
releaseDate.Should().NotHaveMonth(1);
Enums and nullable values
| FluentAssertions construct | Rewritten to | Note |
|---|---|---|
subject.Should().BeDefined() | Expect.That(subject).IsDefined() | |
subject.Should().NotBeDefined() | Expect.That(subject).IsNotDefined() | |
subject.Should().HaveFlag(flag) | Expect.That(subject).HasFlag(flag) | |
subject.Should().NotHaveFlag(flag) | Expect.That(subject).DoesNotHaveFlag(flag) | null subjects |
subject.Should().HaveValue() (Nullable<T>) | Expect.That(subject).IsNotNull() | |
subject.Should().HaveValue(v) | Expect.That(subject).HasValue(v) | |
subject.Should().NotHaveValue() | Expect.That(subject).IsNull() | |
subject.Should().NotHaveValue(v) | Expect.That(subject).HasValue().NotEqualTo(v) | null subjects |
Lambda assertions
When the entire .Should() chain is the body of a lambda (so it is not awaited at the call site and the surrounding signature is Action or Func<T>), the code fix wraps the rewritten expression in aweXpect.Synchronous.Synchronously.Verify(...) to keep the lambda synchronous:
bool isPlaying = // ...
Action verify = () => isPlaying.Should().BeTrue();
Because messages
A trailing because argument on any of the assertions above is preserved as a .Because(...) suffix, including formatted overloads:
int trackCount = // ...
string album = // ...
trackCount.Should().Be(17, "{0} has 17 tracks", album);
Behavioral differences
A few rewrites pass or fail for different inputs than the original FluentAssertions assertion, by a deliberate choice of aweXpect. Each case is listed with an example and a way to restore the original behavior on Behavioral differences from FluentAssertions.