Meziantou.Framework.SnapshotTesting 2.0.0

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);

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.