Class SnapshotSettings

Namespace

XBullet.EasyTesting.Snapshots

Assembly

XBullet.EasyTesting.Snapshots.Core.dll

Controls snapshot naming, storage, serialization, and scrubbing.

public sealed class SnapshotSettings

Inheritance

object

SnapshotSettings

Inherited Members

object.Equals(object)

object.Equals(object, object)

object.GetHashCode()

object.GetType()

object.ReferenceEquals(object, object)

object.ToString()

Constructors

SnapshotSettings()

Creates snapshot settings using package defaults and environment configuration.

public SnapshotSettings()

Fields

AllowCiUpdatesEnvironmentVariable

The environment variable that explicitly permits automatic updates in CI.

public const string AllowCiUpdatesEnvironmentVariable = "INTEGRATION_TESTS_ALLOW_SNAPSHOT_UPDATES_IN_CI"

Field Value

string

UpdateModeEnvironmentVariable

The environment variable used to select automatic snapshot updates.

public const string UpdateModeEnvironmentVariable = "INTEGRATION_TESTS_UPDATE_SNAPSHOTS"

Field Value

string

Properties

AllowUpdatesInContinuousIntegration

Gets or sets whether automatic snapshot updates are allowed when a continuous-integration environment is detected. The default is controlled by INTEGRATION_TESTS_ALLOW_SNAPSHOT_UPDATES_IN_CI and is otherwise false.

public bool AllowUpdatesInContinuousIntegration { get; set; }

Property Value

bool

true to permit configured automatic writes in detected CI environments; otherwise, false. This does not itself enable updates.

Catalog

Gets or sets an optional instance-scoped catalog that records exercised snapshots.

public SnapshotCatalog? Catalog { get; set; }

Property Value

SnapshotCatalog

The caller-owned catalog notified of verified paths, or null for no tracking.

DiffTool

Gets or sets an explicit diff viewer. When omitted, Visual Studio, VS Code, Rider, and Meld are discovered automatically. Diff viewers are never launched in CI.

public SnapshotDiffTool? DiffTool { get; set; }

Property Value

SnapshotDiffTool

An explicit retained configuration, or null to auto-discover a supported viewer.

Directory

Gets or sets the snapshot directory. Relative paths are resolved from the calling source file. The default is a snapshots directory beside that source file.

public string? Directory { get; set; }

Property Value

string

An absolute path or a path relative to the caller's source directory, or null to use the resolver or the default sibling snapshots directory.

DirectoryResolver

Gets or sets an optional callback that selects the snapshot directory from the calling test context. Directory takes precedence when both are set.

public Func<SnapshotLocationContext, string>? DirectoryResolver { get; set; }

Property Value

Func<SnapshotLocationContext, string>

A callback retained and invoked during path resolution, or null. It must return a non-empty absolute or source-relative directory. Directory takes precedence.

JsonSerializerOptions

Gets or sets the JSON options used to serialize the snapshot.

public JsonSerializerOptions JsonSerializerOptions { get; set; }

Property Value

JsonSerializerOptions

The mutable serializer options used immediately by assertions. The default uses web defaults, indented output, and original property names. Defaults templates clone this object.

LaunchDiffTool

Gets or sets whether an installed diff viewer is launched after a mismatch.

public bool LaunchDiffTool { get; set; }

Property Value

bool

true to attempt launching a viewer after mismatches outside CI; otherwise, false. The default is true.

Scrubbers

Gets transformations applied to serialized content before comparison.

public IList<Func<string, string>> Scrubbers { get; }

Property Value

IList<Func<string, string>>

The live ordered callback list. Scrubbers run after structural JSON rules and must return non-null content; JSON scrubbers must leave valid JSON.

SnapshotName

Gets or sets the snapshot name. The calling method name is used when this is not specified.

public string? SnapshotName { get; set; }

Property Value

string

A filename component, or null to use the caller member name.

UpdateMode

Gets or sets automatic snapshot-update behavior. The default can be selected with INTEGRATION_TESTS_UPDATE_SNAPSHOTS=missing or all.

public SnapshotUpdateMode UpdateMode { get; set; }

Property Value

SnapshotUpdateMode

None to write received files and fail, Missing to approve only missing files, or All to overwrite missing and changed verified files.

Variant

Gets or sets an optional snapshot variant. Variants create distinct snapshots for multiple assertions or parameterized cases in the same test method.

public string? Variant { get; set; }

Property Value

string

An optional filename component distinguishing snapshots from the same assertion.

Methods

AllowingUpdatesInContinuousIntegration()

Explicitly permits automatic snapshot updates in continuous integration.

public SnapshotSettings AllowingUpdatesInContinuousIntegration()

Returns

SnapshotSettings

This settings instance, for chaining. The update mode remains unchanged.

BesideSourceFile()

Stores snapshots directly beside the calling source file instead of in its default snapshots directory.

public SnapshotSettings BesideSourceFile()

Returns

SnapshotSettings

This settings instance, for chaining, with directory ..

CanonicalizeJson()

Sorts JSON object properties by ordinal name before comparison.

public SnapshotSettings CanonicalizeJson()

Returns

SnapshotSettings

This settings instance, for chaining.

ForHashedVariant(params object?[])

Creates a compact deterministic variant from serialized parameter values and returns this instance. This is useful when parameter text would produce an excessively long filename.

public SnapshotSettings ForHashedVariant(params object?[] values)

Parameters

values object[]

The non-null parameter array serialized immediately with current JSON options.

Returns

SnapshotSettings

This settings instance with a hash- variant followed by the first 16 lowercase SHA-256 hexadecimal characters of the serialized values.

ForVariant(string)

Sets a snapshot variant and returns this instance.

public SnapshotSettings ForVariant(string variant)

Parameters

variant string

The non-empty variant used as a sanitized filename component.

Returns

SnapshotSettings

This settings instance, for chaining.

HashPath(string)

Replaces values selected by an extended JSON Pointer with a deterministic SHA-256 hash of their canonical JSON representation.

public SnapshotSettings HashPath(string path)

Parameters

path string

The non-null extended JSON Pointer; an empty string selects the root.

Returns

SnapshotSettings

This settings instance, for chaining. Rules run in registration order.

IgnoreMember(string)

Removes a matching JSON member from the snapshot at every nesting level.

public SnapshotSettings IgnoreMember(string memberName)

Parameters

memberName string

The non-empty case-insensitive member name.

Returns

SnapshotSettings

This settings instance, for chaining.

IgnoreMembers(params string[])

Removes matching JSON members from the snapshot at every nesting level. Member names are matched without regard to case.

public SnapshotSettings IgnoreMembers(params string[] memberNames)

Parameters

memberNames string[]

A non-null array of non-empty names; duplicates are ignored case-insensitively.

Returns

SnapshotSettings

This settings instance, for chaining.

IgnorePath(string)

Removes values selected by an extended JSON Pointer. Use * as a wildcard segment.

public SnapshotSettings IgnorePath(string path)

Parameters

path string

The non-null extended JSON Pointer; an empty string selects the root.

Returns

SnapshotSettings

This settings instance, for chaining. Rules run in registration order.

InDirectory(Func<SnapshotLocationContext, string>)

Sets a context-aware snapshot-directory resolver and returns this instance.

public SnapshotSettings InDirectory(Func<SnapshotLocationContext, string> directoryResolver)

Parameters

directoryResolver Func<SnapshotLocationContext, string>

A non-null callback retained until assertion and required to return a non-empty directory path.

Returns

SnapshotSettings

This settings instance, for chaining, with any fixed directory cleared.

InDirectory(string)

Sets the snapshot directory and returns this instance.

public SnapshotSettings InDirectory(string directory)

Parameters

directory string

A non-empty absolute path or path relative to the caller source directory.

Returns

SnapshotSettings

This settings instance, for chaining, with any directory resolver cleared.

Named(string)

Sets the snapshot name and returns this instance.

public SnapshotSettings Named(string snapshotName)

Parameters

snapshotName string

The non-empty name used as a sanitized filename component.

Returns

SnapshotSettings

This settings instance, for chaining.

ReplacePath(string, object?)

Replaces values selected by an extended JSON Pointer with a serialized value.

public SnapshotSettings ReplacePath(string path, object? replacement)

Parameters

path string

The non-null extended JSON Pointer; an empty string selects the root.

replacement object

The replacement serialized with current JSON options; null is accepted.

Returns

SnapshotSettings

This settings instance, for chaining. Rules run in registration order.

Scrub(Func<string, string>)

Adds a serialized-content scrubber and returns this instance.

public SnapshotSettings Scrub(Func<string, string> scrubber)

Parameters

scrubber Func<string, string>

A non-null callback retained and run in registration order before comparison.

Returns

SnapshotSettings

This settings instance, for chaining.

ScrubDateTimes()

Replaces every round-trip JSON date/time string with {DateTime}.

public SnapshotSettings ScrubDateTimes()

Returns

SnapshotSettings

This settings instance, for chaining.

ScrubGuids()

Replaces every JSON string containing a GUID with {Guid}.

public SnapshotSettings ScrubGuids()

Returns

SnapshotSettings

This settings instance, for chaining.

ScrubMember(string)

Replaces the value of a matching JSON member with {Scrubbed} at every nesting level.

public SnapshotSettings ScrubMember(string memberName)

Parameters

memberName string

The non-empty case-insensitive member name.

Returns

SnapshotSettings

This settings instance, for chaining.

ScrubMembers(params string[])

Replaces values of matching JSON members with {Scrubbed} at every nesting level. Member names are matched without regard to case.

public SnapshotSettings ScrubMembers(params string[] memberNames)

Parameters

memberNames string[]

A non-null array of non-empty names; duplicates are ignored case-insensitively.

Returns

SnapshotSettings

This settings instance, for chaining.

ScrubPath(string)

Replaces values selected by an extended JSON Pointer with {Scrubbed}. Use an empty path for the root, / separators, and * as a wildcard segment.

public SnapshotSettings ScrubPath(string path)

Parameters

path string

The non-null extended JSON Pointer; an empty string selects the root.

Returns

SnapshotSettings

This settings instance, for chaining. Rules run in registration order.

SortArray(string, string?)

Sorts arrays selected by an extended JSON Pointer. When itemPath is set, it is resolved relative to each array item and used as the ordinal JSON sort key.

public SnapshotSettings SortArray(string path, string? itemPath = null)

Parameters

path string

The non-null extended JSON Pointer selecting arrays; wildcard segments are accepted.

itemPath string

An optional non-wildcard JSON Pointer relative to each item, or null to sort by each item's canonical JSON representation.

Returns

SnapshotSettings

This settings instance, for chaining. Rules run in registration order.

TrackingWith(SnapshotCatalog)

Records matched snapshot paths in an instance-scoped catalog.

public SnapshotSettings TrackingWith(SnapshotCatalog catalog)

Parameters

catalog SnapshotCatalog

The non-null caller-owned, thread-safe catalog to notify.

Returns

SnapshotSettings

This settings instance, for chaining.

Updating(SnapshotUpdateMode)

Sets automatic snapshot-update behavior and returns this instance.

public SnapshotSettings Updating(SnapshotUpdateMode updateMode)

Parameters

updateMode SnapshotUpdateMode

The update policy; undefined enum values are retained but unsupported during matching.

Returns

SnapshotSettings

This settings instance, for chaining.

WithDiffTool(SnapshotDiffTool)

Selects an explicit diff tool and returns this instance.

public SnapshotSettings WithDiffTool(SnapshotDiffTool diffTool)

Parameters

diffTool SnapshotDiffTool

The non-null caller-owned configuration retained by these settings.

Returns

SnapshotSettings

This settings instance, for chaining, with launching enabled outside CI.

WithoutDiffTool()

Disables diff-tool launching and returns this instance.

public SnapshotSettings WithoutDiffTool()

Returns

SnapshotSettings

This settings instance, for chaining, with any explicit tool cleared.