aweXpect.Snapshots 0.2.0

aweXpect.Snapshots

Snapshot testing for aweXpect.

At a glance

// compare a string with the snapshot that is stored next to the test
await Expect.That(description).MatchesSnapshot();

// compare an object, written completely and indented by the aweXpect formatter
await Expect.That(album).MatchesSnapshot();

// replace values that change from run to run before comparing
await Expect.That(playlist).MatchesSnapshot().For.Text(@"plays=\d+").AsRegex().Mask("plays=<count>");

// replace every Guid and ISO 8601 date with a numbered placeholder ({Guid_1}, {Date_1}, …)
await Expect.That(playlist).MatchesSnapshot().For.Guids().Mask().For.Dates().Mask();

// leave out, mask or convert members of an object, selected by their name, type or declaring type
await Expect.That(album).MatchesSnapshot()
    .For.Members().WithName("PlayCount").Ignore()
    .For.Members().WithName("Id").Mask()
    .For.Members().DeclaredIn<Album>().WithName("Released").OfType<DateTime>().Convert(released => released.Year);

// store a JSON string as AlbumTests.Describes.awexpect-snapshot.json, so that editors and diff tools highlight it
await Expect.That(json).MatchesSnapshot().WithExtension("json");

// keep a snapshot per target framework and operating system (AlbumTests.Describes@net8.0@windows.awexpect-snapshot.txt)
await Expect.That(exception.Message).MatchesSnapshot().UniqueFor.TargetFramework().UniqueFor.OperatingSystem();

The snapshot is stored as <Class>.<Method>.awexpect-snapshot.txt next to the test file, where <Class> is the name of the test file. A missing or different snapshot fails the test and writes the actual value to <Class>.<Method>.awexpect-snapshot.pending.txt; rename it to <Class>.<Method>.awexpect-snapshot.txt to accept it, or set the environment variable AWEXPECT_ACCEPT_SNAPSHOTS to all to accept all changed snapshots of a test run (or to new to only add the missing ones). Snapshots of version 0.1 are named .snapshot. instead, see Migrating from 0.1. OrphanedSnapshots.CheckAsync() in the teardown of the test run reports the snapshots that no test uses any more on a build server, and deletes them while accepting all changes. Comparers decide whether a value matches its snapshot instead of the built-in comparison, e.g. an image comparer that tolerates small differences of single pixels. Reporters are told about every missing, different or matching snapshot, e.g. to open a diff tool.

Overview

Documentation

The full documentation is available at docs.testably.org.