aweXpect

Assert unit tests in natural language using awesome expectations.

await Expect.That(message).IsEqualTo("It's a compliment");

Expected that message
is equal to "It's a compliment",
but it was "It's a complement", which differs at index 12:
           ↓ (actual)
  "…a complement"
  "…a compliment"
           ↑ (expected)

Getting started

1. Install the aweXpect nuget package

   dotnet add package aweXpect

2. Add the following using statement:

   using aweXpect;

   This brings the static Expect class and lots of extension methods into scope.

3. See the documentation or the migration guide for more information.

Features

Async everything

By using async assertions per default, we have a consistent API and other perks:

• Complete async support, e.g. IAsyncEnumerable, HttpResponseMessage (via aweXpect.Web) or similar async types
• No need to distinguish between action.Throws() and await asyncAction.ThrowsAsync()
• The evaluation is only triggered after the complete fluent chain is loaded, which has some nice benefits:
  • Because is applied once at the end of the expectation instead of being a parameter of every method
  • WithCancellation can also be registered at the end and applies a CancellationToken to all async methods which allows cancellation of IAsyncEnumerable evaluations
  • Expectations can be combined directly (via Expect.ThatAll) instead of relying on global state (e.g. assertion scopes)

Performant

A focus on performance allows you to execute your tests as fast as possible.
Special care is taken for the happy case (succeeding tests) to be as performant as possible. See the benchmarks for more details.

Any runner

xUnit, NUnit, MSTest and TUnit are detected automatically: a failed expectation usually throws the assertion exception of the test framework. Fail and Skip fail or skip a test without an expectation. The supported versions and more information can be found in the test frameworks guide.

Native AOT and trimming

aweXpect and aweXpect.Core are trimmable and AOT compatible on .NET 8 and later, see the Native AOT guide.

Extensible

We added lots of extensibility points to allow you to build custom extensions.
The aweXpect.Core package is intended to be a stable source for extensions, so that the risk of version conflicts between different extensions can be reduced.

You can extend the functionality for any types, by adding extension methods on IThat<TType>. More information can be found in the extensibility guide.

Extension packages

Expectations for types outside the base class library are provided by separate packages. See the extension packages in the documentation for an overview.

Core extensions live in the aweXpect repository and are released together with aweXpect, always with the same version. Separate extensions have their own repository and release cycle.

Package	Version	Release	Expectations
aweXpect.Json		core	JSON strings, JsonElement, JsonNode and the JSON serialization of objects: IsEqualTo(…).AsJson(), IsValidJson, Matches, HasProperty, IsObject, IsArray, IsJsonSerializable, IsJsonSerializedAs
aweXpect.Xml		core	XML strings, XElement and XDocument: IsEqualTo(…).AsXml(), IsValidXml, Matches, HasAttribute, HasElement
aweXpect.Web		core	HttpRequestMessage, HttpResponseMessage, Uri and IPAddress: HasMethod, HasRequestUri, HasStatusCode, HasHeader, HasContent, HasHost, HasQueryParameter
aweXpect.Reflection		core	assemblies, types and members, for architecture and convention tests
aweXpect.Snapshots		core	strings, objects and public APIs compared with a reviewed snapshot stored next to the test: MatchesSnapshot, MatchesPublicApiSnapshot
aweXpect.Logging		separate	the records of a FakeLogger or FakeLogCollector: Logged, LoggedWarning, DidNotLog, WithMessage, Within, Then
aweXpect.Testably		separate	the file and time systems of Testably.Abstractions: HasFile, HasDirectory, timers, watcher events
aweXpect.Mockolate		separate	interactions with Mockolate mocks: Once, Never, AtLeast, Then, AllInteractionsAreVerified