SweetAssert 1.0.0

SweetAssert

Fluent, chainable assertions for xUnit v3, built on C# 14 extension members.

SweetAssert wraps Xunit.Assert in a small fluent surface so assertions read left-to-right and chain:

using SweetAssert;
using Xunit;

Assert.That("Hello, world")
    .StartsWith("Hello")
    .Contains("world")
    .DoesNotContain("goodbye");

Every call returns the same Asserter<T>, and each assertion delegates straight to the matching Xunit.Assert method, so failures still throw the underlying xUnit exception — you keep xUnit's messages, runners, and tooling.

Requirements

• .NET SDK 10 or later (C# 14 / extension members)
• xUnit v3 (xunit.v3.assert)

The library targets netstandard2.0, so it can be consumed from any test project on a modern toolchain.

Install

Not published as a package yet. Reference the project directly:

<ProjectReference Include="../SweetAssert/SweetAssert.csproj" />

Usage

Assert.That(...)

AssertThat adds a static That member to Xunit.Assert:

Assert.That(order.Total).InRange(10m, 100m);
Assert.That(name).Equal("Ada");

An optional IComparer<T> is remembered on the Asserter<T> and used as the default for range checks:

Assert.That(version, SemVerComparer.Instance)
    .InRange(lowerBound, upperBound);

Intrusive style

using SweetAssert.Intrusive; adds an .Assert property to every value:

using SweetAssert.Intrusive;

result.Assert.Equal(expected);
"café".Assert.Contains("f");

Import it only in the files where you want it.

Assert.ThatSequence(...)

Collections use a separate entry point so the element type is inferred and lambdas work without annotation (Assert.That(collection) would bind to the collection's concrete type, which the sequence assertions can't attach to):

Assert.ThatSequence(new[] { 1, 2, 3 })
    .NotEmpty()
    .Distinct()
    .Contains(x => x > 2)
    .DoesNotContain(0);

Assert.ThatSequence(orders)
    .Single(o => o.IsPriority)   // returns Asserter<Order>
    .Equal(expectedPriorityOrder);

Single() / Single(predicate) return an Asserter<T> for the single element, so you can keep chaining scalar assertions on it.

Assert.ThatAction(...)

Wraps a delegate so the throw assertions can invoke it and hand you the caught exception as an Asserter<TException> to chain on:

var ex = Assert.ThatAction(() => Parse(input)).Throws<FormatException>();

Assert.ThatAction(() => account.Withdraw(-1))
    .Throws<ArgumentOutOfRangeException>(e => e.ParamName == "amount");

await Assert.ThatAction(() => client.SendAsync(request))
    .Throws<HttpRequestException>();

Overloads accept Action, Func<object?> (property getters), and Func<Task>; the Func<Task> overload's assertions return Task<Asserter<TException>>, so await the call. Throws<T> / ThrowsAny<T> take an optional Func<TException, bool> predicate the caught exception must satisfy.

Type assertions

IsType / IsAssignableFrom hang off Assert.That(...) directly and narrow the asserter to the checked type:

var result = Assert.That(response).IsType<OkObjectResult>();   // Asserter<OkObjectResult>
Assert.That(result.Value.StatusCode).Equal(200);

Assert.That(handler).IsAssignableFrom<IDisposable>();
Assert.That(value).IsNotType<string>();

IsNotType / IsNotAssignableFrom return the receiver (as IValueAsserter) so you can stack further type checks; the narrowing ones flow into every other assertion.

Equivalence

Equivalent compares by public structure (xUnit's Assert.Equivalent), so the expected side can be a partial DTO or anonymous type:

Assert.That(response).Equivalent(new { Status = "ok", Items = 3 });
Assert.That(response).Equivalent(new { Status = "ok" }, strict: true);   // fails: extra members
Assert.That(order).Equivalent(o => o.Total == expectedTotal);            // predicate form
Assert.That(snapshot).NotEquivalent(previousSnapshot);

Assertions

String Contains / DoesNotContain default to StringComparison.Ordinal. IEnumerable<T> assertions are reached via Assert.ThatSequence(...), delegate assertions via Assert.ThatAction(...); sequence equality is already covered by Assert.That(seq).Equal(other).

Full reference per family is in docs/.

Build and test

dotnet build
dotnet run --project SweetAssert.Tests

Status

Early and experimental. The assertion surface is partial and the API may change.

Project layout

SweetAssert/
  AssertThat.cs                   Assert.That / ThatSequence / ThatAction entry points
  Asserter.cs                     carrier types (value + comparer / delegate)
  AssertNull.cs                   IsNull / IsNotNull
  AssertSame.cs                   Same / NotSame (reference identity)
  AssertBoolean.cs                IsTrue / IsFalse (bool and bool?)
  AssertString.cs                 string assertions
  AssertIComparable.cs            range assertions
  AssertIEqualityComparable.cs    equality assertions
  AssertTolerance.cs              numeric / temporal precision & tolerance Equal
  AssertEquivalent.cs             structural-equivalence assertions
  AssertEnumerable.cs             IEnumerable<T> assertions
  AssertThrows.cs                 delegate / throw assertions
  AssertType.cs                   runtime-type assertions (IsType, IsAssignableFrom, …)
  Intrusive/IntrusiveAssert.cs    .Assert extension property
SweetAssert.Tests/                xUnit v3 test project
docs/                             per-family reference (start at docs/README.md)