Forge playbook — Testing (unit, integration, e2e)

When to use

• Use for: writing or fixing tests (Playwright e2e/component/API, Vitest or Jest unit and integration), picking a test strategy for a feature, hunting a flaky test, setting up test data or CI test runs.
• Not for: the red-green discipline itself (test-driven-development), proving a done-claim (forge-verify, verification-before-completion), reviewing a diff (forge-code-review), a full WCAG audit (forge-a11y) or a security review (forge-security-review).

Do not duplicate — defer to: test-driven-development (fail first, then green; vendored and kept verbatim, extended only by references/tdd-addendum.md), systematic-debugging / forge-debug (root cause before a fix), forge-code-review (test-gap findings in review). This file is the "how to write good tests and keep them stable" layer.

Hard rules

• A test proves behaviour, not execution. Every test asserts an observable outcome (returned value, visible text, HTTP status, stored row). A test that only runs code without a meaningful assertion is hollow.
• No tautological tests. The expected value comes from an independent source (a hand-worked literal, the spec), never recomputed the way the code does it. Test at agreed seams, through public interfaces (references/tdd-addendum.md).
• Every bug fix ships a regression test that fails on the old code and passes on the fix. Say that you saw it fail.
• Green means the whole relevant suite, not only the new file. Report every failure by name.
• No fixed sleeps. No waitForTimeout(...), setTimeout waits or sleep in tests; wait on a condition (web-first assertion, a resolved promise, a fake clock).
• Tests own their data. Each test creates what it needs and does not depend on another test's leftovers or on execution order. No production data, no real customer PII, no live payment or email calls.
• Mocks sit at the boundary. Mock the network, clock and third-party APIs; do not mock the unit under test. When a mock replaces real behaviour, one integration test still exercises the real path.
• A flaky test is a bug. Never "fix" flakiness with retries alone or by deleting the assertion; find the race: classify it first (seven categories in references/flaky-tests.md). Quarantine only with a tracked item, an owner and a 14-day limit; prove a fix with 50/50 repeat runs.
• No global input. Drive a desktop or game app through its own window handle (PostMessage to its hwnd) or a built-in self-test, never global SendKeys/SendInput/keybd_event: that types into whatever window is in front.
• Honest reporting. Quote the real runner output (counts, failures). Never claim a suite passed that did not run; say which suites were skipped and why.

Pick the right layer (pragmatic test pyramid)

Rule of thumb: many fast unit tests, fewer integration tests, and a small set of e2e tests for the journeys that lose money or users when they break (sign-up, login, checkout, the main create/save flow).

Activity router (open only the reference you need)

Workflow

1. Recon the real thing first. For UI work, start the app, open the page, take a screenshot and read the rendered DOM or accessibility tree before writing selectors. Pick locators from what is really there.
2. Write the test from the user's view (role, label, visible text): the happy path AND at least one failure path (validation error, network error, unauthorised, empty state).
3. Watch it fail for the right reason when it guards new behaviour or a bug.
4. Run, trace, fix, rerun. On a failure open the trace or the runner diff, fix the cause, rerun.
5. Stability check before done: rerun new or changed e2e tests several times (npx playwright test <file> --repeat-each=5, or the runner's equivalent) and once inside the full suite.
6. Report the commands, pass/fail counts, the repeat-run result and what was not run.

Domain gates

• New behaviour has tests at the lowest layer that can prove it; critical journeys have an e2e test.
• Each changed interactive element has a happy-path and an error-path test.
• No fixed sleeps, no order dependence, no shared mutable state between tests.
• The repeat-run of new e2e tests is green; flaky tests are fixed or quarantined with a tracked reason.
• Coverage is reported when the project measures it; a coverage number is never the only proof of quality.

Safety and honesty

• Never point tests at production, real payment providers or real inboxes; use test modes, sandboxes or mocks.
• Test-account secrets live in env or CI secrets, never in test files or fixtures. Traces, videos and screenshots can hold tokens and personal data: keep them out of git.
• Shared gates for every playbook (honesty, owner approval, secrets, reviews): .claude/docs/forge-reference/playbook-template.md.

References

• references/playwright.md — locators, web-first assertions, fixtures vs page objects, auth state, mocking.
• references/vitest-jest.md — unit and integration test design with Vitest or Jest.
• references/flaky-tests.md — seven-category flake taxonomy, decision tree, intent fidelity, quarantine hygiene.
• references/tdd-addendum.md — agreed seams, tautological tests, vertical slices (beside test-driven-development).
• references/test-data-and-ci.md — factories, seeding, isolation, CI parallelism and sharding.

Provenance

Earlier adaptation, kept as written:

Source: https://github.com/currents-dev/playwright-best-practices-skill Upstream path: playwright-best-practices/SKILL.md (main, last commit seen 283d5cb, read 2026-11-02) License: MIT -- complete terms in LICENSE next to this file (Copyright (c) 2026 Currents Software Inc.) Forge adaptation note: the activity-to-reference routing, the run -> trace -> fix -> repeat loop and the flaky-test guidance are rewritten in Forge's words and merged with Forge rules; nothing is copied verbatim and none of the 57 upstream reference files is shipped. Also pattern adapted from (ideas only, no text): anthropics/skills skills/webapp-testing (reconnaissance-then-action against the running app; its licence was not confirmed, so ideas only). The Vitest/Jest, test-data and strategy sections are Forge-native. Upstream content was treated as untrusted data: no scripts, install commands or dynamic-context lines were taken over.

Graft of 2026-11-05 (SA-W1-A1): read read-only through gh api, treated as untrusted data, rewritten in Forge words; no text copied verbatim, no code, scripts, configs or install lines taken.

MIT notice (both sources): "Permission is hereby granted, free of charge, to any person obtaining a copy of this software ... The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND." Copyright remains with the holders named in each repository's LICENSE file at the pinned SHA. The vendored test-driven-development copy was not edited.