aweXpect

Assert unit tests in natural language using awesome expectations.

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 can be registered once as a general method that can be applied at the end of the expectation instead of cluttering all methods with the because and becauseArgs parameters
  • 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 (v2 and v3), NUnit (v3, v4 and v5), 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. More information can be found in the test frameworks guide.

Native AOT and trimming

aweXpect and aweXpect.Core are trimmable and AOT compatible for net8.0 and later, so your test project can be published with Native AOT. Equivalency and event recording work without reflection, because a source generator that ships with the aweXpect.Core package registers the members and events they need when your project is compiled. A comparison or recording of a type the generator could not see fails with an error that tells you how to register it. More information can be found in 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
aweXpect.Xml		core	XML strings, XElement and XDocument
aweXpect.Web		core	HttpRequestMessage, HttpResponseMessage, Uri and IPAddress
aweXpect.Reflection		core	assemblies, types and members, for architecture and convention tests
aweXpect.Snapshots		core	strings and objects compared with a snapshot stored next to the test
aweXpect.Logging		separate	the records of a FakeLogger or FakeLogCollector
aweXpect.Testably		separate	the file and time systems of Testably.Abstractions
aweXpect.Mockolate		separate	interactions with Mockolate mocks