XBullet.EasyTesting.Snapshots.Core 1.0.6

XBullet.EasyTesting.Snapshots.Core

Lightweight, framework-independent JSON and text snapshot assertions for HTTP responses and arbitrary values. This package does not depend on XBullet.EasyTesting, ASP.NET testing, or XBullet.EasyTesting.Http.

The package targets .NET 8 and .NET 10.

Install

dotnet add package XBullet.EasyTesting.Snapshots.Core

Use XBullet.EasyTesting.Snapshots.Http for snapshots of outbound requests captured by StubHttpMessageHandler. The original XBullet.EasyTesting.Snapshots package remains available as a compatibility facade that references both packages.

var settings = new SnapshotSettings()
    .Named("administrator-order")
    .ScrubMembers("Id", "CreatedAt")
    .ScrubGuids();

await SnapshotAssert.MatchAsync(result, settings);

For a centralized or test-specific layout, resolve the directory from the calling context:

var settings = new SnapshotSettings()
    .InDirectory(context => Path.Combine(
        context.SourceDirectory,
        "snapshots",
        context.SourceFileName));

Snapshot locations

Snapshots are stored in a __snapshots__ directory beside the calling source file by default. Choose another directory with InDirectory; relative paths are resolved from the calling source file rather than the process working directory. To keep snapshots directly beside the source file, use BesideSourceFile:

var settings = new SnapshotSettings()
    .BesideSourceFile();

await SnapshotAssert.MatchAsync(result, settings);

Raw JSON

Raw JSON can be verified as structured JSON instead of as an escaped string. Raw strings and HTTP content are parsed and normalized with System.Text.Json. Verified files use *.verified.json; received files include the current target framework, such as *.received.net8.0.json, so multi-targeted test runs cannot overwrite each other's failures.

var json = $$"""
    {
      "orderId": 42,
      "status": "ready",
      "correlationId": "{{Guid.NewGuid()}}"
    }
    """;
var settings = new SnapshotSettings()
    .ScrubGuids();

await SnapshotAssert.MatchJsonAsync(json, settings);

The resulting verified snapshot contains normalized JSON:

{
  "orderId": 42,
  "status": "ready",
  "correlationId": "{Guid}"
}

Invalid JSON throws JsonException without creating a snapshot.

Plain text

Use MatchTextAsync when the content should not be parsed or serialized as JSON. Text snapshots use .verified.txt and runtime-qualified .received.*.txt files. Custom string scrubbers still apply:

var settings = new SnapshotSettings()
    .Scrub(text => text.Replace(secret, "{Redacted}", StringComparison.Ordinal));

await SnapshotAssert.MatchTextAsync(commandOutput, settings);

HTTP JSON content

Verify only the JSON response body when status, headers, and request metadata do not belong in the snapshot:

using var response = await client.GetAsync("/api/orders/42");
response.EnsureSuccessStatusCode();

await response.ShouldMatchJsonBodySnapshot();

response.Content.ShouldMatchJsonSnapshot() is also available when only the HttpContent is in scope. For buffered or seekable content, both assertions rewind the body and restore its original position, so they remain reliable after the body has already been read.

Use response.ShouldMatchControllerSnapshot() instead when the snapshot should also contain the request method and URL, response status, and stable headers. Sensitive and volatile headers, including Set-Cookie, Authentication-Info, Proxy-Authentication-Info, Date, and tracing identifiers, are excluded by default. Header capture can be customized without exposing values:

var options = new ControllerSnapshotOptions()
    .RedactingHeaders("Set-Cookie", "X-Session-Token")
    .RedactingQueryParameter("tenant_secret");

await response.ShouldMatchControllerSnapshot(options);

Redacted headers and query values are captured as {Redacted}. Common secret-bearing query names, including access_token, api_key, client_secret, sig, and token, are redacted by default. Call WithoutHeaders() to omit the entire header collection, or IncludingHeader(name) and IncludingQueryParameter(name) to explicitly include a value known to be safe.

Multiple snapshots and parameterized tests

Use a variant when one test method produces multiple snapshots or when each parameterized case needs its own file:

var settings = new SnapshotSettings()
    .ForVariant($"status-{statusCode}");

await SnapshotAssert.MatchAsync(result, settings);

The variant is appended to the test-derived snapshot name. Snapshot names and variants are encoded portably, automatically shortened with a stable hash when necessary, and produce the same safe filename on Windows and Linux. When parameter text should never appear in the filename, use ForHashedVariant(parameters).

Targeted JSON transformations

Use extended JSON Pointer rules when a member name should only be transformed at a specific path:

var settings = new SnapshotSettings()
    .ScrubPath("/orders/*/id")
    .IgnorePath("/orders/*/generatedAt")
    .ReplacePath("/environment", "test")
    .HashPath("/largePayload")
    .SortArray("/orders", "/id")
    .CanonicalizeJson();

await SnapshotAssert.MatchJsonAsync(json, settings);

Paths are case-sensitive. An empty path selects the root, / separates segments, and * selects every member or array item at one level. Escape ~ as ~0, / as ~1, and a literal * member as ~2. Missing paths are ignored. Array sort keys are compared by their canonical JSON text; array order remains unchanged unless SortArray is configured.

HashPath writes a stable sha256:... marker based on canonical JSON. It is useful for reducing large values while still detecting changes, but it is not a substitute for removing secrets with IgnorePath.

CanonicalizeJson sorts object properties recursively while preserving array order. ScrubDateTimes only matches ISO-8601 round-trip timestamps. Custom string scrubbers must return valid JSON.

Diagnostics and safe maintenance

Mismatches identify the first structural difference using JSONPath and expose its values on SnapshotMismatchException:

var exception = await Assert.ThrowsAsync<SnapshotMismatchException>(
    () => SnapshotAssert.MatchAsync(result));

Assert.Equal("$.orders[0].status", exception.DifferencePath);
Console.WriteLine($"{exception.ExpectedValue} -> {exception.ActualValue}");

Track the snapshots exercised by a complete test scope to find obsolete verified files. The catalog is explicit and instance-scoped, so parallel projects do not share mutable global state:

var catalog = new SnapshotCatalog();
var defaults = new SnapshotSettingsDefaults(settings => settings
    .ScrubGuids()
    .TrackingWith(catalog));

await SnapshotAssert.MatchAsync(result, defaults.Create());

// Run only after every snapshot in this catalog's scope has executed.
var obsolete = catalog.FindObsoleteSnapshots(snapshotDirectory);

Maintenance is preview-first and requires explicit confirmation:

var received = SnapshotMaintenance.FindReceivedSnapshots(snapshotDirectory);
var accepted = SnapshotMaintenance.AcceptReceivedSnapshots(
    snapshotDirectory,
    confirmed: true);
var removed = SnapshotMaintenance.RemoveVerifiedSnapshots(
    obsolete,
    confirmed: true);

Review received and obsolete before changing files. Removal validates every supplied path as a verified snapshot file before deleting any of them.

Automatic update modes remain disabled in CI unless separately authorized. Set INTEGRATION_TESTS_ALLOW_SNAPSHOT_UPDATES_IN_CI=true or call AllowingUpdatesInContinuousIntegration() in addition to selecting missing or all update mode. Keep this opt-in limited to dedicated snapshot-update jobs.

The first run writes a received snapshot. Review and approve it as the verified snapshot; subsequent runs report structural differences. Update modes and local diff viewers are opt-in.

See the repository documentation for controller snapshots, scrubbers, and approval workflows.