test-hygiene
Use when writing, modifying, or working near test code, when tests look tautological or snapshot-based, when adding a done-when check, or when covering error paths. Don't use for production-only edits with no tests, docs, or UI copy.
AlemTuzlak · AI review on file
Installation
Read the source and dependencies before running a command. Copying does not install or execute anything.
npx skills add AlemTuzlak/skills --skill test-hygieneAbout this skill
name: test-hygiene description: Use when writing, modifying, or working near test code, when tests look tautological or snapshot-based, when adding a done-when check, or when covering error paths. Don't use for production-only edits with no tests, docs, or UI copy.
Test Hygiene
This skill owns what a test pins and how the test file is written. It replaces any older test-hygiene copy.
A test is tautological if it still passes after you delete the production logic. Do not ship that test. Expected must be an independent value (literal or small fixture), not the implementation talking to itself.
When To Use
Load when writing or changing tests, when working near a test file, or when a plan node needs a done when check.
Skip production-only edits with no tests, docs, and UI copy.
This skill does not force tests first. The pin must still fail if the production logic is gone.
What to pin
Pin observable behavior only: return value, thrown error, rendered UI, or a real side effect (HTTP, DB, file).
Do not pin private helpers, internal call order, or framework wiring.
Critical path: the user-visible success path for this change, plus runtime failures that can still happen (empty list, network error, missing field from an API).
How many: one happy critical path, plus one test per distinct runtime edge. Stop when a new test does not fail for a different reason.
Types already forbid it: do not test “wrong input fails.” TypeScript blocked that call. Do not invent cases that cannot happen.
Collaborators: if fetchOrder calls isOrderValid, read isOrderValid tests first. fetchOrder tests pin fetchOrder branches only. Do not replay isOrderValid cases through fetchOrder unless that path is critical to success. Do not write the same behavior in five files.
If isOrderValid has no tests, write them next to isOrderValid first. Then keep fetchOrder tests on fetchOrder branches.
How to assert
- Derive expected from the rule or spec, as a literal or small fixture. Then run the code. Then compare.
- Banned:
toMatchSnapshot,toMatchInlineSnapshot, and any snapshot as the expected value. - Banned:
expect(fn(x)).toBe(fn(x)), copying the production formula into expected,expect(obj.name).toBe(obj.name). - Banned: a mock-only test that only proves the test called its own mock with the args it passed in, and still passes if the unit is deleted.
- Mocks: I/O at the boundary only (HTTP, DB, clock, filesystem). Do not mock the unit under test. Do not mock code you wrote.
// BAD: expected is the formula under test
expect(discount(100, "gold")).toBe(100 * 0.75);
// BAD: still green if fetchOrder is empty; the mock was the test
await fetchOrder("1");
expect(http.get).toHaveBeenCalledWith("/orders/1");
// GOOD: independent expected; mock is the network only
http.get.mockResolvedValue({ id: "1", status: "open" });
expect(await fetchOrder("1")).toEqual({ id: "1", status: "open" });
Phase 1: Reconnaissance (Before Writing)
- Search the current package (and neighbors) for
test-utils,test-helpers,setup,__mocks__/, factories, fixtures. - If
AcallsB, read B’s tests. Do not duplicate B’s matrix in A. - If modifying a test file, list casts, duplicated setup, and dynamic imports for cleanup.
- Decide helpers: existing util, file-local if only this file needs it, shared test-utils if another file in this package wants it.
Phase 2: Enforcement (During and After Writing)
All rules below apply to new test code and to existing code in the same file. Preserve test semantics when cleaning up. Only change how they are written, not what they verify. Do not touch unrelated test files.
Rule 1: Reusable utilities over duplication
Same setup, assertion, or mock pattern in 2+ tests → extract a helper. Each it() is slim after setup. Parameterize. If you extract a helper, use it everywhere in this file.
// BAD: same three lines in every test
it("returns the open order", async () => {
http.get.mockResolvedValue({ id: "1", status: "open" });
const order = await fetchOrder("1");
expect(order.status).toBe("open");
});
// GOOD
async function fetchOrderWith(body: Order) {
http.get.mockResolvedValue(body);
return fetchOrder(body.id);
}
it("returns the open order", async () => {
const order = await fetchOrderWith({ id: "1", status: "open" });
expect(order).toEqual({ id: "1", status: "open" });
});
Rule 2: No type casts and no lazy types
Banned: as any, as unknown as X, double casts.
If a mock does not match the interface, build a typed factory. Writing a factory is cheap.
Only exception: TypeScript has a real limitation that cannot be worked around. Then add a comment that says why. as const is allowed. It narrows, it does not widen.
Banned: Record<string, unknown> as a lazy stand-in. Use the real type.
Banned: generic cast helpers like field<T>(obj, key): T.
Prefer as const on test data. Prefer inferred return types on factories.
// BAD
const order = { id: "1", status: "open" } as any;
// GOOD
function createOrder(overrides?: Partial<Order>): Order {
return { id: "1", status: "open", ...overrides };
}
Rule 3: No dynamic or conditional imports in test bodies
All imports at module scope.
Banned: await import(...) inside describe, it, beforeAll, beforeEach, afterAll, afterEach.
For vitest mocks that need a re-import after vi.mock(), use vi.hoisted() and top-level await import(), not inside tests.
// BAD
it("throws when missing", async () => {
const { OrderNotFoundError } = await import("./order");
})
Read the complete source ↗