Meziantou.Framework

Introduction

edit

Meziantou.Framework.SnapshotTesting replaces long lists of assertions with a single call. Snapshot.Validate serializes the value under test and compares the result with a file committed next to the test, the snapshot. When the value changes, the test fails and shows the difference: either the change is a bug, or you approve the new snapshot.

How it works

  1. Snapshot.Validate(value) serializes the value. Objects are written in a readable, YAML-like text; strings, byte arrays and streams are written as they are.
  2. The result is compared with the verified file of the test, stored in a __snapshots__ folder next to the test source file: __snapshots__/UserTests_CreateUser.verified.txt.
  3. When the content differs, or when the verified file does not exist yet, the new content is written to an actual file (UserTests_CreateUser.actual.txt) and the test fails with the list of changed files.
  4. You review the difference and approve it: the actual file replaces the verified file. You can approve with the approval tool, let an update strategy overwrite the verified files, or merge the change in a merge tool.

The verified files are part of your code: commit them, and review their changes like any other change.

What you can do with it

  • Validate any object as readable text, and configure how it is written. See Serializers and comparers.
  • Validate files and documents in their own format: JSON, YAML, XML, HTML, SVG, PNG, PDF, and any other extension. See Snapshot types.
  • Make snapshots deterministic by scrubbing GUIDs, dates, user names and other unstable values. See Deterministic snapshots.
  • Compare images by their pixels, exactly or by similarity, compare PDF documents page by page, and test source generators, syntax rewriters and analyzers with a single call. See Extensions.
  • Keep CI strict: snapshots are never updated on a build server, in a continuous testing runner or when the tests are run by an LLM agent. See Continuous integration.

Packages

PackageContains
Meziantou.Framework.SnapshotTestingSnapshot.Validate, the settings, the serializers of objects, byte arrays and streams, the scrubbers and the merge tools
Meziantou.Framework.SnapshotTesting.ImagingImage snapshots compared by their pixels, exactly or by similarity. See Images
Meziantou.Framework.SnapshotTesting.PdfPDF snapshots stored as one PNG image per page and a JSON file of metadata. See PDF documents
Meziantou.Framework.SnapshotTesting.RoslynSnapshots of source generator results, syntax trees and diagnostics. See Roslyn
Meziantou.Framework.SnapshotTesting.ToolA .NET tool that approves the actual files. See The approval tool

All the types of the main package are in the Meziantou.Framework.SnapshotTesting namespace.

File snapshots or inline snapshots

Meziantou.Framework.InlineSnapshotTesting works the same way, but stores the snapshot in the source code of the test, as a string argument of the call, instead of in a file. File snapshots suit large values, binary files and formats with their own extension; inline snapshots suit small values you want to read next to the code. See File snapshots or inline snapshots.

Next steps