testing
Guides writing, reviewing, and debugging Vitest tests for JavaScript and TypeScript projects, covering test structure, async handling, mocking, error cases, setup and teardown, and a review checklist of common anti-patterns. Use when writing new tests, reviewing a test file, or debugging a failing or flaky Vitest suite. Not for Python test suites.
- License 许可
- Apache-2.0
- 最近更新
- 2026-11-08
- Stars
- ★ 0
- Forks
- 0
01 前言 Front Matter
- name
- testing
- license
- Apache-2.0
- metadata
- { "owner": "razorvision", "version": "0.1.0" }
- description
- Guides writing, reviewing, and debugging Vitest tests for JavaScript and TypeScript projects, covering test structure, async handling, mocking, error cases, setup and teardown, and a review checklist of common anti-patterns. Use when writing new tests, reviewing a test file, or debugging a failing or flaky Vitest suite. Not for Python test suites.
02 资源文件 1
- 参考文档references/verify-commands.md3.4 KB
03 SKILL.md 正文
Testing Skill
Apply this skill when writing, reviewing, or debugging tests.
Test Configuration
Read the project's vitest.config.* (or the test block in vite.config.*) before writing
tests, and match it. Typical settings to check:
- Environment:
nodefor server/library code,jsdomorhappy-domfor DOM code - Timeout: raised (e.g. 30 seconds) for API/integration tests
- Pattern: where tests live, e.g.
src/**/*.test.tsor colocated*.test.ts - Env vars: how test env vars are loaded (e.g. from an env file or a setup file)
- Path alias: if the project uses path aliases (e.g.
@/mapping to./src/), use them in imports and mocks exactly as the source code does
Core Patterns
1. Test File Structure
import { describe, it, expect, beforeEach, vi } from 'vitest'
describe('ModuleName', () => {
describe('functionName', () => {
it('returns expected result when given valid input', async () => {
// Arrange
const input = { ... }
// Act
const result = await functionName(input)
// Assert
expect(result).toEqual(expected)
})
it('throws error when given invalid input', async () => {
await expect(functionName(null)).rejects.toThrow('Expected error')
})
})
})
2. Async Tests
Always use async/await for async operations:
// Correct
it('fetches data from API', async () => {
const result = await fetchData()
expect(result).toBeDefined()
})
// Wrong - missing await
it('fetches data from API', () => {
const result = fetchData() // Promise, not result!
expect(result).toBeDefined()
})
3. Specific and Realistic Assertions
For pure functions, assert exact values. For integration tests against live or variable data, use range- and shape-based assertions:
// Pure function: exact values
it('applies a percentage discount and rounds to cents', () => {
expect(applyDiscount(19.99, 0.15)).toBe(16.99)
expect(applyDiscount(100, 0)).toBe(100)
})
// Integration: realistic ranges and shapes
it('returns a plausible exchange rate', async () => {
const result = await getExchangeRate('USD', 'EUR')
// Rate should be in a realistic range
expect(result.rate).toBeGreaterThan(0.5)
expect(result.rate).toBeLessThan(2)
// Pair should match the request
expect(result.pair).toMatch(/USD\/EUR/)
// Required fields present
expect(result.source).toBeTruthy()
expect(result.fetchedAt).toBeInstanceOf(Date)
})
4. Mocking an API Client Module
import { vi } from 'vitest'
// Mock the whole module (path must match the import used in the code under test)
vi.mock('./lib/api-client', () => ({
apiClient: {
get: vi.fn().mockResolvedValue({ data: mockData, error: null }),
post: vi.fn().mockResolvedValue({ data: { id: '123' }, error: null }),
},
}))
// Or build a chainable query-builder mock for fluent SDKs
const mockDb = {
from: vi.fn().mockReturnValue({
select: vi.fn().mockReturnValue({
eq: vi.fn().mockResolvedValue({ data: [], error: null }),
}),
}),
}
5. Test Organization
Group related tests with nested describe:
describe('PaymentProvider', () => {
describe('Card payments', () => {
describe('charge', () => {
it('charges the exact amount in minor units', async () => { ... })
it('handles a declined card gracefully', async () => { ... })
it('retries once on a transient network error', async () => { ... })
})
})
describe('Bank transfers', () => {
describe('buildReference', () => {
it('includes the invoice number', () => { ... })
})
})
})
6. Setup and Teardown
describe('DatabaseTests', () => {
beforeEach(() => {
vi.clearAllMocks()
})
afterEach(async () => {
await cleanup()
})
beforeAll(async () => {
await setupTestDatabase()
})
afterAll(async () => {
await teardownTestDatabase()
})
})
7. Testing Error Cases
it('handles API errors gracefully', async () => {
// Mock API failure
vi.spyOn(global, 'fetch').mockRejectedValueOnce(new Error('Network error'))
const result = await fetchWithFallback()
expect(result.error).toBe('Network error')
expect(result.data).toBeNull()
})
it('throws on invalid input', () => {
expect(() => validateInput(null)).toThrow('Input required')
})
it('rejects promise on async error', async () => {
await expect(asyncFunction()).rejects.toThrow('Async error')
})
Running Tests
Resolve the repo's actual test commands per references/verify-commands.md rather than assuming script names. Common Vitest invocations:
# Run all tests once (CI style; does not watch)
npx vitest run
# Run a specific file
npx vitest run src/lib/discount.test.ts
# Run with coverage
npx vitest run --coverage
# Watch mode (interactive only; never use as a gate)
npx vitest
Review Checklist
When reviewing tests:
- [ ] Tests follow the project's configured file pattern
- [ ] Async tests use
async/await - [ ] Descriptive test names (behavior-focused)
- [ ] Assertions are specific (not just
.toBeTruthy()) - [ ] Error cases are tested
- [ ] Mocks are cleaned up in
beforeEach - [ ] No hardcoded delays (use fake timers)
- [ ] Integration tests use realistic ranges
Anti-Patterns
// Don't use vague assertions
expect(result).toBeTruthy() // Use specific: expect(result.id).toBe('123')
// Don't forget async
it('test', () => {
fetchData() // Missing await!
})
// Don't hardcode delays
await new Promise(r => setTimeout(r, 1000)) // Use vi.useFakeTimers()
// Don't test implementation details
expect(component.state.count).toBe(1) // Test behavior, not state
04 同仓库更多 Skills
<folder-name-lowercase-hyphens>
<What it does. Use when the user asks for <X> or mentions <Y>.>
full-skill
暂无简介
typescript
Guides TypeScript best practices for strict-mode projects, covering discriminated unions, interface contracts, nullability, type guards, utility types, async return types, const assertions, and a review checklist of common anti-patterns. Use when writing, reviewing, or debugging TypeScript code or type definitions.
staleness-check
Sweeps the repo and related sources for artifacts that a just-completed body of work should have updated but did not, such as stale doc indexes, READMEs, ADRs, registries, agent instruction files, agent memory files, issue status, and cross-references, then reports each stale item with a proposed fix. Use at the end of an epic, feature, or executed plan, or when the user says "staleness check", "did we miss anything", "are we done", or "anything stale".
software-architecture
Guides architectural decisions using Clean Architecture, separation of concerns, and SOLID principles, covering where new code should live, how modules depend on each other, and which anti-patterns to avoid, with a review checklist. Use when designing a new module or feature structure, refactoring code organization, deciding where code belongs, or reviewing a codebase's architecture.
root-cause
Traces a bug backward through the call chain to the original trigger instead of patching where the error surfaces, then fixes it at the source and adds defensive validation at intermediate layers. Use when debugging an error, a failing test, or unexpected behavior where the symptom appears far from its cause.