playbooks

home / skills / joncrangle / .dotfiles / vitest

vitest skill

/dot_config/opencode/skills/vitest

This skill helps you accelerate test development with Vitest by providing Jest-compatible APIs, in-source testing tips, and fast Vite-backed execution.

npx playbooks add skill joncrangle/.dotfiles --skill vitest

Review the files below or copy the command above to add this skill to your agents.

Files (3)
SKILL.md
1.9 KB
---
name: vitest
description: Specialist in Vitest, a blazing fast unit test framework powered by Vite. Focuses on Jest compatibility, in-source testing, and native ESM support.
---
<skill_doc>
<trigger_keywords>
## Trigger Keywords

Activate this skill when the user mentions any of:

**Core**: Vitest, Vite Test, vi.mock, vi.fn, describe, it, test, expect

**Configuration**: vitest.config.ts, in-source testing, coverage

**Comparison**: Jest replacement, faster than Jest
</trigger_keywords>

## ⛔ Forbidden Patterns

1.  **NO `jest` Global**: Do not use `jest.fn()` or `jest.mock()`. Use `vi.fn()` and `vi.mock()`.
2.  **NO CommonJS require**: Vitest is ESM-first. Use `import` statements.
3.  **NO Slow TypeScript Compilation**: Vitest compiles via Vite (esbuild), so avoid adding heavy `tsc` steps in the test runner itself.
4.  **NO `module.exports`**: Use `export default` or named exports in your test files or mocks.

## 🤖 Agent Tool Strategy

1.  **Config Check**: Look for `vitest.config.ts` or `vite.config.ts` to understand the environment (globals enabled? environment: jsdom?).
2.  **Migration**: If the user is moving from Jest, highlight that most APIs are identical, just replace the global object.
3.  **Mocking**: Use `vi.spyOn` and `vi.mock` for isolating dependencies.
4.  **UI**: Mention `vitest ui` for a visual test runner experience.

## Quick Reference (30 seconds)

Vitest Specialist - "Vite Native Unit Testing".

**Philosophy**:
- **Shared Config**: Uses your existing `vite.config.ts`.
- **Fast**: Powered by esbuild.
- **Compatible**: API is 95% compatible with Jest.

**Workflow**:
1.  Write tests in `*.test.ts`.
2.  Run `vitest` for watch mode.
3.  Run `vitest run` for CI.

---

## Resources

- **Examples**: See `examples/examples.md` for detailed code patterns.
- **References**: See `references/reference.md` for official documentation links.
</skill_doc>

Overview

This skill specializes in Vitest, the fast unit test framework built on Vite, with a focus on TypeScript-friendly, in-source testing and native ESM support. It helps configure, migrate, and optimize tests while preserving Jest-like APIs using vi.* globals. The skill also includes guidance for dotfiles and install scripts to make Vitest part of your developer environment.

How this skill works

It inspects project layout for vitest.config.ts or vite.config.ts to detect global settings, test environment (jsdom/node), and alias resolution. It suggests migration steps from Jest by replacing jest.* usages with vi.* and ensuring ESM imports and proper export styles. It checks for common pitfalls like CommonJS require, module.exports, or unnecessary tsc test steps and suggests fixes and performant configs.

When to use it

  • Setting up fast unit tests for TypeScript projects using Vite
  • Migrating a codebase from Jest to Vitest while keeping similar test APIs
  • Running in-source tests (tests colocated with source files) for rapid feedback
  • Configuring test environment (jsdom vs node) or enabling globals in vitest.config.ts
  • Integrating Vitest into dotfiles or developer install scripts for consistent setups

Best practices

  • Prefer vi.fn, vi.mock, and vi.spyOn instead of any jest.* globals
  • Use import/export and ESM module syntax; avoid require and module.exports
  • Reuse vite.config.ts for shared build/test resolution and aliases
  • Avoid adding tsc compilation to test runner — rely on Vitest's esbuild path for speed
  • Run vitest in watch during dev and vitest run in CI; enable coverage only in CI to save local cycles

Example use cases

  • Add vitest.config.ts to a TypeScript repo and enable globals and jsdom for DOM tests
  • Convert existing Jest tests by replacing jest.mock/jest.fn with vi.mock/vi.fn and switching require to import
  • Bundle Vitest setup into dotfiles and install scripts to provision consistent developer environments
  • Use in-source tests (.test.ts next to implementation) for faster edit-test loops with vitest watch mode
  • Enable vitest ui for a browser-based test runner during manual QA

FAQ

How do I migrate a Jest mock to Vitest?

Replace jest.mock/jest.fn with vi.mock/vi.fn (and use vi.spyOn). Ensure files use import/export and remove module.exports or require calls.

Should I run tsc before running tests?

No. Vitest uses Vite and esbuild for fast TypeScript handling. Avoid adding a full tsc compile step to the test runner for better performance.