Meziantou.Framework.SnapshotTesting 2.1.1

Meziantou.Framework.SnapshotTesting

Meziantou.Framework.SnapshotTesting validates serialized values against snapshot files stored on disk.

Basic usage

public sealed class SampleTests
{
    [Fact]
    public void ValidateUser()
    {
        var value = new { Name = "John", Age = 42 };
        Snapshot.Validate(value);
    }
}

For typed snapshots:

Snapshot.Validate(imageBytes, SnapshotType.Png);
Snapshot.Validate(svgText, SnapshotType.Svg);

For GIF/ICO frame snapshots (opt-in, emitted as PNG snapshots):

var settings = SnapshotSettings.Default with { };
settings.Serializers.AddGifSerializer();
settings.Serializers.AddIcoSerializer();

Snapshot.Validate(gifBytes, SnapshotType.Gif, settings);
Snapshot.Validate(icoBytes, SnapshotType.Ico, settings);

File naming convention

Snapshots are stored in a __snapshots__ directory next to the test source file:

• expected snapshots: *.verified.<extension>
• mismatch output: *.actual.<extension>

Example:

• __snapshots__/SampleTests_ValidateUser.verified.txt
• __snapshots__/SampleTests_ValidateUser.actual.txt

Notes:

• By default, snapshot names include class name and test name to avoid collisions across test classes.
• .actual files are always written when a snapshot does not match.
• If a single assertion serializes multiple files, an index suffix (_0, _1, ...) is appended.
• If names are too long (or already end with .verified / .actual), a stable hash is added.

You can choose how snapshot names are generated using SnapshotSettings.SnapshotNamingStrategy:

• SnapshotNamingStrategies.TestName
• SnapshotNamingStrategies.ClassName_TestName (default)
• SnapshotNamingStrategies.FullName

Approving snapshots

To approve generated *.actual.* files, you can use the dedicated tool package:

dotnet tool install --global Meziantou.Framework.SnapshotTesting.Tool
Meziantou.Framework.SnapshotTesting.Tool approve

Use --interactive to approve or reject snapshots one by one.

Snapshot types

SnapshotType controls extension and optional metadata (MimeType, DisplayName). This can also affect the serializer.

Test context

Snapshot naming uses test context when available:

• Snapshot.TestContext (AsyncLocal<SnapshotTestContext?>) can be set explicitly.
• Xunit v3, TUnit, and NUnit display names are auto-detected to improve generated file names.

Customization

Use SnapshotSettings to customize behavior:

• Serializers (SnapshotSerializerCollection)
• Comparers (SnapshotComparerCollection)
• SnapshotUpdateStrategy (Disallow, Overwrite, OverwriteWithoutFailure, MergeTool, MergeToolSync)
• AssertionExceptionCreator and ErrorMessageFormatter
• SnapshotPathStrategy for full path generation

You can also set the default strategy using the SNAPSHOTTESTING_STRATEGY environment variable. The value is case-insensitive and must match one of the SnapshotUpdateStrategy static property names (for example: DISALLOW, MergeTool, overwritewithoutfailure).

var settings = SnapshotSettings.Default with
{
    SnapshotUpdateStrategy = SnapshotUpdateStrategy.Disallow,
};

Snapshot.Validate(value, SnapshotType.Default, settings);

The default serializers handle human-readable objects, byte[], and Stream. GIF frame extraction is opt-in via Serializers.AddGifSerializer(): when enabled and SnapshotType.Gif is used with a valid GIF byte[], each frame is serialized as a separate .png snapshot. ICO image extraction is opt-in via Serializers.AddIcoSerializer(): when enabled and SnapshotType.Ico is used with a valid ICO byte[], each icon image is serialized as a separate .png snapshot. BMP/PNG/JPEG image comparison is opt-in via Comparers.AddImageComparer(). When enabled, SnapshotType.Bmp, SnapshotType.Png, and SnapshotType.Jpeg (including .jpg aliases) snapshots are compared by decoded pixel content (ARGB), so format metadata differences do not trigger snapshot mismatches. To allow small visual differences, configure the image comparer with an SSIM threshold:

var settings = SnapshotSettings.Default with { };
settings.Comparers.AddImageComparer(new ImageComparisonSettings
{
    SimilarityThreshold = 0.95f,
});

JPEG/JPG parsing limitations

JPEG support in the core package is intentionally subset-based and dependency-free.

Supported:

• 8-bit baseline JPEG decoding
• Grayscale and YCbCr color encodings
• 4:4:4, 4:2:2, and 4:2:0 sampling
• Restart markers (DRI/RST)

Unsupported (throws NotSupportedException):

• Progressive JPEG and arithmetic-coded JPEG
• Non-8-bit precision JPEG
• CMYK/YCCK or Adobe transform 0/2 workflows
• JPEG files with ICC profiles
• JPEG files with EXIF orientation values requiring auto-rotation

Scrubbing

Scrubbing helps make snapshots deterministic by removing unstable values or lines.

var settings = SnapshotSettings.Default with { };
settings.ConfigureHumanReadableSerializer(options => options.ScrubGuid());
settings.ScrubLinesContaining("GeneratedAt:");

Snapshot.Validate(value, SnapshotType.Default, settings);

You can also scrub relative temporal values:

var now = DateTime.UtcNow;
var settings = SnapshotSettings.Default with { };
settings.ConfigureHumanReadableSerializer(options => options.UseRelativeDateTime(now));