vitest-testing
Vitest testing framework patterns and best practices. Use when writing unit tests, integration tests, configuring vitest.config, mocking with vi.mock/vi.fn, using snapshots, or setting up test coverage. Triggers on describe, it, expect, vi.mock, vi.fn, beforeEach, afterEach, vitest.
When & Why to Use This Skill
This Claude skill provides a comprehensive guide to Vitest testing framework patterns and best practices. It empowers developers to write high-quality unit and integration tests by offering standardized templates for assertions, asynchronous testing, and advanced mocking techniques using vi.mock and vi.fn. It is designed to streamline the testing workflow, ensure robust code coverage, and maintain consistency across JavaScript and TypeScript projects.
Use Cases
- Case 1: Writing robust unit tests using a wide range of assertions for equality, truthiness, and object matching.
- Case 2: Implementing complex mocking strategies with vi.mock and vi.fn to isolate components and services during testing.
- Case 3: Handling asynchronous code testing effectively using async/await patterns and promise matchers like .resolves and .rejects.
- Case 4: Configuring vitest.config.ts and setup files to optimize the test environment and enable detailed coverage reporting.
- Case 5: Utilizing snapshots and specialized matchers to verify UI components and complex data structures.
| name | vitest-testing |
|---|---|
| description | Vitest testing framework patterns and best practices. Use when writing unit tests, integration tests, configuring vitest.config, mocking with vi.mock/vi.fn, using snapshots, or setting up test coverage. Triggers on describe, it, expect, vi.mock, vi.fn, beforeEach, afterEach, vitest. |
Vitest Best Practices
Quick Reference
import { describe, it, expect, beforeEach, vi } from 'vitest'
describe('feature name', () => {
beforeEach(() => {
vi.clearAllMocks()
})
it('should do something specific', () => {
expect(actual).toBe(expected)
})
it.todo('planned test')
it.skip('temporarily disabled')
it.only('run only this during dev')
})
Common Assertions
// Equality
expect(value).toBe(42) // Strict (===)
expect(obj).toEqual({ a: 1 }) // Deep equality
expect(obj).toStrictEqual({ a: 1 }) // Strict deep (checks types)
// Truthiness
expect(value).toBeTruthy()
expect(value).toBeFalsy()
expect(value).toBeNull()
expect(value).toBeUndefined()
// Numbers
expect(0.1 + 0.2).toBeCloseTo(0.3)
expect(value).toBeGreaterThan(5)
// Strings/Arrays
expect(str).toMatch(/pattern/)
expect(str).toContain('substring')
expect(array).toContain(item)
expect(array).toHaveLength(3)
// Objects
expect(obj).toHaveProperty('key')
expect(obj).toHaveProperty('nested.key', 'value')
expect(obj).toMatchObject({ subset: 'of properties' })
// Exceptions
expect(() => fn()).toThrow()
expect(() => fn()).toThrow('error message')
expect(() => fn()).toThrow(/pattern/)
Async Testing
// Async/await (preferred)
it('fetches data', async () => {
const data = await fetchData()
expect(data).toEqual({ id: 1 })
})
// Promise matchers - ALWAYS await these
await expect(fetchData()).resolves.toEqual({ id: 1 })
await expect(fetchData()).rejects.toThrow('Error')
// Wrong - creates false positive
expect(promise).resolves.toBe(value) // Missing await!
Quick Mock Reference
const mockFn = vi.fn()
mockFn.mockReturnValue(42)
mockFn.mockResolvedValue({ data: 'value' })
expect(mockFn).toHaveBeenCalled()
expect(mockFn).toHaveBeenCalledWith('arg1', 'arg2')
expect(mockFn).toHaveBeenCalledTimes(2)
Additional Documentation
- Mocking: See references/mocking.md for module mocking, spying, cleanup
- Configuration: See references/config.md for vitest.config, setup files, coverage
- Patterns: See references/patterns.md for timers, snapshots, anti-patterns
Test Methods Quick Reference
| Method | Purpose |
|---|---|
it() / test() |
Define test |
describe() |
Group tests |
beforeEach() / afterEach() |
Per-test hooks |
beforeAll() / afterAll() |
Per-suite hooks |
.skip |
Skip test/suite |
.only |
Run only this |
.todo |
Placeholder |
.concurrent |
Parallel execution |
.each([...]) |
Parameterized tests |