SnapshotAssertions 0.4.0

Prefix Reserved

dotnet add package SnapshotAssertions --version 0.4.0

NuGet\Install-Package SnapshotAssertions -Version 0.4.0

This command is intended to be used within the Package Manager Console in Visual Studio, as it uses the NuGet module's version of Install-Package.

<PackageReference Include="SnapshotAssertions" Version="0.4.0" />

For projects that support PackageReference, copy this XML node into the project file to reference the package.

<PackageVersion Include="SnapshotAssertions" Version="0.4.0" />
                    

                            Directory.Packages.props

<PackageReference Include="SnapshotAssertions" />
                    

                            Project file

For projects that support Central Package Management (CPM), copy this XML node into the solution Directory.Packages.props file to version the package.

paket add SnapshotAssertions --version 0.4.0

The NuGet Team does not provide support for this client. Please contact its maintainers for support.

#r "nuget: SnapshotAssertions, 0.4.0"

#r directive can be used in F# Interactive and Polyglot Notebooks. Copy this into the interactive tool or source code of the script to reference the package.

#:package SnapshotAssertions@0.4.0

#:package directive can be used in C# file-based apps starting in .NET 10 preview 4. Copy this into a .cs file before any lines of code to reference the package.

#addin nuget:?package=SnapshotAssertions&version=0.4.0
                    

                            Install as a Cake Addin

#tool nuget:?package=SnapshotAssertions&version=0.4.0
                    

                            Install as a Cake Tool

The NuGet Team does not provide support for this client. Please contact its maintainers for support.

SnapshotAssertions

Scope: Test projects only. Not intended for production code.

Framework-agnostic core for text-snapshot assertions.

For TUnit test projects, install SnapshotAssertions.TUnit instead; this package comes with it transitively. SnapshotAssertions is the framework-agnostic shared engine; framework-specific adapter packages add the assertion entry points each test framework expects.

What's in this package

SnapshotComparer: string-against-file comparison with line-ending, BOM, trailing-whitespace, and trailing-newline options.
SnapshotFileResolver: TestContext-aware default file naming (Snapshots/{TestClass}.{TestMethod}.expected.txt) and explicit-path resolution.
SnapshotAcceptMode: env-var-driven accept logic (SNAPSHOT_ACCEPT=1 writes the actual content over the expected baseline) with a CI=true guard so accidental pipeline acceptance is impossible.
SnapshotOptions: line-ending, BOM, whitespace, and trailing-newline configuration with strict defaults.
LineDiffRenderer: terminal line-based diff display, truncated to the first 20 differing lines for very large diffs (LineDiffRenderer.MaxDifferingLines = 20).
SnapshotScrubber + Scrubbers factory (v0.2.0+): text-transform pipeline that replaces volatile substrings (GUIDs, ISO 8601 timestamps, Unix-epoch-millis numbers, custom regex matches) with stable indexed tokens before comparison. Built-ins (Scrubbers.Guid, Scrubbers.Iso8601Timestamp, Scrubbers.UnixEpochMillis, plus Scrubbers.GuidN and Scrubbers.ElapsedMs (v0.4.0+)), curated chains (Scrubbers.Default for the v0.2.0 three-pattern set, Scrubbers.Common (v0.4.0+) for the extended five-pattern set), two Scrubbers.Pattern overloads for custom regex, and SnapshotScrubberState for stable indexed-token assignment across recurring values. Scrubbers.Combine(params SnapshotScrubber[]) (v0.3.0+) assembles an array of scrubbers into a single composite for reusable bundles.
DiffSuggestion + DiffSuggestionAnalyzer (v0.4.0+): scans a snapshot-mismatch diff for known volatile patterns and surfaces scrubber recommendations. Integrated into SnapshotResult.Describe() so failure messages include a top-3-capped "Suggestion(s)" section pointing at applicable built-ins.
SnapshotAssertions.Render.SnapshotRenderer<T> + Renderer.For<T> (v0.4.0+): abstract base class and inline factory for projecting domain types to canonical strings before snapshot comparison. Adapter packages consume these via their own MatchesSnapshot<T> overloads.

Test-framework adapters

Package	Test framework	Status
`SnapshotAssertions.TUnit`	TUnit	Available now
`SnapshotAssertions.NUnit`	NUnit	Possible if there is demand
`SnapshotAssertions.xUnit`	xUnit	Possible if there is demand
`SnapshotAssertions.MSTest`	MSTest	Possible if there is demand

If you'd find a non-TUnit adapter useful, open a feature request: adapters are not built proactively.

Installation

dotnet add package SnapshotAssertions.TUnit

SnapshotAssertions comes transitively. You don't need to install it directly unless you're building your own adapter package.

Stability

The public surfaces above are semver-bound. Breaking changes require a major version bump. The exact text format of line-based diff output is not stable and may gain extra detail or change formatting in any release.

License

Product	Compatible and additional computed target framework versions.
.NET	net10.0 is compatible. net10.0-android was computed. net10.0-browser was computed. net10.0-ios was computed. net10.0-maccatalyst was computed. net10.0-macos was computed. net10.0-tvos was computed. net10.0-windows was computed.

Compatible target framework(s)

Included target framework(s) (in package)

Learn more about Target Frameworks and .NET Standard.

net10.0
- No dependencies.

NuGet packages (1)

Showing the top 1 NuGet packages that depend on SnapshotAssertions:

Package	Downloads
SnapshotAssertions.TUnit TUnit-native text-snapshot assertions using [AssertionExtension]. Provides Assert.That(actual).MatchesSnapshot() / .MatchesSnapshotFile() with line-based diff display, accept-via-environment-variable workflow, and CI guard. AOT-compatible, trimmable, no reflection. Designed for API-surface verification and small text snapshots; coexists with Verify for object-graph cases.	1.4K

GitHub repositories

This package is not used by any popular GitHub repositories.

Version	Downloads	Last Updated
0.4.0	493	5/16/2026
0.3.0	458	5/12/2026
0.2.0	282	5/7/2026
0.1.0	182	5/5/2026

View the rendered release notes: https://github.com/JohnVerheij/SnapshotAssertions.TUnit/releases/tag/v0.4.0

Additive release. No breaking changes; baselines that opted into `Scrubbers.Default` produce byte-identical output.

### Added

- `Scrubbers.GuidN`: scrubs 32-character GUID-N format strings (the `Guid.ToString("N")` shape) into `<guid:N>` tokens. Shares the `"guid"` kind name with `Scrubbers.Guid`, so the index counter is unified across both formats; the Nth GUID occurrence in a snapshot gets the same N regardless of which format produced it.
- `Scrubbers.ElapsedMs`: scrubs elapsed-millisecond values (`42ms`, `42.5ms`, `1234.567 ms`) into `<elapsed-ms:N>` tokens. Case-sensitive on the `ms` suffix.
- `Scrubbers.Common`: curated chain of `Guid` + `GuidN` + `Iso8601Timestamp` + `UnixEpochMillis` + `ElapsedMs`. Superset of `Scrubbers.Default`; opt-in for the extended pattern set. Ordering follows the most-specific-first rule to avoid double-scrubbing.
- `DiffSuggestionAnalyzer.Analyze(string diff)`: scans a snapshot-mismatch diff for known volatile patterns and returns `DiffSuggestion` entries recommending applicable built-in scrubbers, ordered by hit count descending with stable secondary ordering by declaration order. Counts matches only on lines that begin with `+` or `-`; context lines are skipped so patterns unchanged on both sides do not surface as suggestions.
- `DiffSuggestion(string PatternName, int Count, string Recommendation)` record: one scrubber recommendation surfaced by `DiffSuggestionAnalyzer`.
- `SnapshotResult.Describe()` / `WriteDescription` smart-diff suggestion section: on `Mismatched` outcomes with detected patterns, the failure message now includes a "Suggestion(s)" section between the diff and the accept-flow guidance. The list is capped at the top 3 patterns by hit count; surplus patterns roll up into an "... and N more" line pointing consumers at `Scrubbers.Common`. Failure messages for `Mismatched` outcomes with no detected patterns, and for all other outcomes (`Matched`, `NoBaseline`, `Accepted`), are byte-identical to v0.3.0.
- `SnapshotAssertions.Render.SnapshotRenderer<T>` abstract base class: consumers subclass to plug domain types (Google.Protobuf messages, `XDocument`, `Activity`, project-specific value objects) into the snapshot pipeline.
- `SnapshotAssertions.Render.Renderer.For<T>(Func<T, string>)` static factory: builds a renderer from a lambda when a full subclass is unnecessary.
- `RenderedSnapshotAssertion<T>`: renderer-projected assertion type returned by the two new `MatchesSnapshot<T>` overloads. Carries the same chain methods as `SnapshotAssertion` (`WithName`, `AtPath`, `WithOptions`, `WithScrubber`).
- `MatchesSnapshot<T>(this IAssertionSource<T>, SnapshotRenderer<T>)` extension: renderer-projected entry point taking a subclass renderer. Use when the renderer is reusable and owns configuration or state.
- `MatchesSnapshot<T>(this IAssertionSource<T>, Func<T, string>)` extension: delegate-shaped entry point. Use for inline projections and for composing with a sibling family package's static renderer method without taking a reference on its assembly.

### Changed

- `TUnit` package reference bumped `1.44.0` → `1.44.39` (and the external-consumer smoke-test pin). 1.44.39 carries the `[GenerateAssertion]` source-generator fix for value-type optional parameters; no behavioural change for this package, taken for family lockstep.
- `Microsoft.SourceLink.GitHub` bumped `10.0.203` → `10.0.300`. The embedded source-link metadata in shipped `.pdb` files now points at the updated SourceLink schema; debugging-into-the-package from consumers' IDEs is unaffected in behaviour but uses the newer SourceLink format.
- README cookbook documents `Scrubbers.Common` ordering rationale, smart-diff suggestion output shape and top-3 cap, the renderer-pattern API with four worked subclass examples (`OtelTraceIdScrubber`, `EphemeralPathScrubber`, `PortScrubber`, `NumericTokenScrubber` as a parameterised variant), and sibling-family composition without cross-package dependency.
- Packaged READMEs (`src/SnapshotAssertions.TUnit/README.md`, `src/SnapshotAssertions/README.md`) mention `Scrubbers.Common`, smart-diff suggestions, and the renderer-pattern API with deep-links to the root README.