Testing
Testing conventions
The rule
This is the whole text, exactly as your agent receives it. Nothing is held back for the paid tier.
Full guidance: docs/testing.md.
What a test must do
- Assert observable behaviour, not internal structure.
- Fail for exactly one reason, and say which in its name.
- Run deterministically — no real network, no real clock, no shared state.
Structure
it('surfaces a retryable error when the token has expired', async () => {
// Arrange — the smallest setup that makes the scenario true
// Act — one call
// Expect — the outcome a caller would observe
});Mocking
Mock only at boundaries: network, storage, device APIs, third-party SDKs. Mocking your own modules ties the test to today's file layout, and it will break on a refactor that changed nothing a user can see.
Test data
Use a factory with overrides so each test states only what it cares about:
const user = makeUser({ subscriptionStatus: 'expired' });Inline literals repeated across tests hide which field the test depends on.
Fixing a bug
Write the failing test first. A bug fix without a regression test invites the same bug back.
Do not
- Do not assert on snapshot blobs nobody reads.
- Do not test third-party library behaviour; test your use of it.
- Do not skip a flaky test — fix the non-determinism or delete the test.
6 formats, one per tool
Each tab is the file that tool actually reads, at the path it actually looks in. Knowing where each one looks is most of the work of supporting it.
---
description: Testing conventions
globs: ["**/*.test.ts", "**/*.test.tsx", "**/*.spec.ts", "**/*.spec.tsx", "**/__tests__/**"]
alwaysApply: false
---
# Testing
Full guidance: `docs/testing.md`.
## What a test must do
- Assert observable behaviour, not internal structure.
- Fail for exactly one reason, and say which in its name.
- Run deterministically — no real network, no real clock, no shared state.
## Structure
```ts
it('surfaces a retryable error when the token has expired', async () => {
// Arrange — the smallest setup that makes the scenario true
// Act — one call
// Expect — the outcome a caller would observe
});
```
## Mocking
Mock only at boundaries: network, storage, device APIs, third-party SDKs.
Mocking your own modules ties the test to today's file layout, and it will
break on a refactor that changed nothing a user can see.
## Test data
Use a factory with overrides so each test states only what it cares about:
```ts
const user = makeUser({ subscriptionStatus: 'expired' });
```
Inline literals repeated across tests hide which field the test depends on.
## Fixing a bug
Write the failing test first. A bug fix without a regression test invites the
same bug back.
## Do not
- Do not assert on snapshot blobs nobody reads.
- Do not test third-party library behaviour; test your use of it.
- Do not skip a flaky test — fix the non-determinism or delete the test.
Hand-written by the module author, frontmatter and all. It is the source the four derived formats are rendered from, so a correction lands here first.
Advisory history
Every time this rule turned out to be wrong, and what we did about it.
This rule has been accurate since it was published. That is a fact about the rule, not a promise about the future — which is the whole reason this section exists.
Pro tells you the day a correction lands that affects a repo you actually have.
See what Pro adds →Every generated project gets this rule automatically — there is nothing to add. The wizard picks the rest of the stack with you and leaves a manifest, so check can tell you when any of it drifts.