How aweXpect works

Describes the concepts that all expectations share.

Page	Topics
Negation	negated counterparts of expectations
Combining expectations	And, Or, members, new and different subjects, using the result
null subjects	how expectations and their negations treat a null subject
Options	Because, string options, comparers, equivalency, tolerance
Time and cancellation	timeouts, cancellation, waiting, execution time
Configuration	customization lifetimes, global defaults, formatting, settings
Native AOT and trimming	equivalency and events under Native AOT and trimming
Test frameworks	Fail, Skip, the exceptions per test framework

Anatomy of an expectation

Every expectation starts with Expect.That(subject), continues with what you expect and is awaited:

string title = "Let It Be";

await Expect.That(title).StartsWith("Abbey").Because("it is the album title");

A failure throws an exception that fails the test, usually the assertion exception of your test framework, with a message that reads like a sentence. The expectation above fails with:

Failure message

Expected that title
starts with "Abbey", because it is the album title,
but it was "Let It Be", which differs at index 0:
   ↓ (actual)
  "Let It Be"
  "Abbey"
   ↑ (expected prefix)

• The first line names the subject with the expression you passed to Expect.That.
• The second line states the expectation, followed by the reason from Because(…).
• The line starting with "but" describes what was found instead.

Evaluated when awaited

Every expectation is lazy: it is only evaluated when it is awaited. An expectation that is not awaited never fails, so only the second line can fail the test:

Expect.That(result).IsTrue();          // never evaluated
await Expect.That(result).IsTrue();    // evaluated, fails when result is false

The analyzer rule aweXpect0001 reports an expectation that is neither awaited nor verified, and aweXpect0005 reports an expectation in an async void method or lambda, whose failure would be thrown after the test has completed.

Awaiting an expectation also returns the value it verified, see combining.

When you cannot await

ref struct values such as Span<T> can't be used in an async method. To verify one of their properties in a synchronous test, e.g. on a target framework that can't pass spans to Expect.That, use:

using aweXpect.Synchronous;

ReadOnlySpan<char> title = "Let It Be".AsSpan();

Expect.That(title.Length).IsEqualTo(9).VerifySynchronously();
// or alternatively:
Synchronously.Verify(Expect.That(title.Length).IsEqualTo(9));

warning

Only use this where awaiting is impossible: it blocks the thread until the expectation is evaluated.