vitest

Correct async assertions, mocking, snapshots, and CI configuration in Vitest test suites.

Updated Mar 11, 2026
One-click install
npx skills add https://github.com/selfagency/agentsy --skill vitest-selfagency
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: vitest
Source: https://github.com/selfagency/agentsy/tree/main/.agents/skills/vitest
Command: npx skills add https://github.com/selfagency/agentsy --skill vitest-selfagency

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill includes references (resource) and assets (resource) components.

What problem does it solve?

It eliminates flaky or misleading Vitest results caused by incorrect async handling, leaking mocks/state across tests, unstable snapshots, and slow CI performance patterns.

Core Features & Use Cases

  • Async correctness: Use proper async assertion patterns, return promises correctly, wait on conditions with vi.waitFor, and use fake timers to make time-dependent logic deterministic.
  • Test isolation & mocking hygiene: Avoid shared mutable state, clean up in afterEach hooks, restore mocks after each test, reset module cache when needed, and choose vi.spyOn vs vi.mock appropriately to avoid over-mocking.
  • Performance & snapshot discipline: Configure pools and environments for speed, optimize CI execution (run mode, bail, sharding), and keep snapshots stable and reviewable to prevent silent regressions.

Quick Start

Use the vitest skill to rewrite your failing or flaky test by applying the relevant rule from the async patterns or test setup categories, then re-run the test suite to confirm it becomes deterministic.

Frequently Asked Questions about vitest

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
Why are my Vitest tests flaky when using async assertions?

Flaky Vitest tests often stem from incorrect async handling, such as not returning promises or missing vi.waitFor conditions. Applying proper async assertion patterns and fake timers makes time-dependent logic deterministic and test results reliable.

How do I stop mock state from leaking across Vitest test suites?

To stop mock state leaking across Vitest tests, clean up shared mutable state in afterEach hooks and restore mocks after each test. Resetting module cache when needed and choosing vi.spyOn versus vi.mock appropriately ensures strict test isolation.

What is the best way to migrate from Jest to Vitest without breaking snapshots?

Migrating from Jest to Vitest requires updating vi.* helpers and ensuring stable snapshot serialization. Keeping snapshots reviewable and correctly configuring execution environments prevents silent regressions and maintains consistent test behavior.

Can I configure Vitest pools and environments to improve CI performance?

Configuring Vitest pools and environments directly improves CI performance. Optimizing execution through run mode, bail, and sharding configurations significantly reduces overall test runtime while maintaining reliable test outcomes.

When should I use fake timers in Vitest for time-dependent logic?

Use fake timers in Vitest when testing time-dependent logic to make assertions deterministic. vi.useFakeTimers controls time progression, preventing race conditions and ensuring async operations settle predictably without arbitrary delays.