Open-source project
pointfreeco/swift-snapshot-testing avatar
pointfreeco/swift-snapshot-testing

SnapshotTesting compares values, not just rendered views

📸 Delightful Swift snapshot testing.

4,395 stars689 forksSwiftMIT

At a glance

What is it?
pointfreeco's Swift library records a reference file on the first run of an assertion, then diffs every later run against it, and the strategy argument decides whether the artifact is an image, a URL request, JSON or a Swift mirror dump. It suits Swift teams that want CI-enforced pixel and payload baselines.
Who is it for?
Adopt it if your team already owns a simulator-driven test target and wants baseline files in version control for views, URL requests and Encodable payloads. Do not adopt it if your snapshots must be reproducible across machines, since the README requires the exact simulator that took the reference.
Can I use it commercially?
Yes. MIT is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
Is it still maintained?
Yes. The repository last received commits 25 days ago.
What is it written in?
Mainly Swift, according to GitHub's language statistics.

Answers come from the project's GitHub data, last synced on November 15, 2026, and from our analysis. They are not legal advice.

From daily snapshots

Star history

  • pointfreeco/swift-snapshot-testing4,395 ★ · +56
Star history
Repository2026-09-232026-11-15
pointfreeco/swift-snapshot-testing4.3k4.4k

56 Stars in the last 53 days, measured from the daily GitHub snapshot. Compare with other projects

Editorial analysis

The first run writes a file and fails on purpose

The library's core trick is that a snapshot assertion doubles as its own baseline generator. The first time `assertSnapshot` runs, it records a reference to disk and deliberately fails, printing the path. The README shows the shape of that message: a failure line stating that no reference was found, the path of the newly recorded snapshot, and an instruction to re-run the test. Only the second run compares anything.

That design has an immediate consequence for review. A new test does not pass on arrival; it produces a binary file that a human has to look at before it means anything. Someone still has to decide whether the recorded image is correct. The library automates comparison, not judgement.

The module import is short. Callers bring in `SnapshotTesting` and the assertion function, and the library handles the rest.

The strategy argument decides what artifact lands in the repository

Most Swift snapshot libraries compare rendered images of views. This one makes the strategy the deciding argument, so the same value can produce several reference files in one test. A view controller can be checked twice, once as an image and once as a text dump of its subview hierarchy:

swift
assertSnapshot(of: vc, as: .image)
assertSnapshot(of: vc, as: .recursiveDescription)

Values that are not views work the same way. A URL request can be snapshotted as raw text, which is how you pin down what an API client actually sends:

swift
assertSnapshot(of: urlRequest, as: .raw)

An `Encodable` model can be compared against `.json` or `.plist`, and any value at all can be dumped through its Swift mirror with `.dump`, which renders a tree beginning with the type name and one line per stored property. That last strategy is the floor of the library: no strategy has to exist for a type because reflection covers everything.

Snapshot overrides replace a whole baseline at three different scopes

Recording is controlled by the `record:` argument, which takes `.all` or `.failed` and appears in three places. Inline on a single assertion, to overwrite one reference. Wrapped around a scope, to re-record every assertion inside it:

swift
withSnapshotTesting(record: .all) {
  assertSnapshot(of: vc1, as: .image)
  assertSnapshot(of: vc2, as: .image)
}

Or at the suite level, where a trait records only what failed, which keeps passing baselines untouched:

swift
@Suite(.snapshots(record: .failed))
struct FeatureTests {}

The XCTest equivalent hooks `invokeTest`, so a legacy `XCTestCase` subclass wraps `super.invokeTest()` in the same call.

`.failed` is the useful one for routine work. Re-recording everything after a deliberate redesign wipes out the one baseline you most wanted to compare against.

One simulator, many device configs, and the caveat that undercuts it

Strategies accept a device argument, so one simulator can produce baselines for several form factors and orientations:

swift
assertSnapshot(of: vc, as: .image(on: .iPhoneSe))
assertSnapshot(of: vc, as: .image(on: .iPhoneSe(.landscape)))
assertSnapshot(of: vc, as: .image(on: .iPadMini(.portrait)))

Trait collections and content size categories can be overridden, which is the argument for doing this rather than hand-maintaining one test file per device.

The catch sits in a warning directly under those examples: snapshots must be compared using the exact same simulator that originally took the reference, because otherwise the images drift. So the device argument buys you several device shapes on one machine, not portability across machines. A contributor on a different simulator runtime, or a CI image with a different OS build, will get failures that describe a rendering difference rather than a code change.

The no-configuration claim stops at the Xcode target column

The claim that no configuration is needed holds for the assertion itself, not for the install. Xcode will by default attach the package to your main application or framework target, so the Add to Target choice on the final dialog has to be changed to a test target.

With Swift Package Manager the dependency goes in `Package.swift`, and the README gives a version floor rather than the current tag:

swift
dependencies: [
  .package(
    url: "https://github.com/pointfreeco/swift-snapshot-testing",
    from: "1.12.0"
  ),
]

Then the test target has to name the product explicitly:

swift
.testTarget(
  name: "MyAppTests",
  dependencies: [
    "MyApp",
    .product(name: "SnapshotTesting", package: "swift-snapshot-testing"),
  ]
)

Getting the Xcode step wrong links the library into your shipping target. That is the one installation mistake worth checking.

Comparing baselines across machines is where this design breaks

The alternative to reach for first is not another Swift library. Jest ships snapshot testing for JavaScript and TypeScript, but it compares serialised values, not rendered pixels, so it has no equivalent of the image strategies. The real difference in approach is that image-based UI baselines on Apple platforms are tied to the renderer that produced them, while value snapshots are not.

If your goal is catching regressions in what your networking layer sends or in model encoding, the `.raw`, `.json` and `.plist` strategies snapshot text rather than images.

The repository is not archived and the last push was on 2026-10-21, with release 1.19.7 published the same day and 1.19.6 on 2026-09-21. The project is MIT licensed.

Mirrored values pay off when no strategy fits the type

The fallback strategy deserves more attention than it gets. `assertSnapshot(of: user, as: .dump)` needs no conformance, no adapter and no registration. Reflection walks the value and writes a tree of stored properties, so a struct with three fields can get a baseline in one line without anyone writing a strategy.

The trade-off is fidelity. A mirror dump shows stored properties, not behaviour. Two values can dump identically and encode differently if a custom encode implementation changes the key names or ordering, which is exactly what the `.json` and `.plist` strategies exist to catch. Mirror baselines are a cheap first line, not a substitute.

The repository's own `Makefile` shows how the maintainers run the suite: the Linux tests run through a `swift:5.7-focal` Docker container executing `swift test`, while the macOS, iOS and tvOS targets go through `xcodebuild`, with named simulator destinations for iOS and tvOS. That split is a good signal about where the library is verifiable and where it is not.

Editorial conclusion

Adopt it if your team already owns a simulator-driven test target and wants baseline files in version control for views, URL requests and Encodable payloads. Do not adopt it if your snapshots must be reproducible across machines, since the README requires the exact simulator that took the reference. Verify first that Xcode attaches the package to a test target rather than your app target, then run one assertion and confirm the recorded file lands under the __Snapshots__ directory next to the test that produced it, and pin the simulator runtime used for image strategies so the baseline means the same thing on every machine that runs it.

Frequently asked questions

What is swift-snapshot-testing?

It is a Swift library that records a reference file for a value and compares later runs against it. The strategy argument decides what gets stored, covering images of views, raw URL requests, JSON, property lists and Swift mirror dumps.

What is snapshot testing?

A test technique where an expected output is stored as a reference file rather than written as assertions by hand. On the first run SnapshotTesting records that file and fails, and subsequent runs compare against it.

Why does my swift-snapshot-testing image test fail on CI but pass locally?

The README warns that snapshots must be compared using the exact same simulator that originally took the reference. A different simulator runtime produces image differences that are not code changes.

Official sources

  1. License: MIT
  2. pointfreeco/swift-snapshot-testing on GitHub
  3. Project website
  4. README
  5. Releases
Add this badge to your README

If you maintain this project, the badge below links readers to this analysis and shows its maintenance status from the daily GitHub snapshot. Paste the markdown into your README; add ?metric=license or ?metric=stars to the image URL for a different field.

Add this badge to your README

markdown
[![Hysen Labs](https://hysenlabs.com/badge/pointfreeco-swift-snapshot-testing.svg)](https://hysenlabs.com/projects/pointfreeco-swift-snapshot-testing)

Star history chart for your README

markdown
[![Star history](https://hysenlabs.com/chart/pointfreeco-swift-snapshot-testing.svg)](https://hysenlabs.com/projects/pointfreeco-swift-snapshot-testing)

Was this useful?