diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md index b05df9b51405..b68459f7102c 100644 --- a/.github/pull_request_template.md +++ b/.github/pull_request_template.md @@ -30,6 +30,7 @@ Fixes # - [ ] I manually tested these changes locally - [ ] Automated tests added/updated, or explained why not below +- [ ] Every added test fails without this change and avoids the [test anti-patterns](https://github.com/stablyai/orca/blob/main/docs/agents-md-refs/test-antipatterns.md) ## Risk diff --git a/AGENTS.md b/AGENTS.md index 9aceb79a1892..40cc387546bf 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -17,7 +17,7 @@ Use `gh run watch --compact --exit-status` or `gh pr checks --watch` to - Ensure main is always releasable - Never break the CI. If it's broken borken, merge fixes. -- Avoid low-value tests (see [Anti-patterns](./docs/agents-md-refs/test-antipatterns.md)) +- **Do not add tests by default.** Low-value tests cost more than they catch. Add one only when it fails if your change is reverted, hardcodes its expected values (never computed by production code, locale files, or mocks), and runs at the single layer that owns the behavior. Never test copy/translations, CSS classes, constants, third-party libraries, private state, timing, or work counts. If you touch a test like that, delete it instead of updating it. See [anti-patterns](./docs/agents-md-refs/test-antipatterns.md). # Design System diff --git a/docs/agents-md-refs/test-antipatterns.md b/docs/agents-md-refs/test-antipatterns.md index 6897faaa1d4d..b5c3fce15b2f 100644 --- a/docs/agents-md-refs/test-antipatterns.md +++ b/docs/agents-md-refs/test-antipatterns.md @@ -1,27 +1,32 @@ # Test anti-patterns +Keep a test only if it fails when your change is reverted, its expected values are hardcoded (not computed by production code), it lives at the one cheapest layer that owns the behavior, and its size matches the change (a one-line fix gets about one case). + Tests that: -- Reimplement production logic instead of exercising it. -- Have no meaningful assertions, such as `expect(true).toBe(true)`. -- Assert only mock calls or values supplied by their own mocks. -- Promise inputs or behavior their setup never exercises. -- Claim pixel or interaction coverage from static markup. -- Duplicate coverage without faster feedback or clearer failures, including private predicates and provider replays. -- Copy inventories, manifests, exports, imports, or strings instead of proving behavior. -- Check persistence at a path the code never writes. -- Assert capability flags instead of delivery or acknowledgement. -- Pass negative cases without exercising the intended rejection path. -- Wait on real time or networks instead of fake clocks and deterministic boundaries. +- Reimplement production logic, or use it as the oracle (`expect(out).toBe(buildX(input))`). +- Assemble production pieces (pipelines, adapters, subclasses) instead of calling the real entry point. +- Assert nothing meaningful: `expect(true)`, lone `toBeDefined()`, `expect(a || b)`, `.not.toBe('')`, unpinned `toThrow()`, `not.toHaveBeenCalled()` on unreachable spies. +- Assert only mock calls, mock-supplied values, or fixtures the test built; or check `mock.calls[i][j]` when order doesn't matter. +- Promise inputs or behavior the setup never exercises, including unread fields and scale params (`it.each([1_000, 10_000])`) that change nothing. +- Claim pixel, layout, or interaction coverage from static markup, happy-dom/jsdom, or Tailwind/`data-slot` class strings. +- Re-test one contract per layer (shared/IPC/renderer/mobile/CLI), per desktop+mobile copy, or per locale/agent. +- Use Cartesian `it.each`, or branch inside a parameterized body, instead of one case per distinct behavior. +- Copy inventories, manifests, exports, strings, registry lists, or counts (`registry.size).toBe(50)`). +- Assert copy or translations (`changeLanguage('es')` + `getByText`, `key.replace('{{x}}', …)`). +- Pin constants, defaults, versions, or schema values. +- Test third-party behavior (Radix focus, zustand selectors, zod, i18next). +- Count internal work (`String.prototype` spies, getter/Proxy counts, read budgets) or assert wall-clock timing. Perf changes get correctness tests only. +- Reach into private state (`obj['x']`, `*ForTests()`, test-only subclasses). +- Check persistence at a path the code never writes, or capability flags instead of delivery. +- Wait on real time or networks instead of fake clocks. Mocks and fixtures that: -- Fake React hooks while ignoring effect dependencies or cleanup. -- Hide incorrect tables, fields, joins, filters, or arguments behind mocked internal chains. -- Contradict real producers or source contracts. -- Implement the behavior under test or treat distinct APIs as equivalent. -- Supply receipts, admission decisions, callback ordering, or other outputs production code should generate. - -Production code that: +- Fake React hooks while ignoring effect deps or cleanup. +- Hide wrong tables, fields, joins, filters, or arguments behind mocked internal chains. +- Contradict real producers (e.g. mocking a feature gate back to old logic). +- Implement the behavior under test (e.g. a mocked lock that sets the state it guards), or supply outputs production should generate. +- Are hand-copied across files instead of extending a shared typed fake. -- Adds exports, globals, wrappers, or code paths solely for tests. +Production code that adds exports, globals, wrappers, dependency overrides, or code paths only for tests.