Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions .github/pull_request_template.md
Original file line number Diff line number Diff line change
Expand Up @@ -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)

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Minor · Maintainability & Code Quality · Quick win

Apply the test gate to updated tests too.

AGENTS.md applies this gate when contributors write or edit tests, and the anti-pattern guide says to check each test before committing. This checkbox covers only added tests, so an updated existing test can bypass the gate. Change Every added test to Every added or updated test. (github.com)


## Risk

Expand Down
2 changes: 1 addition & 1 deletion AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -17,7 +17,7 @@ Use `gh run watch <run-id> --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

Expand Down
43 changes: 24 additions & 19 deletions docs/agents-md-refs/test-antipatterns.md
Original file line number Diff line number Diff line change
@@ -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.
Loading