Vitest Testing Skill - Master Reference

AI-friendly comprehensive testing guidance for Vitest with practical patterns and behavior-driven development.

For humans: Start with README.md for full navigation For AI agents: This file provides quick access to all skill resources

🎯 Quick Access for Agents

Decision Support

• What type of test should I write? → index.md
• How do I structure this test? → principles/aaa-pattern.md
• Is this code testable? → refactoring/testability-patterns.md

Most Referenced Patterns

• F.I.R.S.T Principles - Fast, Isolated, Repeatable, Self-Checking, Timely
• AAA Pattern - Arrange-Act-Assert structure
• Black Box Testing - Test behavior through public APIs
• Test Doubles - Mocks, stubs, spies, fakes

📚 Skill Organization

Core Principles /principles/

Foundation concepts that guide all testing decisions:

Testing Strategies /strategies/

Approaches for different testing scenarios:

Practical Patterns /patterns/

Ready-to-use patterns for common scenarios:

Refactoring for Testability /refactoring/

Transform untestable code into testable code:

Quick Reference /quick-reference/

Fast lookups and decision aids:

🤖 Agent Integration Points

For typescript-coder Agent

When writing tests:

// 1. Check decision tree
const testType = checkDecisionTree(codeType)
// Reference: /skills/vitest-testing/index.md

// 2. Apply F.I.R.S.T principles
ensureTestsAreFast()        // < 100ms
ensureTestsAreIsolated()    // No shared state
// Reference: /skills/vitest-testing/principles/first-principles.md

// 3. Use AAA structure
// Arrange → Act → Assert
// Reference: /skills/vitest-testing/principles/aaa-pattern.md

// 4. Follow black box strategy
testThroughPublicAPI()      // Not private methods
// Reference: /skills/vitest-testing/strategies/black-box-testing.md

When refactoring:

// Check if code is testable
if (isHardToTest(code)) {
  // Apply testability patterns
  applyPattern(testabilityPatterns)
  // Reference: /skills/vitest-testing/refactoring/testability-patterns.md
}

For Code Review Agents

Check these aspects:

• Tests follow F.I.R.S.T principles
• Tests use AAA structure
• Tests use black box approach (public APIs only)
• Proper mocking of external dependencies
• Error scenarios covered
• Async operations handled correctly

🎯 Common Workflows

Workflow 1: Writing Tests for New Feature

1. Consult decision tree → /skills/vitest-testing/index.md
2. Determine test type → Unit/Integration/Component
3. Apply F.I.R.S.T principles → /skills/vitest-testing/principles/first-principles.md
4. Structure with AAA → /skills/vitest-testing/principles/aaa-pattern.md
5. Use relevant pattern → /skills/vitest-testing/patterns/
6. Reference examples → /skills/vitest-testing/examples/ (when created)

Workflow 2: Refactoring for Testability

1. Identify pain points → What makes this hard to test?
2. Select pattern → /skills/vitest-testing/refactoring/testability-patterns.md
3. Apply pattern → Extract pure functions, inject dependencies, etc.
4. Write tests → Black box tests for refactored code
5. Verify → All tests pass, code is easier to test

Workflow 3: Testing Async Code

1. Check async patterns → /skills/vitest-testing/patterns/async-testing.md
2. Mock external APIs → /skills/vitest-testing/patterns/test-doubles.md
3. Control timing → Use vi.useFakeTimers()
4. Test states → Loading, success, error
5. Verify cleanup → Resources released

📖 Philosophy

This skill follows these core beliefs:

1. Behavior over Implementation

Tests should verify WHAT the code does, not HOW it does it. Focus on observable outcomes and public contracts. Implementation details should be testable indirectly through public APIs.

2. Example-Driven Learning

Every principle includes practical examples. Before/after refactoring shows impact. Complete examples provide working templates.

3. Testability by Design

Code that's hard to test is poorly designed. Refactoring patterns transform untestable code. Testability improvements enhance overall code quality.

4. F.I.R.S.T Quality

Fast, Isolated, Repeatable, Self-Checking, Timely tests create a valuable safety net that developers trust and maintain.

🔍 Skill Map

vitest-testing/
├── SKILL.md                    ← You are here (AI agent entry point)
├── README.md                   ← Human navigation hub
├── index.md                    ← Decision tree
├── principles/                 ← Testing fundamentals
│   ├── first-principles.md     ← F.I.R.S.T (most important)
│   ├── aaa-pattern.md          ← Test structure
│   └── bdd-integration.md      ← Given/When/Then
├── strategies/                 ← Testing approaches
│   ├── black-box-testing.md    ← Default strategy
│   └── implementation-details.md ← Rare exceptions
├── patterns/                   ← Practical implementations
│   ├── test-doubles.md         ← Mocking (highly referenced)
│   ├── component-testing.md    ← React/UI testing
│   ├── async-testing.md        ← Promises, async/await
│   ├── error-testing.md        ← Error scenarios
│   ├── api-testing.md          ← HTTP/API testing
│   ├── performance-testing.md  ← Benchmarks, load tests
│   └── test-data.md            ← Factories, builders
├── refactoring/                ← Making code testable
│   └── testability-patterns.md ← Extract, inject, isolate
└── quick-reference/            ← Fast lookups
    ├── cheatsheet.md           ← Syntax reference
    └── jest-to-vitest.md       ← Migration guide

🎓 Learning Paths

For Beginners

1. F.I.R.S.T Principles - Understand quality attributes
2. [AAA Pattern](princip