Unit Testing (Vitest)
Guidelines for writing reliable, fast, and maintainable unit tests with Vitest in JS/TS projects. Contains 13 rules across 6 categories, prioritized by impact.
When to Apply
Reference these guidelines when:
- Writing new unit tests for functions, classes, or components
- Adding or reviewing
vi.fn()/vi.mock()/vi.spyOn()usage - Configuring Vitest coverage thresholds or CI gates
- Debugging a test that's flaky, hangs, or silently passes
- Refactoring code and needing tests that won't break on implementation changes
Rule Categories by Priority
| Priority | Category | Impact | Prefix |
|---|---|---|---|
| 1 | Test Structure & Naming | HIGH | structure- |
| 2 | Assertions | HIGH | assert- |
| 3 | Mocking & Test Doubles | HIGH | mock- |
| 4 | Async & Timers | HIGH | async- |
| 5 | Coverage & CI | MEDIUM | coverage- |
| 6 | Performance & Isolation | MEDIUM | perf- |
Quick Reference
1. Test Structure & Naming (HIGH)
structure-aaa-pattern- Arrange-Act-Assert in every teststructure-descriptive-names- Name tests after behavior, not methodstructure-one-behavior-per-test- One assertion focus per test
2. Assertions (HIGH)
assert-specific-matchers- Use the most specific matcher availableassert-behavior-not-implementation- Assert output, not internals
3. Mocking & Test Doubles (HIGH)
mock-vi-fn-spyon- Choose vi.fn/vi.spyOn/vi.mock deliberatelymock-reset-restore- Reset/restore mocks between testsmock-avoid-mocking-what-you-own- Don't mock code you can test directly
4. Async & Timers (HIGH)
async-await-promises- Always await async assertionsasync-fake-timers- Use vi.useFakeTimers() instead of real delays
5. Coverage & CI (MEDIUM)
coverage-ci-thresholds- Gate CI on explicit coverage thresholdscoverage-dont-chase-100- Don't chase 100% on low-risk code
6. Performance & Isolation (MEDIUM)
perf-test-isolation- Keep tests isolated for safe parallel runs
How to Use This Skill
- Read
rules/_sections.mdfor full category descriptions. - For a specific task, open the relevant rule file(s) under
rules/— each has an incorrect/correct code example. - When reviewing existing tests, check them against the HIGH-impact rules first (structure, assertions, mocking, async), then MEDIUM.
- When writing new tests, default to the AAA pattern, prefer
vi.spyOnover fullvi.mockwhen only one function needs stubbing, and alwaysawaitasync assertions.
See rules/_template.md for the format used by every rule file.