# Vitest Testing Guidelines

> Comprehensive testing guidelines for Vitest with React Testing Library Use when this capability is needed.

- Skill: `tomevault-io/vitest-testing-guidelines` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add tomevault-io/vitest-testing-guidelines`
- Raw SKILL.md: https://api.skillmd.com/api/skills/tomevault-io/vitest-testing-guidelines/raw
- Safety review: pending (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Web & Frontend
- Author: tomevault-io (https://skillmd.com/u/tomevault-io)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/tomevault-io/vitest-testing-guidelines

---


# Vitest Testing Guidelines

**Choose the right guide for your task:**

## 📝 Creating New Tests

→ See [rules/new-tests.md](rules/new-tests.md)

Use when:

- Writing tests for new components or utilities
- Need modern testing patterns and examples
- Starting from scratch

## 🔄 Refactoring Legacy Tests

→ See [rules/legacy-refactoring.md](rules/legacy-refactoring.md)

Use when:

- Converting old tests to modern patterns
- Replacing Sinon with Vitest
- Migrating from old Testing Library patterns
- Need step-by-step refactoring checklist

## 📘 TypeScript Guidelines

→ See [rules/typescript.md](rules/typescript.md)

Use when:

- Converting tests to TypeScript
- Need TypeScript-specific patterns
- Writing type-safe test utilities

## 🎯 Common Patterns & Reference

→ See [rules/common-patterns.md](rules/common-patterns.md)

Use anytime for:

- Quick reference of common mistakes
- Testing best practices
- Mocking patterns
- User interaction examples
- Global setup information

---

## 🎯 Token Budget Guide

**Quick tasks** (50-150 tokens):

- Simple lookup → [quick-ref/testing-cheatsheet.md](quick-ref/testing-cheatsheet.md)
- Common patterns → [quick-ref/testing-cheatsheet.md](quick-ref/testing-cheatsheet.md)

**Medium tasks** (200-400 tokens):

- New test file → [rules/new-tests.md](rules/new-tests.md)
- TypeScript conversion → [rules/typescript.md](rules/typescript.md)

**Complex tasks** (400-800 tokens):

- Legacy refactoring → [rules/legacy-refactoring.md](rules/legacy-refactoring.md) + [rules/typescript.md](rules/typescript.md)
- Complete test suite → [rules/new-tests.md](rules/new-tests.md) + [rules/common-patterns.md](rules/common-patterns.md)

---

## 🚀 Auto-Trigger Patterns

**This skill should be loaded when:**

- Creating `.test.ts` or `.test.tsx` files
- User mentions: "test", "write tests", "add tests", "test coverage"
- Modifying existing test files
- User mentions: "vitest", "react testing library", "RTL"
- Converting/refactoring: "migrate tests", "update tests", "refactor tests"

**File patterns that trigger this skill:**

- `*.test.ts`, `*.test.tsx`, `*.test.js`, `*.test.jsx`
- `*.spec.ts`, `*.spec.tsx`
- Files in `__tests__/` directory

**Keywords:**
`test`, `vitest`, `expect`, `describe`, `it`, `mock`, `spy`, `render`, `screen`, `userEvent`, `waitFor`, `assertion`

---

## Test File Strategy: When to Use TypeScript vs JavaScript

### Creating New Test Files

✅ **Always use TypeScript** (`.test.ts` or `.test.tsx`)

- Follow modern patterns from [rules/new-tests.md](rules/new-tests.md)
- Use `testRender`, `testRenderAdmin` helpers
- No need to import `describe`, `expect`, `it`, `vi` (they're global)

### Refactoring/Converting Existing Test Files

✅ **Use TypeScript** and apply modern patterns

- Convert `.test.js`/`.test.jsx` → `.test.ts`/`.test.tsx`
- Follow [rules/legacy-refactoring.md](rules/legacy-refactoring.md)
- Apply all modern best practices

### Extending Existing Test Files (Adding Tests/Assertions)

⚠️ **PROMPT THE USER FIRST:**

When asked to add tests to an existing file, ask:

```
I see this test file uses [JavaScript/TypeScript] with [legacy/modern] patterns.
Would you like me to:
1. Add new tests only:
   a) Following the modern approach (less tech debt, recommended)
   b) Following the current file's approach (faster, maintains consistency)
2. Refactor the entire file to modern TypeScript patterns (comprehensive, but takes longer)

Which approach would you prefer?
```

**If user chooses option 1a (modern approach):**

- Add new tests using patterns from [rules/new-tests.md](rules/new-tests.md)
- Use TypeScript syntax for new tests
- Import from `@/test`
- Existing tests remain unchanged

**If user chooses option 1b (match current approach):**

- Follow the file's existing patterns (imports, style, syntax)
- Keep the same language (JS or TS)
- Maintain consistency with existing tests in the file

**If user chooses option 2 (modern refactor):**

- Convert to TypeScript using [rules/typescript.md](rules/typescript.md)
- Apply all modern patterns from [rules/legacy-refactoring.md](rules/legacy-refactoring.md)
- Refactor all tests in the file

## Quick Reference

### Running Tests

- **Run all tests**: `npm run test --run`
- **Run specific test file**: `npm run test -- current/src/.../about.test.jsx --run`
- **Run by filename shorthand**: `npm run test -- about.test.jsx --run`

### File Naming

- **Use `.test.jsx` extension** for new Vitest tests (not `.vitest.jsx`)
- **Future migration**: All existing `.vitest.jsx` files will be renamed to `.test.jsx`

---
> Converted and distributed by [TomeVault](https://tomevault.io/claim/alexandrebenkendorf) — claim your Tome and manage your conversions.
<!-- tomevault:4.0:skill_md:2026-04-13 -->