vitest
pproenca/dot-skills
Vitest testing framework patterns: async, mocking, setup, snapshots, and performance optimization.
What is vitest?
Comprehensive guide to Vitest best practices covering test setup, async patterns, mocking with vi.*, snapshots, and performance tuning. Use this when writing, debugging, or optimizing Vitest tests—excludes TDD methodology and MSW API mocking.
- 44 prioritized rules across 8 categories: async patterns, test setup & isolation, mocking, performance, snapshots, environment, assertions, and organization
- Async pattern guidance: await assertions, return promises, fake timers, vi.waitFor, and error handling
- Test isolation best practices: cleanup hooks, mock restoration, module resets, and test factories
- Mocking strategies: vi.mock vs vi.spyOn, implementation patterns, type safety, and avoiding over-mocking
- Performance tuning: pool selection, test isolation trade-offs, happy-dom vs jsdom, sharding, and CI optimization
- Snapshot testing rules: inline vs file snapshots, stability, and review practices
How to install vitest
npx skills add https://github.com/pproenca/dot-skills --skill vitestHow to use vitest
- 1.Reference the 8 rule categories by priority when writing or reviewing tests
- 2.Consult async patterns (CRITICAL) for any test involving promises or time-dependent code
- 3.Apply test setup & isolation rules (CRITICAL) to prevent state leakage between tests
- 4.Use mocking patterns (HIGH) to choose between vi.mock, vi.spyOn, and MSW appropriately
- 5.Check performance rules (HIGH) when tests are slow or CI is bottlenecked
- 6.Review snapshot, environment, assertion, and organization rules for code quality
Use cases
- Writing new Vitest test suites with proper async handling and isolation
- Debugging flaky or slow tests using performance and async pattern guidelines
- Setting up test configuration and environment for consistent test behavior
- Reviewing test code in pull requests against best practices
- Migrating existing Jest tests to Vitest with pattern equivalents
- Frontend and full-stack developers writing Vitest tests
- QA engineers setting up test infrastructure
- Teams migrating from Jest to Vitest
- Code reviewers evaluating test quality
- DevOps engineers optimizing CI/CD test performance
vitest FAQ
Use vi.mock for module-level mocking with hoisting; use vi.spyOn for selective method spying on existing objects. The mock-spyon-vs-mock rule provides detailed guidance.
Await async assertions, return promises from test functions, use vi.waitFor for polling conditions, and avoid act warnings by awaiting user events. See async patterns (CRITICAL) category.
happy-dom is lighter and faster for most UI tests; jsdom is more complete but slower. Use happy-dom when possible for performance (perf-happy-dom rule).
Use sharding for parallelization, run mode instead of watch mode, choose the right pool (threads vs forks), and consider disabling test isolation when safe.
No. For TDD methodology, use the test-tdd skill. For API mocking with MSW, use the test-msw skill. This skill focuses on Vitest framework patterns and vi.* APIs.
Full instructions (SKILL.md)
Source of truth, from pproenca/dot-skills.
name: vitest description: Vitest testing framework patterns for test setup, async testing, mocking with vi.*, snapshots, and test performance (formerly test-vitest). This skill should be used when writing or debugging Vitest tests. This skill does NOT cover TDD methodology (use test-tdd skill), API mocking with MSW (use test-msw skill), or Jest-specific APIs.
Vitest Best Practices
Comprehensive performance optimization and best practices guide for Vitest testing framework. Contains 44 rules across 8 categories, prioritized by impact to guide test writing, refactoring, and code review.
When to Apply
Reference these guidelines when:
- Writing new Vitest tests
- Debugging flaky or slow tests
- Setting up test configuration
- Reviewing test code in PRs
- Migrating from Jest to Vitest
- Optimizing CI/CD test performance
Rule Categories by Priority
| Priority | Category | Impact | Prefix |
|---|---|---|---|
| 1 | Async Patterns | CRITICAL | async- |
| 2 | Test Setup & Isolation | CRITICAL | setup- |
| 3 | Mocking Patterns | HIGH | mock- |
| 4 | Performance | HIGH | perf- |
| 5 | Snapshot Testing | MEDIUM | snap- |
| 6 | Environment | MEDIUM | env- |
| 7 | Assertions | LOW-MEDIUM | assert- |
| 8 | Test Organization | LOW | org- |
Quick Reference
1. Async Patterns (CRITICAL)
async-await-assertions- Await async assertions to prevent false positivesasync-return-promises- Return promises from test functionsasync-fake-timers- Use fake timers for time-dependent codeasync-waitfor-polling- Use vi.waitFor for async conditionsasync-concurrent-expect- Use test context expect in concurrent testsasync-act-wrapper- Await user events to avoid act warningsasync-error-handling- Test async error handling properly
2. Test Setup & Isolation (CRITICAL)
setup-beforeeach-cleanup- Clean up state in afterEach hookssetup-restore-mocks- Restore mocks after each testsetup-avoid-shared-state- Avoid shared mutable state between testssetup-beforeall-expensive- Use beforeAll for expensive one-time setupsetup-reset-modules- Reset modules when testing module statesetup-test-factories- Use test factories for complex test data
3. Mocking Patterns (HIGH)
mock-vi-mock-hoisting- Understand vi.mock hoisting behaviormock-spyon-vs-mock- Choose vi.spyOn vs vi.mock appropriatelymock-implementation-not-value- Use mockImplementation for dynamic mocksmock-msw-network- Use MSW for network request mockingmock-avoid-overmocking- Avoid over-mockingmock-type-safety- Maintain type safety in mocksmock-clear-between-tests- Clear mock state between tests
4. Performance (HIGH)
perf-pool-selection- Choose the right pool for performanceperf-disable-isolation- Disable test isolation when safeperf-happy-dom- Use happy-dom over jsdom when possibleperf-sharding- Use sharding for CI parallelizationperf-run-mode-ci- Use run mode in CI environmentsperf-bail-fast-fail- Use bail for fast failure in CI
5. Snapshot Testing (MEDIUM)
snap-inline-over-file- Prefer inline snapshots for small valuessnap-avoid-large- Avoid large snapshotssnap-stable-serialization- Ensure stable snapshot serializationsnap-review-updates- Review snapshot updates before committingsnap-describe-intent- Name snapshot tests descriptively
6. Environment (MEDIUM)
env-per-file-override- Override environment per file when neededenv-setup-files- Use setup files for global configurationenv-globals-config- Configure globals consistentlyenv-browser-api-mocking- Mock browser APIs not available in test environment
7. Assertions (LOW-MEDIUM)
assert-specific-matchers- Use specific matchers over generic onesassert-edge-cases- Test edge cases and boundariesassert-one-assertion-concept- Test one concept per testassert-expect-assertions- Use expect.assertions for async testsassert-toequal-vs-tobe- Choose toBe vs toEqual correctly
8. Test Organization (LOW)
org-file-colocation- Colocate test files with source filesorg-describe-nesting- Use describe blocks for logical groupingorg-test-naming- Write descriptive test namesorg-test-skip-only- Use skip and only appropriately
How to Use
Read individual reference files for detailed explanations and code examples:
- Section definitions - Category structure and impact levels
- Rule template - Template for adding new rules
- async-await-assertions - Example rule file
- mock-vi-mock-hoisting - Example rule file
Related Skills
- For TDD methodology, see
test-tddskill - For API mocking with MSW, see
test-mswskill - For TypeScript testing patterns, see
typescriptskill
Full Compiled Document
For the complete guide with all rules expanded: AGENTS.md
Related skills
More from pproenca/dot-skills and the wider catalog.
wxt-browser-extensions
WXT browser extension performance optimization guidelines. This skill should be used when writing, reviewing, or refactoring WXT browser extension code to ensure optimal performance patterns. Triggers on tasks involving WXT, browser extensions, content scripts, service workers, messaging, and extension APIs.
zod
Zod schema validation best practices for type safety, parsing, and error handling.
chrome-extension
Chrome Extensions (Manifest V3) performance and code quality guidelines. Use when writing, reviewing, or refactoring Chrome extension code including service workers, content scripts, message passing, storage APIs, TypeScript patterns, and testing.
clean-architecture
Clean Architecture principles and best practices for designing maintainable, testable software systems.
powerpoint-ppt
Create, format, and manipulate PowerPoint presentations programmatically via MCP or python-pptx.
word-document
Word (.docx) manipulation via MCP server. Use for reading, creating, editing, formatting Word documents including tables, footnotes, comments, images, headers, styles, and PDF conversion.