Skip to main content

Getting started

Requirements​

.NET Framework 4.8 or .NET 6 or later

aweXpect supports test projects on .NET Framework 4.8 and on .NET 6 or later; some features need .NET 8 or later, see target frameworks.

Install the package​

dotnet add package aweXpect --prerelease

Latest version: 4.0.0-pre.3

This documentation describes aweXpect v4, which is available as a pre-release, so the snippets above install the latest pre-release. Without --prerelease or a pre-release version you get v3, which lacks some of the APIs described here.

Add the following using directives: the first brings the static Expect class and lots of extension methods into scope, the second lets you write That(...) instead of Expect.That(...):

using aweXpect;
using static aweXpect.Expect;
note

The samples in this documentation write durations like 5.Seconds() with the aweXpect.Chronology package, marked with the comment // from the aweXpect.Chronology package; TimeSpan.FromSeconds(5) works as well.

Write your first test​

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

MusicLibraryTests.cs
using aweXpect;
using static aweXpect.Expect;

public class MusicLibraryTests
{
    [Test]
    public async Task Contains_WhenAlbumIsMissing_ShouldReturnFalse()
    {
        MusicLibrary sut = new();

        bool result = sut.Contains("Unknown Album");

        await That(result).IsFalse();
    }
}

That is a member of the static Expect class. With using static aweXpect.Expect;, or a global using static aweXpect.Expect; anywhere in your test project, you can write That(...); without it, write Expect.That(...). All examples in this documentation assume the static using and write That(...).

warning

An expectation is only evaluated when it is awaited: without await it never fails. The analyzer aweXpect0001 reports a missing await as an error.

If it fails, it throws an exception that fails the test with the following message:

Failure message
Expected that result
is False,
but it was True

Add a reason​

You can add a reason for all expectations that will be included in the exception message:

await That(result).IsFalse().Because("the album is not in the library");

The reason then appears in the failure message:

Failure message
Expected that result
is False, because the album is not in the library,
but it was True

Find the expectation you need​

The expectations are grouped by the type of the subject:

What you testWhere to look
bool, numbers, string, char, enums, Guid, Version, Stream, TimeSpan, DateTime, DateOnly, TimeOnly, any object, equivalencyValues
IEnumerable<T>, arrays, dictionariesCollections
delegates and exceptions, Task, events, callbacksBehavior
JSON, XML, HTTP, Uri, IPAddress, reflection, snapshotsExtension packages
fail, skip or end a test without an expectation: Fail, SkipTest frameworks

Next steps​

  • How it works explains how expectations are evaluated, negated and combined, how they treat null, the options they share and how to configure their defaults.
  • Setup and integration covers the test frameworks, the target frameworks and Native AOT.
  • Extending aweXpect shows how to add expectations for your own types.