tdd-workflow
Drives every Pocket Arcade code change test-first - one failing test seen red for the right reason, minimum code, refactor, check:fast - plus layer order and evidence. Use when writing or changing product code or deciding what to test. Not for test helpers or Jest setup (unit-and-component-tests).
- License 许可
- MIT
- 最近更新
- 2026-11-05
- Stars
- ★ 0
- Forks
- 0
01 前言 Front Matter
- name
- tdd-workflow
- description
- Drives every Pocket Arcade code change test-first - one failing test seen red for the right reason, minimum code, refactor, check:fast - plus layer order and evidence. Use when writing or changing product code or deciding what to test. Not for test helpers or Jest setup (unit-and-component-tests).
02 资源文件 96
- 资产文件assets/shared.json73 B
- 参考文档examples/slice-walkthrough.md7.2 KB
- 参考文档references/build-order.md8.7 KB
- 参考文档references/definition-of-done.md6.3 KB
- 参考文档references/tdd-loop.md8.1 KB
- 参考文档references/test-conventions.md8.3 KB
- 脚本scripts/check-lib.mjs44.4 KB
- 脚本scripts/check-test-edits.mjs15.7 KB
- 脚本scripts/check-tests.mjs14.0 KB
- 脚本scripts/selftest.mjs557 B
- 其他templates/component.test.tsx1015 B
- 脚本templates/logic.test.ts1.8 KB
- 参考文档templates/slice-plan.md1.1 KB
- 参考文档tests/fixtures/check-test-edits/bad-assertion-changed/EXPECT.txt52 B
- 其他tests/fixtures/check-test-edits/bad-assertion-changed/history.log2.3 KB
- 参考文档tests/fixtures/check-test-edits/bad-code-without-test/EXPECT.txt37 B
- 其他tests/fixtures/check-test-edits/bad-code-without-test/history.log1.8 KB
- 参考文档tests/fixtures/check-test-edits/bad-device-only-mixed/EXPECT.txt34 B
- 其他tests/fixtures/check-test-edits/bad-device-only-mixed/history.log1.1 KB
- 参考文档tests/fixtures/check-test-edits/bad-device-only-no-reason/EXPECT.txt80 B
- 其他tests/fixtures/check-test-edits/bad-device-only-no-reason/history.log755 B
- 参考文档tests/fixtures/check-test-edits/bad-disabled-next-to-skills/EXPECT.txt127 B
- 其他tests/fixtures/check-test-edits/bad-disabled-next-to-skills/history.log976 B
- 参考文档tests/fixtures/check-test-edits/bad-disabled-test-added/EXPECT.txt28 B
- 其他tests/fixtures/check-test-edits/bad-disabled-test-added/history.log1.8 KB
- 参考文档tests/fixtures/check-test-edits/bad-test-deleted/EXPECT.txt37 B
- 其他tests/fixtures/check-test-edits/bad-test-deleted/history.log1.9 KB
- 参考文档tests/fixtures/check-test-edits/bad-weakened-test-only/EXPECT.txt26 B
- 其他tests/fixtures/check-test-edits/bad-weakened-test-only/history.log1.7 KB
- 其他tests/fixtures/check-test-edits/good/history.log5.8 KB
- 参考文档tests/fixtures/check-test-edits/pass-fit-in-comment/EXPECT.txt61 B
- 其他tests/fixtures/check-test-edits/pass-fit-in-comment/history.log1.5 KB
- 参考文档tests/fixtures/check-test-edits/pass-generated-file/EXPECT.txt61 B
- 其他tests/fixtures/check-test-edits/pass-generated-file/history.log800 B
- 参考文档tests/fixtures/check-test-edits/pass-spec-change-swap/EXPECT.txt61 B
- 其他tests/fixtures/check-test-edits/pass-spec-change-swap/history.log1.6 KB
- 参考文档tests/fixtures/check-tests/bad-component-snapshot/EXPECT.txt42 B
- 其他tests/fixtures/check-tests/bad-component-snapshot/packages/shell/src/ui/play-button.test.tsx172 B
- 参考文档tests/fixtures/check-tests/bad-device-only-reason/EXPECT.txt45 B
- 脚本tests/fixtures/check-tests/bad-device-only-reason/packages/shell/src/services/clock/system-clock-adapter.ts204 B
- 参考文档tests/fixtures/check-tests/bad-disabled-test/EXPECT.txt29 B
- 脚本tests/fixtures/check-tests/bad-disabled-test/packages/game-kit/src/rng/pick.test.ts153 B
- 参考文档tests/fixtures/check-tests/bad-focused-fit/EXPECT.txt40 B
- 脚本tests/fixtures/check-tests/bad-focused-fit/packages/game-kit/src/rng/pick.test.ts312 B
- 脚本tests/fixtures/check-tests/bad-focused-fit/packages/game-kit/src/rng/pick.ts152 B
- 参考文档tests/fixtures/check-tests/bad-no-assertion/EXPECT.txt38 B
- 脚本tests/fixtures/check-tests/bad-no-assertion/packages/game-kit/src/rng/pick.test.ts164 B
- 参考文档tests/fixtures/check-tests/bad-node-in-app-test/EXPECT.txt49 B
- 脚本tests/fixtures/check-tests/bad-node-in-app-test/packages/shell/src/services/save/save-file.test.ts208 B
- 参考文档tests/fixtures/check-tests/bad-nondeterminism/EXPECT.txt58 B
- 脚本tests/fixtures/check-tests/bad-nondeterminism/packages/shell/src/services/clock/day-key.test.ts196 B
- 脚本tests/fixtures/check-tests/bad-nondeterminism/test/integration/save/load.perf.test.ts273 B
- 参考文档tests/fixtures/check-tests/bad-retry/EXPECT.txt26 B
- 脚本tests/fixtures/check-tests/bad-retry/packages/game-kit/src/rng/pick.test.ts158 B
- 参考文档tests/fixtures/check-tests/bad-spec-file/EXPECT.txt28 B
- 脚本tests/fixtures/check-tests/bad-spec-file/packages/game-kit/src/rng/__tests__/pick.spec.ts147 B
- 参考文档tests/fixtures/check-tests/bad-title/EXPECT.txt43 B
- 脚本tests/fixtures/check-tests/bad-title/packages/game-kit/src/rng/pick.test.ts154 B
- 脚本tests/fixtures/check-tests/bad-tooling-build-test/.claude/skills/demo/b.test.ts108 B
- 脚本tests/fixtures/check-tests/bad-tooling-build-test/apps/line-siege/src/rules/apply-move.golden.test.ts263 B
- 脚本tests/fixtures/check-tests/bad-tooling-build-test/apps/line-siege/src/rules/apply-move.ts116 B
- 参考文档tests/fixtures/check-tests/bad-tooling-build-test/EXPECT.txt61 B
- 脚本tests/fixtures/check-tests/bad-tooling-build-test/packages/game-kit/src/levels/level-types.ts168 B
- 脚本tests/fixtures/check-tests/bad-tooling-build-test/packages/game-kit/src/levels/pack-sizes.ts201 B
- 脚本tests/fixtures/check-tests/bad-tooling-build-test/packages/game-kit/src/levels/stars-for-moves.test.ts675 B
- 脚本tests/fixtures/check-tests/bad-tooling-build-test/packages/game-kit/src/levels/stars-for-moves.ts235 B
- 脚本tests/fixtures/check-tests/bad-tooling-build-test/packages/game-kit/src/testing/make-level.ts140 B
- 脚本tests/fixtures/check-tests/bad-tooling-build-test/packages/shell/src/services/clock/day-key.ts129 B
- 脚本tests/fixtures/check-tests/bad-tooling-build-test/packages/shell/src/services/clock/fake-clock.ts169 B
- 脚本tests/fixtures/check-tests/bad-tooling-build-test/packages/shell/src/services/save/expo-sqlite-sql-driver.ts397 B
- 其他tests/fixtures/check-tests/bad-tooling-build-test/packages/shell/src/ui/play-button.test.tsx225 B
- 脚本tests/fixtures/check-tests/bad-tooling-build-test/skills/tdd-workflow/tests/fixtures/check-tests/bad-disabled-test/a.test.ts108 B
- 脚本tests/fixtures/check-tests/bad-tooling-build-test/test/integration/save/save-file.test.ts271 B
- 脚本tests/fixtures/check-tests/bad-tooling-build-test/test/integration/save/save-write.perf.test.ts669 B
- 脚本tests/fixtures/check-tests/bad-untested-module/apps/line-siege/src/rules/list-moves.ts168 B
- 参考文档tests/fixtures/check-tests/bad-untested-module/EXPECT.txt30 B
- 参考文档tests/fixtures/check-tests/bad-use-test/EXPECT.txt22 B
- 脚本tests/fixtures/check-tests/bad-use-test/packages/game-kit/src/rng/pick.test.ts139 B
- 脚本tests/fixtures/check-tests/good/.claude/skills/demo/b.test.ts108 B
- 脚本tests/fixtures/check-tests/good/apps/line-siege/src/rules/apply-move.golden.test.ts263 B
- 脚本tests/fixtures/check-tests/good/apps/line-siege/src/rules/apply-move.ts116 B
- 脚本tests/fixtures/check-tests/good/packages/game-kit/src/levels/level-types.ts168 B
- 脚本tests/fixtures/check-tests/good/packages/game-kit/src/levels/pack-sizes.ts201 B
- 脚本tests/fixtures/check-tests/good/packages/game-kit/src/levels/stars-for-moves.test.ts675 B
- 脚本tests/fixtures/check-tests/good/packages/game-kit/src/levels/stars-for-moves.ts235 B
- 脚本tests/fixtures/check-tests/good/packages/game-kit/src/testing/make-level.ts140 B
- 脚本tests/fixtures/check-tests/good/packages/shell/src/services/clock/day-key.ts129 B
- 脚本tests/fixtures/check-tests/good/packages/shell/src/services/clock/fake-clock.ts169 B
- 脚本tests/fixtures/check-tests/good/packages/shell/src/services/save/expo-sqlite-sql-driver.ts397 B
- 其他tests/fixtures/check-tests/good/packages/shell/src/ui/play-button.test.tsx225 B
- 脚本tests/fixtures/check-tests/good/skills/tdd-workflow/tests/fixtures/check-tests/bad-disabled-test/a.test.ts108 B
- 脚本tests/fixtures/check-tests/good/test/integration/save/save-file.test.ts271 B
- 脚本tests/fixtures/check-tests/good/test/integration/save/save-write.perf.test.ts669 B
- 参考文档tests/fixtures/check-tests/pass-fit-in-title/EXPECT.txt11 B
- 脚本tests/fixtures/check-tests/pass-fit-in-title/packages/game-kit/src/rng/pick.test.ts445 B
- 脚本tests/fixtures/check-tests/pass-fit-in-title/packages/game-kit/src/rng/pick.ts152 B
03 SKILL.md 正文
Test-driven workflow
Every behaviour in Pocket Arcade is built red-green-refactor: a failing test that quotes the spec, the least code that turns it green, a refactor, the fast gate, and one commit holding test and code together. The owner never reads the code, so the tests are both the specification and the evidence; two scripts prove the tree and the history follow the rules.
Rules that must hold
- No product code without a red test seen failing for the right reason. Run it and read the failure: an assertion diff (
Expected ... Received ...), never an import, type or syntax error. A test that was never red proves nothing. - Red and green in the same commit, one behaviour per commit. Never commit a failing test; pre-commit reruns related tests and history must show test and code arriving together.
- Never edit an existing assertion to make it pass. Fix the code. Only a spec change may change an expectation, and the commit then carries
Spec-Change: <spec section and what changed>. "The test was wrong" is never a Spec-Change. A swap the build order directs is one: Shell step 8 replaces the bootstrap's phase-0with-shell.tsand its test with architecture-and-boundaries' final pair, and that commit carries exactlySpec-Change: with-shell final composer (phase 0 placeholder replaced). - Never skip, focus, retry or weaken: no
.skip,.only,.failing,.todo,xit,fit,jest.retryTimes, component snapshots, lowered thresholds,eslint-disableor--no-verify. If a gate looks wrong, stop and ask the owner. - Quote the spec line in the first test (title or comment above it:
it('counts only the first completion of the day (spec S9)')). Print it with the product-spec lookup, never from memory. - Build in layer order: rules -> level generator -> save and migrations -> services with fakes -> hooks -> screens -> end-to-end flows -> screenshot matrix. Each layer is tested before anything depends on it.
- Pure logic gets examples, fast-check properties and at least one pinned exact value in the same file. Properties alone left 3 of 8 random-number mutants alive in the probes.
- Tests are deterministic: no
Math.random,Date.now,new Date(),performance.now(), real timers, network, locale or time zone. Inject the fake clock and the seeded random-number generator. The one exception is a perf budget test (test/**/<name>.perf.test.ts), which times real work withperformancefromnode:perf_hooks. - Tests live where they run:
<unit>.test.ts(x)next to the unit,*.golden.test.tsfor data goldens,*.sim.test.tsundertest/sims/, Node-API tests undertest/. Titles start with a third-person verb orcan; useit, nevertest. - Each kind of change carries its evidence (
references/definition-of-done.md): UI changes also need screenshots in en and fa, light and dark, matched against the Toybox design screenshot.
Workflow
- Start from green (once per session, from the repo root):
git statusandgit log --oneline -10(never discard work you did not make; ask about it), notegit rev-parse --short HEADas the session's<base>, thennpm run -s check:fast. If it is red, getting back to green is the first slice, and the report says what was broken. - Find the spec lines the task serves (the
pocket-arcade-product-specskill prints each entry exactly; never quote from memory) and write the plan with templates/slice-plan.md: behaviour in one sentence, first test title, files, evidence. - Place the slice in the build order (references/build-order.md). If a lower layer it needs is untested, build that slice first.
- Write one failing test. Copy templates/logic.test.ts (pure logic) or templates/component.test.tsx (a component) next to the unit and replace every
__PLACEHOLDER__. Names and places follow references/test-conventions.md. - Run it and read the failure:
npx jest --ci <test-file>(to see a slice's coverage without a verdict:npx jest <paths> --ci --selectProjects unit --coverage --collectCoverageFrom='<path>/**/*.ts' --coverageThreshold='{}', paths first; onlynpm run test:coveragejudges the thresholds). If it fails on an import or a type, add a typed stub that returns a wrong value and rerun until the failure is an assertion diff (references/tdd-loop.md, "Red for the right reason"). Keep the red lines for the report. - Write the minimum code to turn that test green, rerun. Add the next example, see it red, make it green. For pure logic add the properties and the pinned value; turn any fast-check counterexample into an example test first.
- Refactor by responsibility (split a module, extract a pure function with its own test); tests stay green.
- Run the fast gate and the tree check from the repo root:
npm run -s check:fast, thennode ${CLAUDE_SKILL_DIR}/scripts/check-tests.mjs .. Fix everyFAILline and rerun until both pass. - Commit the slice (test and code together, spec lines in the body; the
git-commits-and-reportingskill has the message format), then check the history:node ${CLAUDE_SKILL_DIR}/scripts/check-test-edits.mjs . --range <base>..HEAD(<base>from step 0). Before committing,--staged --message <file>checks the staged slice. - Collect the evidence the change kind needs from references/definition-of-done.md and report it. Read examples/slice-walkthrough.md once to see a complete slice.
Definition of done
- [ ] Every new behaviour has a test that was seen failing on an assertion before its code existed; the red lines are in the report.
- [ ] Each commit holds one behaviour with its tests and code together; no existing assertion changed without a
Spec-Change:trailer. - [ ] Pure logic has examples, properties and a pinned exact value; UI has component tests plus en/fa light/dark screenshots matched to the Toybox design.
- [ ]
npm run -s check:fastis green (andnpm run verifybefore any push). - [ ]
node ${CLAUDE_SKILL_DIR}/scripts/check-tests.mjs .andnode ${CLAUDE_SKILL_DIR}/scripts/check-test-edits.mjs . --range <base>..HEADprintRESULT: PASS
Anti-patterns
- Writing the code, then a test that passes first time. It asserts what the code does, not what the spec says. Delete the code, watch the test fail, rewrite.
- "Red" from a missing file.
Cannot find moduleis not a failing behaviour; stub the export with a wrong value and get an assertion diff. - Changing
toBe(3)totoBe(2)because the code returns 2. That is editing the test to pass;check-test-edits.mjsreports it asassertion-changed. - Parking a test with
.skip"for later". Finish the behaviour in the slice or delete the test. - A 40-line object literal in every test. Use a
make<Thing>(overrides)builder. - Snapshotting a component tree. Assert roles, accessible names and visible text; snapshots belong only in
*.golden.test.ts. - Testing through the UI what a property already proves. One level per behaviour; the flow proves the wiring, not the rule.
- Several behaviours in one commit ("add stars, packs and unlocks"). The history can no longer show that each was test-first.
Files in this skill
| File | What it is | Read/run when |
|---|---|---|
| references/tdd-loop.md | The loop, red for the right reason, commands, discipline rules, examples + properties + pinned value, determinism, counterexamples | Before the first slice of a session, and whenever a red run looks wrong |
| references/test-conventions.md | File names and places, titles, builders, banned test code, what not to test, snapshots, flaky-test policy | Workflow step 3, and when check-tests.mjs fails |
| references/build-order.md | The layer order, the Shell + pilot build order, the per-game order, first tests per layer | Workflow step 2, and when starting the Shell or a game |
| references/definition-of-done.md | Always-true items, evidence by kind of change, the test pyramid, coverage and mutation gates, where evidence files are | Workflow step 9, before calling work done |
| templates/slice-plan.md | The plan for one slice (spec lines, first test, files, evidence, red run) | Workflow step 1 |
| templates/logic.test.ts | Test file for a pure unit: pinned example, rule table, impossible input, properties | Workflow step 3 for logic |
| templates/component.test.tsx | Component test through renderWithShell, by role and name, async presses |
Workflow step 3 for a component |
| examples/slice-walkthrough.md | One complete slice (spec 8.1 stars) with the real red and green runs and the commit | Once, to see the whole loop |
scripts/check-tests.mjs |
Checks the tree: disabled or retried tests, titles, snapshots, clock and randomness in tests, Node APIs in app tests, file names, assertion-free files, untested logic modules | Workflow step 7 and the definition of done |
scripts/check-test-edits.mjs |
Checks commits (--range, --log) or the staged slice (--staged): changed assertions without Spec-Change, deleted tests, feat/fix code without a test (a // device-only: covered by ... wrapper, a file whose first 3 lines say GENERATED by <tool path> and a types-only module are exempt), newly disabled tests (call sites only: comments and strings are not read) |
Workflow step 8 and the definition of done |
scripts/selftest.mjs |
Proves both checkers pass good fixtures and catch each planted bug | After changing a checker |
scripts/check-lib.mjs |
Shared script helper, synced from the library (do not edit here) | Never by hand |
assets/shared.json |
Declares the shared files this skill copies in | When adding a shared file |
tests/fixtures/ |
Good and planted-bad inputs for the self-test (history fixtures are real git log -p output) |
When adding a rule to a checker |
Related skills
pocket-arcade-product-spec- the exact spec lines each first test quotes.unit-and-component-tests- Jest projects,renderWithShell, mocks, fast-check and coverage set-up.golden-tests- data and pixel goldens and whenjest -uis allowed.e2e-maestro- end-to-end flows and the screenshot matrix.toybox-visual-parity- matching each changed screen to its design screenshot.quality-gates- whatcheck:fastandverifyrun and how to fix a failing gate.git-commits-and-reporting- the commit message and the evidence report for each slice.
04 同仓库更多 Skills
unit-and-component-tests
Sets up Jest and writes Pocket Arcade test code - three projects, RNTL 14 async via renderWithShell, root SDK mocks, fakes, fast-check, coverage, Stryker. Use when a test needs the Shell wrapper, a mock or a fake, or Jest fails. Not for the red-green loop (tdd-workflow) or goldens (golden-tests).
typescript-and-lint-rules
Enforces Pocket Arcade's strict TypeScript 6 tsconfigs, ESLint 9 flat config, Prettier and size limits. Use when writing or splitting .ts/.tsx or fixing a tsc or lint error. Not for gate wiring (quality-gates), names (naming-conventions) or import zones (architecture-and-boundaries).
demo-skill
Builds a demo. Use when testing the pitfall checker.
demo-skill
Builds a demo. Use when testing the pitfall checker.
troubleshooting-playbook
Diagnoses and fixes Pocket Arcade failures with a catalogue of 300+ known ones (symptom, cause, fix). Use when something errors, crashes, hangs or renders wrong, or an error or log needs explaining. Not for gate setup (quality-gates) or running builds (ios-simulator-build, ios-release-testflight).
toybox-visual-parity
Proves a built Pocket Arcade screen matches its Toybox design screenshot (light/dark, en/fa) and drives the fixes: capture, element gates, sheets, sign-off. Use when any screen is built or changed, or for visual parity, design match, screenshot compare. Not for building screens (toybox-screens).