jest

Jest Cursor Rules

You are an expert in Jest testing (v29+). Follow these rules:

Structure

• One test file per source file: user.service.ts → user.service.test.ts. Colocate tests next to source, not in a separate __tests__/ tree
• describe() for grouping related behaviors. Nest describes for sub-behaviors: describe('UserService') → describe('findById')
• it() with descriptive names that read as sentences: it("returns null when user not found") — not it("test1") or it("should work")
• Tests must be independent — no shared mutable state between test cases. If test B depends on test A running first, both tests are broken
• Arrange-Act-Assert pattern in every test: set up data, call the thing, check the result. One logical assertion per test (multiple expect calls checking one behavior is fine)

Matchers

• .toBe() for primitives and reference equality. .toEqual() for deep equality on objects/arrays — .toBe({a:1}) fails because it's a different object reference
• .toMatchObject() for partial matching — don't over-specify with .toEqual() when you only care about 3 of 10 fields. Less brittle when the shape changes
• .toThrow() requires wrapping in a function: expect(() => fn()).toThrow() not expect(fn()).toThrow() — this is the #1 gotcha
• .toHaveBeenCalledWith(expect.objectContaining({...})) for partial argument matching on mocks
• .toMatchInlineSnapshot() over .toMatchSnapshot() for small outputs — inline snapshots keep the expected value right in the test file, no separate .snap file to maintain

Mocking

• jest.fn() for standalone mock functions. jest.spyOn(object, 'method') to wrap an existing method while keeping the original accessible via .mockRestore()
• jest.mock("module") at the top level — Jest hoists it above imports automatically. Inside the mock factory, you can't reference variables from the outer scope (they're not initialized yet)
• jest.mocked(fn) for TypeScript: wraps the function type so autocomplete and type-checking work on mock methods (.mockReturnValue, .mockResolvedValue)
• jest.clearAllMocks() in beforeEach — resets call counts and return values. jest.restoreAllMocks() also undoes spyOn replacements. Pick one and be consistent
• Mock at the boundary (HTTP client, database, file system), not internal functions — testing the wiring between your own functions gives you change-detector tests, not confidence