agentinit / rules

---
description: Behavior assertions, top-level vi.mock, and fake timers.
globs: "**/*.test.tsx,**/*.spec.tsx,*.test.ts,*.spec.ts,src/**/*.test.ts,src/**/*.spec.ts,app/**/*.test.ts,app/**/*.spec.ts,lib/**/*.test.ts,lib/**/*.spec.ts,server/**/*.test.ts,server/**/*.spec.ts,pages/**/*.test.ts,pages/**/*.spec.ts,components/**/*.test.ts,components/**/*.spec.ts,test/**/*.test.ts,test/**/*.spec.ts,tests/*.test.ts,tests/unit/**/*.test.ts,tests/integration/**/*.test.ts,__tests__/**/*.test.ts,__tests__/**/*.spec.ts"
alwaysApply: false
---

## Boundary
`describe` groups the tests for one unit. `it` and `test` are the same function. `vi.mock` is hoisted to the top of the file and runs before imports. `vi.useFakeTimers` replaces `setTimeout`, `setInterval`, and `Date` until `vi.useRealTimers`. `toMatchSnapshot` compares serialized output with a file stored next to the test.

## Directives
- **ALWAYS** group one unit's tests in a `describe` named for that unit. **ALWAYS** name `it` or `test` after a result the caller can observe, such as `returns 0 for an empty cart`. **NEVER** name a test after an internal call.
- **ALWAYS** assert an observable result: the returned value, the thrown error, or a callback the caller passed in. **NEVER** assert the order of calls inside the unit.
- **ALWAYS** call `vi.mock` at the top level of the test file, with `vi` imported from `vitest`, and only for a module the unit does not own. **NEVER** mock the module under test.
- **ALWAYS** call `vi.useFakeTimers()` before code that schedules a timer, then advance with `vi.advanceTimersByTime` or `vi.runAllTimers`. **ALWAYS** call `vi.useRealTimers()` before the file moves on.
- **PREFER** `expect(value).toEqual` when the expected value can be written in the test. Use `toMatchSnapshot` only for a large stable structure. **NEVER** accept a snapshot update without reading the diff.
- **ALWAYS** run the suite with `pnpm test`.

## Contract
```ts
import { afterEach, describe, expect, it, vi } from "vitest";
import { priceAfter } from "./price-after";

vi.mock("./rates", () => ({
  loadRate: () => 2,
}));

function runLater(callback: () => void, ms: number) {
  setTimeout(callback, ms);
}

describe("priceAfter", () => {
  it("returns the price times the rate", () => {
    expect(priceAfter(10)).toBe(20);
  });
});

describe("runLater", () => {
  afterEach(() => {
    vi.useRealTimers();
  });

  it("runs the callback after one second", () => {
    vi.useFakeTimers();
    const callback = vi.fn();
    runLater(callback, 1000);
    vi.advanceTimersByTime(1000);
    expect(callback).toHaveBeenCalledTimes(1);
  });
});

// ❌ Anti-pattern: a hoisted mock of the unit, and a name that describes an internal call
// vi.mock("./price-after");
// it("calls loadRate", () => {
//   expect(true).toBe(true);
// });
```