Skip to main content

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.

Before (FluentAssertions)
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*");
aweXpectM002Migration available.

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 constructRewritten toNote
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.

Before (FluentAssertions)
double rating = // ...
DateTime releaseDate = // ...
DateTime expected = // ...

rating.Should().BeApproximately(4.5, 0.1);
releaseDate.Should().BeCloseTo(expected, TimeSpan.FromDays(1));
aweXpectM002Migration available.

Equivalency​

Should().BeEquivalentTo(...) and Should().NotBeEquivalentTo(...) dispatch on the called overload and the type of the expected items:

SubjectBeEquivalentTo(expected) rewrites to
stringIsEqualTo(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 objectIsEquivalentTo(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 optionAppended 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.

Before (FluentAssertions)
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 });
aweXpectM002Migration available.

Null and emptiness​

FluentAssertions constructRewritten toNote
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()
Before (FluentAssertions)
string[] bonusTracks = // ...
string[] tracks = // ...

bonusTracks.Should().BeNullOrEmpty();
tracks.Should().NotBeNullOrEmpty();
aweXpectM002Migration available.

Booleans​

FluentAssertions constructRewritten 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 constructRewritten 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.

Before (FluentAssertions)
Exception error = // ...

error.Should().BeAssignableTo<ArgumentException>();
error.Should().BeOfType<ArgumentNullException>();
aweXpectM002Migration available.

Numbers​

FluentAssertions constructRewritten toNote
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
Before (FluentAssertions)
int rating = // ...

rating.Should().BeInRange(1, 5);
aweXpectM002Migration available.

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 constructRewritten toNote
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(...).

Before (FluentAssertions)
string[] tracks = // ...
string[] favorites = // ...

tracks.Should().Contain(favorites);
tracks.Should().ContainInOrder("Something", "Octopus's Garden");
aweXpectM002Migration available.

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 occurrenceAppended to the rewriteNote
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)
Before (FluentAssertions)
string lyrics = // ...

lyrics.Should().Contain("love", AtLeast.Twice());
lyrics.Should().Contain("yesterday", Exactly.Once());
lyrics.Should().Contain("help", AtMost.Thrice());
aweXpectM002Migration available.

Collections​

In addition to the containment and ordering assertions above, these collection-specific forms are recognized:

FluentAssertions constructRewritten toNote
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 optionAppended 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.

Before (FluentAssertions)
string[] genres = // ...
Exception[] errors = // ...

genres.Should().AllBeEquivalentTo("rock", o => o.IgnoringCase());
errors.Should().AllBeOfType<ArgumentException>();
aweXpectM002Migration available.

Object equivalency​

FluentAssertions constructRewritten toNote
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 constructRewritten toNote
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)
Before (FluentAssertions)
Action addTrack = // ...

addTrack.Should().Throw<ArgumentException>().WithMessage("*track number*");
aweXpectM002Migration available.

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 constructRewritten toNote
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.

Before (FluentAssertions)
DateTime releaseDate = // ...

releaseDate.Should().HaveYear(1969);
releaseDate.Should().NotHaveMonth(1);
aweXpectM002Migration available.

Enums and nullable values​

FluentAssertions constructRewritten toNote
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:

Before (FluentAssertions)
bool isPlaying = // ...

Action verify = () => isPlaying.Should().BeTrue();
aweXpectM002Migration available.

Because messages​

A trailing because argument on any of the assertions above is preserved as a .Because(...) suffix, including formatted overloads:

Before (FluentAssertions)
int trackCount = // ...
string album = // ...

trackCount.Should().Be(17, "{0} has 17 tracks", album);
aweXpectM002Migration available.

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.