Snapshot Tests

Snapshot Tests Skill

Workflow for recording and validating swift-snapshot-testing snapshots in the SwiftStreamingMarkdown package.

When to use this skill

Trigger when the user asks anything that resolves to one of:

• Record — "record snapshots", "re-record the snapshots", "update snapshots", "regenerate references" → use Mode 1.
• Validate — "validate snapshots", "run snapshot tests", "check snapshots for regressions", "diff the failed snapshots" → use Mode 2.

If the request is ambiguous (e.g. "fix the snapshot tests"), validate first (Mode 2) and only re-record after the user confirms the visual changes are intentional.

Repo context

Because diffTool is the string "diff-image", swift-snapshot-testing formats every failure message with a literal line shaped exactly like:

diff-image <reference-png-path> <failed-png-path>

That is the hook this skill keys off of.

Build command

xcodebuild test \
  -scheme SwiftStreamingMarkdown \
  -destination "platform=iOS Simulator,OS=26.4.1,name=iPhone 17" \
  -skipMacroValidation 2>&1 | tee /tmp/snapshot-tests.log

Always tee to a log file — the Mode 2 grep below depends on it.

If the iPhone 17 / iOS 26.4.1 destination is unavailable on the developer's machine, list installed simulators with xcrun simctl list devices available | head -30 and substitute an equivalent iOS Simulator destination.

Mode 1: record snapshots

1. Uncomment the recording flag:

   sed -i '' 's|// isRecording = true|isRecording = true|' \
     Tests/MarkdownTextTests/SnapshotTestFoundation/SnapshotTestCase.swift

2. Verify the toggle:

   grep -n "isRecording" Tests/MarkdownTextTests/SnapshotTestFoundation/SnapshotTestCase.swift

   Expect a single hit with isRecording = true and no leading //.
3. Run the tests using the build command above. Every snapshot test will fail — recording mode always emits a failure after it writes the new reference PNG. This is expected; do not treat it as an error.
4. Restore the comment — always, even if step 3 errored out:

   sed -i '' 's|^\([[:space:]]*\)isRecording = true|\1// isRecording = true|' \
     Tests/MarkdownTextTests/SnapshotTestFoundation/SnapshotTestCase.swift

5. Re-verify:

   grep -n "isRecording" Tests/MarkdownTextTests/SnapshotTestFoundation/SnapshotTestCase.swift

   Should once again show // isRecording = true.
6. Report to the user:

   git status Tests/MarkdownTextTests/__Snapshots__/

   Summarise which reference PNGs were added or changed, and remind the user to eyeball the diff before committing — recording overwrites references blindly, including wrong renders.

Platform coverage: iOS records locally, macOS does not

A local xcodebuild ... -destination "platform=iOS Simulator,..." run only regenerates the iOS variants (iPhone16-*, iPadPro11-*, iPadPro11Landscape-*). The macOS variants (macOS-standard-light, macOS-standard-dark) are not produced by that run.

Do not record macOS references on a developer machine. The macOS variants use a strict perceptualPrecision: 1.0, so even a one-off subpixel/font-rendering difference between a local macOS version and the CI runner's macOS version fails validation. Locally-recorded macOS PNGs will almost always mismatch CI.

macOS references are recorded by the dedicated Record macOS Snapshots workflow (.github/workflows/record-macos-snapshots.yml), a workflow_dispatch job on runs-on: macos-26. It flips isRecording on, deletes the existing *macOS*.png references, re-records them with -destination "platform=macOS", and uploads the fresh PNGs as the macos-snapshots artifact. (The record step's continue-on-error: true means the run reports success even though xcodebuild test exits non-zero in record mode.)

Note the workflow re-records the entire macOS suite, so the artifact contains every *.macOS-standard-*.png — copy back only the files your change actually affects, so you don't churn unrelated references against a possibly-different runner rendering.

When the branch lives in microsoft/SwiftStreamingMarkdown

1. Push your branch (with re-recorded iOS references) to origin.
2. Run the workflow against it:

   gh workflow run "Record macOS Snapshots" --ref <branch>
   gh run watch "$(gh run list --workflow 'Record macOS Snapshots' \
     --branch <branch> --limit 1 --json databaseId -q '.[0].databaseId')" \
     --exit-status

3. Download the artifact and copy only the affected PNGs into place:

   gh run download <run-id> -n macos-snapshots -D /tmp/macos-snaps
   cp /tmp/macos-snaps/<TestMethod>.macOS-standard-*.png \
     Tests/MarkdownTextTests/__Snapshots__/<TestClass>/

4. Eyeball the PNGs, commit, and push.