XBullet.EasyTesting.Snapshots.Core 1.3.0

XBullet.EasyTesting.Snapshots.Core

Framework-independent snapshot assertions for serializable values, raw JSON, plain text, HTTP content, controller responses, and complete request/response exchanges.

The package targets .NET 8, .NET 9, and .NET 10. It does not depend on xUnit, Verify, XBullet.EasyTesting, ASP.NET testing, or XBullet.EasyTesting.Http.

Install

dotnet add package XBullet.EasyTesting.Snapshots.Core

Use XBullet.EasyTesting.Snapshots.Http instead when the test snapshots requests or exchanges captured by StubHttpMessageHandler. Existing references to XBullet.EasyTesting.Snapshots can remain temporarily through the compatibility facade.

Example

Import XBullet.EasyTesting.Snapshots to assert values and anonymous arrays directly:

using XBullet.EasyTesting.Snapshots;

await new[] { new { PortfolioCode = primaryPortfolioCode, Request = request } }
    .ShouldMatchSnapshot("external-status-request", cancellationToken: cancellationToken);

The string selects a snapshot variant within the calling test. Omit it for a single snapshot, or pass settings or a configureSnapshot callback to customize serialization and scrubbing.

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

await SnapshotAssert.MatchAsync(result, settings, cancellationToken);

The first verification failure writes a target-framework-qualified *.received.* file. Review it, ensure dynamic and sensitive values are handled, and promote it to the shared *.verified.* file. Commit verified files; do not commit received files.

Controller and complete TestServer exchange assertions use the same settings:

await response.ShouldMatchControllerSnapshot(
    snapshotSettings: settings,
    cancellationToken: cancellationToken);

await response.ShouldMatchHttpExchangeSnapshot(
    configureSnapshot: settings => settings.ScrubMember("id"),
    cancellationToken: cancellationToken);

Snapshot assertions also continue to accept prebuilt SnapshotSettings instances.

Use .NormalizeStringLineEndings() on snapshot settings when JSON string values contain platform-specific newlines, such as validation messages generated on Windows and Linux. This opt-in rule converts decoded CRLF and CR to LF in both actual and verified JSON without rewriting existing verified files. It preserves trailing newlines within values and literal backslash sequences, and works with reusable or global defaults. HTTP text and YAML output retain their existing behavior. See stabilizing snapshot data.

Attach HttpExchangeRecorder to the real client pipeline when the complete request body must be captured before TestServer consumes it. Recorded responses accept configureExchange and separate exchangeOptions during assertion to omit or further scrub captured data and select output format. Callbacks start from independent recorder options; the original recording remains unchanged. Data excluded or redacted during capture cannot be restored. See where to configure exchange options.

Safety and maintenance

• Common sensitive HTTP headers and query values are excluded or redacted by default, but application-specific secrets still require explicit rules.
• SnapshotUpdateMode.All can replace reviewed files. Never enable it in ordinary CI.
• CI updates require a separate explicit authorization.
• Bulk acceptance and deletion require confirmed: true; preview paths first.
• Obsolete-file detection is valid only after the complete intended test scope passes.

Documentation

• API reference
• Snapshot documentation hub
• Create and review a first snapshot
• Snapshot recipes
• Stabilize and redact data
• Maintenance and CI safety
• Package migration
• Outbound HTTP snapshot adapters
• Verify.Xunit adapter