js-testing-patterns

Skill Directory

Resolve SKILL_DIR to the absolute directory containing this SKILL.md, as shown by the current host, before using any bundled path below. Before a shell command uses $SKILL_DIR, assign it in that command or replace it with the resolved path. It is not a host-exported environment variable.

JavaScript Testing Patterns

Jest, Vitest, and React Testing Library testing patterns. For shared test quality principles (philosophy, smells, mocking decisions), see testing-patterns.

Reference Routing

| Need | Reference File | Sections to Read | |------|---------------|-----------------| | Jest/Vitest + RTL patterns | $SKILL_DIR/../testing-patterns/references/jest-vitest-patterns.md | Full file (~422L, manageable) | | Behavior vs implementation | $SKILL_DIR/../testing-patterns/references/test-philosophy.md | ## The Fundamental Shift + ## Four Core Principles | | Flaky/brittle tests | $SKILL_DIR/../testing-patterns/references/test-smells.md | ## The Six Major Test Smells (relevant subsection) | | Mock usage decisions | $SKILL_DIR/../testing-patterns/references/mocking-strategies.md | ## The Mocking Decision Framework | | AAA pattern/naming | $SKILL_DIR/../testing-patterns/references/test-structure.md | ## The AAA Pattern + ## Test Naming Conventions | | Test data strategy | $SKILL_DIR/../testing-patterns/references/test-data.md | ## Factories + ## Builders |

How to read sections: Grep for heading to find line number, Read with offset+limit.

RTL Query Priority (Best to Worst)

1. getByRole('button', { name: 'Submit' }) — accessible, resilient
2. getByLabelText('Email') — form elements
3. getByPlaceholderText() — when no label
4. getByText('Click me') — visible content
5. getByDisplayValue() — filled inputs
6. getByTestId('submit-btn') — last resort

JS Assertion Quick Reference

| Use | Instead Of | Why | |-----|-----------|-----| | toMatchObject({key: val}) | toEqual({...all fields}) | Partial match, resilient to new fields | | toHaveBeenCalledWith(x) | toHaveBeenCalled() | Verifies correct arguments | | await expect(fn()).rejects.toThrow() | Missing await | Without await, assertion silently passes | | userEvent.click() | fireEvent.click() | Simulates real user interaction | | jest.useFakeTimers() | Real timers | Deterministic, no flakiness | | toContainEqual(item) | toEqual([...all items]) | Checks membership, not exact array | | Inline snapshots | toMatchSnapshot() on large output | Reviewed in PR diff, not hidden files |

JS Red Flags

| Pattern | Why Harmful | Fix | |---------|------------|-----| | toMatchSnapshot() on large components | Never meaningfully reviewed | Use inline snapshots or specific assertions | | jest.mock() on owned modules | Tests mock wiring, not behavior | Test through public API | | toEqual for partial checks | Breaks when fields added | Use toMatchObject | | Missing await on async assertions | Silent pass | Always await expect(...).rejects | | Blanket act() wrapping | Hides real act() warnings | Let RTL handle, wrap only when needed | | Timer-dependent without fake timers | Flaky in CI | Use jest.useFakeTimers() | | getByTestId as primary query | Tests implementation | Use role/label/text queries | | fireEvent over userEvent | Not real interaction | Use @testing-library/user-event |

Async Testing Patterns

• Promises: Always await or return the promise
• Timers: jest.useFakeTimers() + jest.advanceTimersByTime(ms)
• Queries: Use findBy* (waits) not getBy* (immediate) for async content
• Act warnings: Let RTL render() handle; wrap only state updates outside RTL