golden-and-snapshot-tests

Files (36)

• SKILL.md
• shared.json · assets/
• template-placeholders.json · assets/
• backup-envelope.golden.test.ts · examples/
• backup-envelope.golden.test.ts.snap.ios · examples/
• gate-change-commit.txt · examples/
• checkers.md · references/
• data-goldens.md · references/
• golden-policy.md · references/
• pixel-goldens.md · references/
• check-golden-changes.mjs · scripts/
• check-goldens.mjs · scripts/
• check-lib.mjs · scripts/
• golden-config.mjs · scripts/lib/
• selftest.mjs · scripts/
• goldens.json · templates/contracts/
• goldens.schema.json · templates/contracts/
• __FEATURE__-digest.golden.test.ts · templates/src/features/__FEATURE__/
• __FEATURE__-digest.golden.test.ts.snap.ios · templates/src/features/__FEATURE__/
• __FEATURE__-digest.ts · templates/src/features/__FEATURE__/
• golden-text.test.ts · templates/test/goldens/
• golden-text.ts · templates/test/goldens/
• skia-golden.ts · templates/test/goldens/
• ci.yml · tests/bases/app/.github/workflows/
• dot-gitignore · tests/bases/app/
• lefthook.yml · tests/bases/app/
• package.json · tests/bases/app/
• quality-gates.json · tests/bases/app/
• weekly-chart.golden.test.ts · tests/bases/app/test/goldens/canvas/
• CASES.json · tests/fixtures/check-golden-changes/
• SUITE.json · tests/fixtures/check-golden-changes/
• EXPECT.txt · tests/fixtures/check-golden-changes/good/
• history.log · tests/fixtures/check-golden-changes/good/
• CASES.json · tests/fixtures/check-goldens/
• SUITE.json · tests/fixtures/check-goldens/
• EXPECT.txt · tests/fixtures/check-goldens/good/

SKILL.md (first lines)

# Golden and snapshot tests

Goldens are the frozen answers of an app: the readable text a pure unit produces for fixed inputs,
the output every installed version must reproduce, the pixels a Skia surface draws. They change only
on purpose, after a real look, in a commit that says why, and contract entries never change at all.
This skill writes them in the Jest `golden` project and its two checkers prove that the tree and the
git history keep that policy.

## Rules that must hold

1. **A golden changes only by hand, one file at a time:** `npx jest <file> --selectProjects golden -u`,
   path first. Every script, hook and CI job runs `jest --ci`, which refuses to write a missing
   snapshot. No `-u`, `--updateSnapshot`, `--ci=false`, `CI=false` or baseline `--update` in
   `package.json`, git hooks (lefthook, husky, lint-staged), CI (GitHub Actions, EAS Workflows) or
   agent hooks. Why: an agent rubber-stamps whatever `-u` writes, and after `--selectProjects` a path
   is read as another project name, so every golden is rewritten (verified with `--listTests`).
2. **Look before accepting.** Read the `.snap.ios` diff line by line, open every new or changed PNG
   and its diff image, then `CI=1 npx jest --ci --selectProjects golden` passes. Why: an unread golden
   freezes a bug for every later run.
3. **Every commit that adds, changes or deletes a golden path carries
   `Gate-Change: <which goldens, why, what you looked at>`** (at least 10 characters). Golden paths:
   `**/*.golden.test.ts.snap(.ios|.android)`, `**/__image_snapshots__/**`, the pixel matcher
   `test/goldens/skia-golden.ts`, `.maestro/baselines/**`, plus `goldenPaths` in
   `contracts/goldens.json`. Why: one `git log --grep='^Gate-Change:'` lists every gate change later.
4. **`[contract]` entries are append-only.** Output that every installed version, every device or a
   file a user keeps must reproduce exactly (a backup or export format, a share code, a derived
   identifier such as a scheduled notification id, a date-keyed pick) is pinned in a describe titled
   `[contract] <unit> goldens`, registered in `contracts/goldens.json`, with at least three keys and,
   for date keys, a year-end/new-year pair. An existing entry is never edited, deleted or renamed, not
   even with a trailer; adding keys is fine. If the producing code must change, stop and ask: ship a
   versioned format next to the old one, or switch inputs from a future date. Why: users on the old
   and the new version would get different results from the same input; renaming a title deletes
   the entry (the key is the title).
5. **Data goldens are readable text from pure code.** `<unit>.golden.test.ts` next to the unit, one
   string per case (a header line with the inputs and headline numbers, then short lines or an ASCII
   grid), stored by jest-expo as `<file>.golden.test.ts.snap.ios` next to the test; at most 120 lines
   per entry (aim for 60); no clock, machine locale or unseeded randomness; no rendering. Why: a golden
   is reviewed by reading its diff, and a machine-dependent golden differs between runs.
6. **No component-tree snapshots and no inline snapshots, anywhere.** A `.snap` of a non-golden test
   is deleted and replaced by assertions on roles and text; `toMatchInlineSnapshot` is never used.
   Why: component trees churn on every style change and train `-u` reflexes; `-u` would rewrite the
   test file itself, and Jest 29 with Prettier 3 fails the suite outright (verified).
7. **Pixel goldens (apps that draw with Skia) render the production draw function** offscreen in the
   CanvasKit `golden` project, under `test/goldens/`, at three canvas sizes (narrow 320x400, phone
   390x560, tablet 1024x700; a fixed-size drawing says `// fixed-size: <why>`, and a pipeline smoke
   test that draws a function defined in the test is exempt) and, when it animates,
   at moments 0, 0.5 and 1, with fonts loaded explicitly, through the one matcher
   `test/goldens/skia-golden.ts` (`toMatchPixelGolden`), never a per-call threshold.
   `jest-image-snapshot` 6.5.2 and `@types/jest-image-snapshot` 6.4.2 are pinned exactly. Why: goldens
   catch what assertions forget only when they draw what users see, at the sizes they see it.
8. **Tolerances are gates:** 0.1% of pixels for Skia goldens (the matcher), 0.2% for simulator and
   emulator screenshots (e2e-maestro). Never raise one to hide a diff; a raise needs the reviewer's
   agreement first, then the matcher and `contracts/goldens.json` `maxPixelTolerance` change together
   in a commit with `Gate-Change: <name> <old> -> <new> approved by <reviewer>: <reason>`. Why: a
   raised tolerance silently accepts every future regression below it.
9. **Snapshots never outlive their tests and diffs never reach git.** An obsolete entry is removed with
   `-u` on that one file; an orphan `.snap` or baseline PNG is deleted with its test
   (`baseline-orphan`); `.gitignore` lists `reports/` and `**/__image_snapshots__/__diff_output__/`; `quality-gates.json` `gatedPaths` lists the golden paths.
   Why: an obsolete entry makes `jest --ci` exit 1 even when every test passed (verified), and a
   golden path missing from the gate is changed without a trailer.
10. **A failing golden is investigated, not re-accepted.** Decide: a bug (fix the code, keep the
    golden), intended (update that one file, rules 1 to 3) or a contract entry (always a bug). A
    golden that differs between two runs of the same commit means the code reads time or randomness.
    Why: the generators, formatters and CanvasKit are deterministic, so noise is a bug.

## Workflow

1. **Know the policy** once per session: read [references/golden-policy.md](references/golden-policy.md)
   (the kinds of golden, where each lives, the only way to change one, contract entries, failure
   triage, iOS and Android notes, "When multi-package").
2. **Pick the kind.** Readable output a reviewer checks: a data golden. Output installed versions
   must reproduce: a `[contract]` describe in a data golden. A Skia surface: a pixel golden. A whole
   screen on a device: a screenshot baseline (e2e-maestro). Seeded generator output: golden vectors
   (seeded-determinism-and-golden-vectors). Then read
   [references/data-goldens.md](references/data-goldens.md) or
   [references/pixel-goldens.md](references/pixel-goldens.md).
3. **A data golden:** if `test/goldens/golden-text.ts` is missing, copy it and its test from
   `templates/test/goldens/`. Imitate `templates/src/features/__FEATURE__/__FEATURE__-digest.golden.test.ts`
   (the digest unit and its reviewed `.snap.ios` show a complete, verified pair): a `describe<Unit>()`
   function that returns one string, fixed inputs, titles that start with a third-person verb.
4. **A contract:** put its cases in `describe('[contract] <unit> goldens', ...)`, pin at least three
   keys (a year-end/new-year pair for date keys, and a leap day), and register it in
   `contracts/goldens.json` (the first time, copy `templates/contracts/goldens.json` and its schema and
   replace the sample digest entry with yours; the checker fails a marked describe the register does
   not list, and an app with no contract needs no register). [examples/backup-envelope.golden.test.ts](examples/backup-envelope.golden.test.ts)
   shows a format contract.
5. **A pixel golden:** if `test/goldens/skia-golden.ts` is missing, copy
   [templates/test/goldens/skia-golden.ts](templates/test/goldens/skia-golden.ts) and run
   `npm install --save-dev --save-exact jest-image-snapshot@6.5.2 @types/jest-image-snapshot@6.4.2`
   (without the types, `npm run typecheck` fails with TS7016). The surface's golden test, draw code and
   layout come from skia-canvas-rendering's template.
6. **Create the goldens deliberately:** `npx jest <file> --selectProjects golden --listTests` (it must
   list only that file), then `npx jest <file> --selectProjects golden -u`. Read every new entry or
   open every new PNG with your file-reading tool, compare it with what users should get, then
   `CI=1 npx jest --ci --selectProjects golden`.
7. **Check the tree:** `node ${CLAUDE_SKILL_DIR}/scripts/check-goldens.mjs .` and fix every `FAIL`
   line (file, rule, fix); rerun until `RESULT: PASS`. Rules and options:
   [references/checkers.md](references/checkers.md).
8. **Commit with the trailer** ([examples/gate-change-commit.txt](examples/gate-change-commit.txt)):
   write the message to a file, stage, run
   `node ${CLAUDE_SKILL_DIR}/scripts/check-golden-changes.mjs . --staged --message <file>`, commit. At
   the end of the session run it with `--range <base>..HEAD` (base: the commit before the session's
   first); in CI, `--range origin/main..HEAD`.
9. **When a golden fails later:** follow "When a golden fails" in the policy reference. Bug: fix the
   code. Intended: step 6 for that one file, then step 8. A contract entry changed: revert, or stop and
   ask the reviewer. A wide re-acceptance (a Skia or font upgrade) follows run-goldens-rebaseline;
   after a Jest major (SDK 58 brings Jest 30) every file fails on its header: "Jest upgrades" in the policy.

## Definition of done

- [ ] Every data golden has its `.snap.ios`, every pixel golden its baselines, and
      `CI=1 npx jest --ci --selectProjects golden` passes with no obsolete snapshot.
- [ ] Every new or changed entry was read and every new or changed PNG opened; the report names them
      and why they changed.
- [ ] Every contract is registered in `contracts/goldens.json`, pins at least three keys (a
      year-boundary pair for date keys), and no existing `[contract]` entry changed.
- [ ] No script, hook or CI job writes goldens; no tolerance went up without an approval trailer.
- [ ] Every golden change sits in a commit with a `Gate-Change:` trailer, and
      `node ${CLAUDE_SKILL_DIR}/scripts/check-golden-changes.mjs . --range <base>..HEAD` prints

From zakariaf/ReactNative-Skills, MIT.

More from zakariaf/ReactNative-Skills