aweXpect.Migration 0.6.0

aweXpect.Migration

A Roslyn analyzer and code-fix provider that migrates FluentAssertions and xUnit assertions to aweXpect. Drop the package into a project that uses one of those libraries and the analyzer flags each assertion it can migrate; the accompanying code fix rewrites the call site to its aweXpect equivalent.

Installation

Install aweXpect (the assertion library you are migrating to) and aweXpect.Migration (the analyzers and code fixers) into the test project you want to migrate:

dotnet add package aweXpect
dotnet add package aweXpect.Migration

aweXpect.Migration ships only the analyzer and code fixer — no runtime code. Once a project no longer references the source assertion library you can remove the aweXpect.Migration reference again; aweXpect itself stays.

It is usually convenient to add the following global usings to the project so the rewritten code compiles without further edits:

global using System.Threading.Tasks;
global using aweXpect;

How it works

After installing the package, every supported assertion is reported as a warning. Apply the relevant code fix from your IDE (Visual Studio, Rider, VS Code with C# Dev Kit) or via dotnet format analyzers to rewrite the call site.

aweXpectM002 is raised on every .Should() invocation defined under the FluentAssertions namespace (nested .Should() inside lambda arguments are intentionally skipped, so chains like .Should().AllSatisfy(x => x.Should().BeGreaterThan(0)) are migrated as a single unit). aweXpectM003 is raised on every method call on Xunit.Assert.

Conditional access on the subject is supported — subject?.Inner?.NewInner()?.Value.Should().Be(x) rewrites to Expect.That(subject?.Inner?.NewInner()?.Value).IsEqualTo(x), preserving the null-propagation chain.

A typical migration looks like this:

// Before
subject.Should().BeTrue();
Assert.Equal(expected, actual);

// After
await Expect.That(subject).IsTrue();
await Expect.That(actual).IsEqualTo(expected);

Most rewritten expressions return a Task and must be awaited — that's enforced by the aweXpect0001 analyzer that ships with aweXpect itself.

From the command line

Migration is a two-pass operation: first apply the rewrites, then add the missing await / async keywords:

# 1. Rewrite assertions
dotnet format analyzers --diagnostics aweXpectM002 aweXpectM003 --severity warn

# 2. Add the missing `await` (and mark surrounding methods `async`)
dotnet format analyzers --diagnostics aweXpect0001 --severity warn

In an IDE the equivalent is "Fix all in solution" for aweXpectM002 / aweXpectM003, then "Fix all" for aweXpect0001.

Migrating from FluentAssertions

The fixer 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, and any trailing because argument is moved into a .Because(...) suffix. .And chains are preserved.

// Before (FluentAssertions)
subject.Should().Contain(1).And.Contain(2, "because foo");

// After (aweXpect)
await Expect.That(subject).Contains(1).And.Contains(2).Because("because foo");

The tables below are grouped by target concept (equality, containment, …), not by FluentAssertions' own documentation pages. Most of the "basic" assertions (Be, NotBe, BeEmpty, Contain, StartWith, …) are not string-specific — they apply to any compatible subject type.

Equality

Should().BeEquivalentTo(...) and Should().NotBeEquivalentTo(...) dispatch on the static type of the subject:

For string subjects the o => o.… options are translated as well (combined with the implicit .IgnoringCase() above):

NotBeEquivalentTo is translated symmetrically (IsNotEqualTo / IsNotEquivalentTo).

Null and emptiness

Booleans

Type checks

The generic forms (<T>) and the non-generic (typeof(T)) overloads are both supported — the fixer keeps whichever form was used.

Numbers

Containment, ordering and predicates

These cover both string and collection subjects; the fixer dispatches on the parameter types where it matters.

Occurrence constraints on Contain (string subjects)

Should().Contain(expected, occurrence) translates the full FluentAssertions occurrence family. Note the Thrice / Times(n) cases — they're emitted as 3.Times() / numeric arguments, not as chained .Thrice():

Collections

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

For IEnumerable<string> collections, the o => o.… options on AllBeEquivalentTo are translated as well:

Object equivalency

Exceptions

// Before
callback.Should().Throw<ArgumentException>().WithMessage("foo*");

// After
await Expect.That(callback).Throws<ArgumentException>().WithMessage("foo*").AsWildcard();

Dates and times

Enums and nullable values

Caveat — HaveValue / NotHaveValue argument heuristic. The fixer inspects the text of the first argument: anything containing a " (i.e. anything that looks like a string literal) is treated as a because message rather than an expected value. As a result, subject.Should().HaveValue("text") rewrites to Expect.That(subject).IsNotNull() instead of HasValue("text"). Review the rewrite when the expected value is itself a string.

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 / Func<T>), the fixer wraps the rewritten expression in aweXpect.Synchronous.Synchronously.Verify(...) to keep the lambda synchronous:

// Before
Action action = () => true.Should().BeTrue();

// After
Action action = () => aweXpect.Synchronous.Synchronously.Verify(Expect.That(true).IsTrue());

Because messages

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

// Before
subject.Should().Be(expected, "because the value is {0}", value);

// After
await Expect.That(subject).IsEqualTo(expected).Because($"because the value is {value}");

Migrating from xUnit

The fixer rewrites each Xunit.Assert.* call into the corresponding Expect.That(actual).<Assertion>(expected) form. The argument order in xUnit (Assert.Equal(expected, actual)) is swapped to match aweXpect's "actual first" convention.

// Before (xUnit)
Assert.Equal(expected, actual);
Assert.Throws<ArgumentException>(callback);

// After (aweXpect)
await Expect.That(actual).IsEqualTo(expected);
await Expect.That(callback).ThrowsExactly<ArgumentException>();

Supported xUnit migrations

Basic

Booleans

Equality

Strings

Collections

Exceptions

Types

The non-generic overloads (Assert.IsType(typeof(T), actual) etc.) are migrated to the matching non-generic aweXpect form.

Removing aweXpect.Migration again

Once the warnings in a project have been resolved, drop the analyzer reference:

dotnet remove package aweXpect.Migration

aweXpect itself stays in the project — that's the assertion library the tests now depend on.