vitest

Name: vitest
Author: pproenca

44 Vitest best practices rules organized by priority, covering async patterns, test setup, mocking, performance, snapshots, and assertions. Async patterns and test isolation are marked CRITICAL; covers awaiting assertions, returning promises, fake timers, and proper cleanup between tests Mocking rules address vi.mock hoisting, spyOn vs mock selection, implementation patterns, and type safety Performance optimization includes pool selection, test isolation toggling, happy-dom preference, sharding for CI, and bail-fast strategies Snapshot testing guidance covers inline vs file snapshots, avoiding large snapshots, stable serialization, and intentional naming Rules organized by impact level with prefixed categories (async-, setup-, mock-, perf-, snap-, env-, assert-, org-) and detailed reference files for each pattern

INSTALLATION

npx skills add https://github.com/pproenca/dot-skills --skill vitest

Run in your project or agent environment. Adjust flags if your CLI version differs.

SKILL.md

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

Quick Reference

1. Async Patterns (CRITICAL)

async-await-assertions - Await async assertions to prevent false positives

async-return-promises - Return promises from test functions

async-fake-timers - Use fake timers for time-dependent code

async-waitfor-polling - Use vi.waitFor for async conditions

async-concurrent-expect - Use test context expect in concurrent tests

async-act-wrapper - Await user events to avoid act warnings

async-error-handling - Test async error handling properly

2. Test Setup & Isolation (CRITICAL)

setup-beforeeach-cleanup - Clean up state in afterEach hooks

setup-restore-mocks - Restore mocks after each test

setup-avoid-shared-state - Avoid shared mutable state between tests

setup-beforeall-expensive - Use beforeAll for expensive one-time setup

setup-reset-modules - Reset modules when testing module state

setup-test-factories - Use test factories for complex test data

3. Mocking Patterns (HIGH)

mock-vi-mock-hoisting - Understand vi.mock hoisting behavior

mock-spyon-vs-mock - Choose vi.spyOn vs vi.mock appropriately

mock-implementation-not-value - Use mockImplementation for dynamic mocks

mock-msw-network - Use MSW for network request mocking

mock-avoid-overmocking - Avoid over-mocking

mock-type-safety - Maintain type safety in mocks

mock-clear-between-tests - Clear mock state between tests

4. Performance (HIGH)

perf-pool-selection - Choose the right pool for performance

perf-disable-isolation - Disable test isolation when safe

perf-happy-dom - Use happy-dom over jsdom when possible

perf-sharding - Use sharding for CI parallelization

perf-run-mode-ci - Use run mode in CI environments

perf-bail-fast-fail - Use bail for fast failure in CI

5. Snapshot Testing (MEDIUM)

snap-inline-over-file - Prefer inline snapshots for small values

snap-avoid-large - Avoid large snapshots

snap-stable-serialization - Ensure stable snapshot serialization

snap-review-updates - Review snapshot updates before committing

snap-describe-intent - Name snapshot tests descriptively

6. Environment (MEDIUM)

env-per-file-override - Override environment per file when needed

env-setup-files - Use setup files for global configuration

env-globals-config - Configure globals consistently

env-browser-api-mocking - Mock browser APIs not available in test environment

7. Assertions (LOW-MEDIUM)

assert-specific-matchers - Use specific matchers over generic ones

assert-edge-cases - Test edge cases and boundaries

assert-one-assertion-concept - Test one concept per test

assert-expect-assertions - Use expect.assertions for async tests

assert-toequal-vs-tobe - Choose toBe vs toEqual correctly

8. Test Organization (LOW)

org-file-colocation - Colocate test files with source files

org-describe-nesting - Use describe blocks for logical grouping

org-test-naming - Write descriptive test names

org-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-tdd skill

For API mocking with MSW, see test-msw skill

For TypeScript testing patterns, see typescript skill

Full Compiled Document

For the complete guide with all rules expanded: AGENTS.md