Docs/process: regenerate snapshots with a full `vitest run -u` after theme edits

[IgorShevchik]

Background

During the live nuxt/ui→b24ui sync ports (#72), regenerating snapshots with a targeted command like:

pnpm exec vitest run -u test/components/Select.spec.ts test/components/SelectMenu.spec.ts ...

intermittently did not update the first component(s) in the run — the test rendered against a stale compiled theme (#build/b24ui/*) and the snapshot wasn't refreshed. A subsequent full pnpm exec vitest run -u always fixed it. This caused a false "green" -u followed by a failing non--u verify.

Proposal — document the rule (and optionally harden)

After editing any src/theme/*.ts, regenerate snapshots with a full run, not a targeted one:

pnpm run dev:prepare
pnpm exec vitest run -u        # full suite
pnpm exec vitest run           # verify green (no -u)

Where to put it:

• A note in the sync workflow guidance (.sync/PORTING.md reviewer/runbook section) and/or AGENTS.md "Key Conventions".
• Optionally harden: vitest.config.ts with cache: false under CI=true, or a test:update script that always runs the full suite.

Priority: P3 (process/DX). Context: PR #72; same staleness hit ContextMenu and InputMenu during that PR.

[IgorShevchik]

Done in #498 — and you were right about the symptom, we were wrong twice about the cause before landing on it. Worth the retelling.

You reported a green -u followed by a failing verify during the #72 ports. The first attempt at explaining it blamed a stale compiled theme under #build/b24ui/*. Confident, plausible, completely made up: revert the theme, re-run the same targeted update, and the snapshot comes back clean every single time. Review called it, and re-running it step by step agreed with review.

What actually happens is much dumber, and therefore much better:

$ pnpm exec vitest run -u test/components/Kbd.spec.ts --project nuxt
  Snapshots  77 updated
 Test Files  161 passed (161)      ← one file named. 161 run.

$ pnpm exec vitest run test/components/Kbd.spec.ts -u --project nuxt
  Snapshots  10 updated
 Test Files  1 passed (1)

-u swallows the next token as its value, so the path stops being a filter and the whole project updates. The false green follows from there, and it survives because the damage lands where nobody is looking. Marking src/theme/kbd.ts, updating that way, then reverting the theme:

2. revert the theme, targeted -u  →  Kbd's 10 come back clean. The four
                                     unnamed files are never re-rendered,
                                     so their marker stays on disk.
3. targeted verify                →  11 passed. Green.
4. pnpm run test run              →  5 failed, in ContentSearchButton —
                                     a component the change never touched.

Step 3 is your report, exactly. Every command the author ran was green; a snapshot on disk was wrong.

So there is now one safe command, and it takes no path on purpose:

pnpm run test:update    # the whole suite
pnpm run test run       # verify, without -u

The reproduction with its measured counts lives in the testing guide, the rule is in .sync/PORTING.md where a porter meets it mid-port, and the published contributor guide no longer tells anyone to press u.

A prompt that gets an agent to do this correctly:

Regenerate snapshots with pnpm run test:update — the full suite, never a path. Then verify with pnpm run test run and read the diff before committing. If you see a snapshot change in a component you did not touch, that is the bug, not noise.

Thanks for filing it as "intermittent" rather than shrugging — it wasn't intermittent, it was invisible, and those are the good ones. 🕵️

— from the repo owner

---

Generated by Claude Code