Settings

edit

SnapshotSettings holds everything that controls an assertion: the serializers, the comparers, the scrubbers, the file names and the update strategy. Snapshot.Validate uses SnapshotSettings.Default unless you pass settings.

Configure every test

Configure SnapshotSettings.Default once, before any test runs. A module initializer runs when the test assembly is loaded (ModuleInitializer is in the System.Runtime.CompilerServices namespace):

internal static class SnapshotConfiguration
{
    [ModuleInitializer]
    internal static void Initialize()
    {
        // Runs once, before any test of the assembly
        SnapshotSettings.Default.SnapshotUpdateStrategy = SnapshotUpdateStrategy.MergeTool;
        SnapshotSettings.Default.MergeTools = [MergeTool.VisualStudioCode];
        SnapshotSettings.Default.ScrubUserName();
    }
}

SnapshotSettings.Default is shared by every test of the process, and tests usually run in parallel. Do not change it from a test: the change would apply to the tests running at the same time, and registering a serializer or a scrubber from a test adds it again every time the test runs.

Change the settings of one assertion

SnapshotSettings is a record: with creates a copy with its own serializers, comparers and scrubbers, which you can change without affecting the other tests. Clone() does the same. Pass the copy to Snapshot.Validate:

var value = new { Name = "John", Age = 42 };
var settings = SnapshotSettings.Default with
{
    SnapshotUpdateStrategy = SnapshotUpdateStrategy.Disallow,
};

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

Properties

Property	Default	Description
SnapshotUpdateStrategy	Disallow, or the `SNAPSHOTTESTING_STRATEGY` environment variable	What happens when a snapshot does not match. See Update strategies
ForceUpdateSnapshots	`false`	Updates the verified files even when they match, as far as the update strategy allows
AutoDetectContinuousEnvironment	`true`, unless `SNAPSHOTTESTING_AUTODETECT_CONTINUOUS_ENVIRONMENT` is `false`	Never updates snapshots on a build server, in a continuous testing runner or in an LLM agent. See Continuous integration
MergeTools	The configured and detected tools	The tools started by the merge tool strategies. See Merge tools
Serializers	Objects, `byte[]` and `Stream`	Convert a value to the content of the snapshot files. See Serializers and comparers
Comparers	Text formats ignore line endings, other formats are compared byte for byte	Decide whether a verified file and an actual file match. See Serializers and comparers
Scrubbers	Empty	Rewrite the text snapshots after serialization. See Deterministic snapshots
SnapshotNamingStrategy	SnapshotNamingStrategies.ClassName_TestName	Builds the name of the snapshot from the test. See Naming snapshots
SnapshotPathStrategy	`__snapshots__` next to the test file	Builds the full path of the verified file. See Snapshot files
MaxSnapshotFileNameLength	`128`	The longest file name before a hash shortens it. At least 20

Extension methods

Method	Description
`ConfigureHumanReadableSerializer(options => ...)`	Changes the options of the human-readable serializer, which writes objects as text
`AddConverter(converter)`	Adds a HumanReadableConverter that controls how a type is written
ScrubLines, ScrubLinesContaining, ScrubLinesMatching, ScrubLinesWithReplace, ScrubUserName, ScrubMachineName	Add a scrubber
Clone()	Returns a copy of the settings

The extension packages add their own methods, such as AddImaging(), AddPdf() and AddRoslyn(). See Extensions.

Environment variables

Variable	Effect
`SNAPSHOTTESTING_STRATEGY`	The default update strategy: the case-insensitive name of a SnapshotUpdateStrategy property, such as Overwrite or `mergetool`
`SNAPSHOTTESTING_AUTODETECT_CONTINUOUS_ENVIRONMENT`	`false`, `0`, `no` or `off` allows updates on a build server, in a continuous testing runner and in an LLM agent
`DiffEngine_Tool`	The merge tool to try first, as the case-insensitive name of a MergeTool property
`DiffEngine_Disabled`	`true` or `1` disables every merge tool

The first two variables are read when settings are created, and SnapshotSettings.Default is created the first time it is used: set them before the tests run, for example in your shell.