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:

| File | Purpose | When to Use | |------|---------|-------------| | first-principles.md | F.I.R.S.T quality attributes | Every test | | aaa-pattern.md | Arrange-Act-Assert structure | Structuring tests | | bdd-integration.md | Given/When/Then with AAA | Business-focused tests |

Testing Strategies /strategies/

Approaches for different testing scenarios:

| File | Purpose | When to Use | |------|---------|-------------| | black-box-testing.md | Testing via public APIs | Default approach (99% of tests) | | implementation-details.md | When to test internals | Rare exceptions only |

Practical Patterns /patterns/

Ready-to-use patterns for common scenarios:

| File | Purpose | When to Use | |------|---------|-------------| | test-doubles.md | Mocks, stubs, spies, fakes | Isolating dependencies | | async-testing.md | Testing promises, async/await | Async operations | | error-testing.md | Testing exceptions, edge cases | Error scenarios | | component-testing.md | React/Vue component patterns | UI components | | api-testing.md | HTTP clients, REST APIs | API integration | | performance-testing.md | Benchmarks, load testing | Performance-critical code | | test-data.md | Factories, builders, fixtures | Test data management |

Refactoring for Testability /refactoring/

Transform untestable code into testable code:

| File | Purpose | When to Use | |------|---------|-------------| | testability-patterns.md | Extract pure functions, DI, etc. | Code hard to test |

Quick Reference /quick-reference/

Fast lookups and decision aids:

| File | Purpose | When to Use | |------|---------|-------------| | cheatsheet.md | Syntax, matchers, mocking | Quick syntax lookup | | jest-to-vitest.md | Migration from Jest | Migrating projects |

🤖 Agent Integration Points

For typescript-coder Agent

When writing tests:

typescript
// 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:

typescript
// 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 - Learn test structure
3. Cheatsheet - Basic syntax
4. Test Doubles - Mocking basics

For Intermediate Developers

1. Black Box Testing - Strategy
2. BDD Integration - Business focus
3. Async Testing - Handle promises
4. Component Testing - UI testing

For Advanced Developers

1. Testability Patterns - Design for testability
2. Implementation Details - Rare exceptions
3. Performance Testing - Benchmarking
4. Architecture Alignment - DDD/Clean Architecture

🚀 Integration with Other Skills

With architecture-patterns Skill

• Domain Models → Test business rules (black box)
• Aggregates → Test invariants
• Use Cases → Test orchestration with mocks
• Repositories → Test with in-memory implementations

With typescript-coder Agent

• Automatically references this skill for test generation
• Applies F.I.R.S.T principles
• Uses AAA structure
• Follows black box strategy

📊 Statistics

Files Created: 20+ Coverage:

• ✅ Core principles (F.I.R.S.T, AAA, BDD)
• ✅ Testing strategies (black box, implementation details)
• ✅ Practical patterns (mocks, async, errors, components, APIs, performance, test data)
• ✅ Refactoring guidance (testability patterns)
• ✅ Quick references (cheatsheet, migration guide)

Integration:

• ✅ typescript-coder agent updated
• ✅ Cross-references to architecture-patterns
• ✅ Decision trees for quick pattern selection

💡 Usage Examples for Agents

Example 1: Agent Writing a Test

typescript
// Agent receives: "Write a test for the UserService.register function"

// Step 1: Check decision tree (index.md)
// → New feature → Unit test (Black Box)

// Step 2: Apply F.I.R.S.T (first-principles.md)
// → Fast: Mock database
// → Isolated: Fresh mocks in beforeEach
// → Repeatable: Control time
// → Self-Checking: Use expect()
// → Timely: Write now

// Step 3: Use AAA pattern (aaa-pattern.md)
describe('UserService.register', () => {
  it('creates user and sends welcome email', async () => {
    // ARRANGE
    const mockDb = { users: { create: vi.fn().mockResolvedValue({...}) } }
    const mockEmailer = { sendWelcome: vi.fn() }
    const service = new UserService(mockDb, mockEmailer)

    // ACT
    const user = await service.register({ email: 'test@example.com' })

    // ASSERT
    expect(mockDb.users.create).toHaveBeenCalled()
    expect(mockEmailer.sendWelcome).toHaveBeenCalledWith('test@example.com')
  })
})

// Step 4: Add error scenarios (error-testing.md)
it('throws ValidationError for invalid email', async () => {
  const service = new UserService(mockDb, mockEmailer)

  await expect(service.register({ email: 'invalid' }))
    .rejects.toThrow(ValidationError)
})

Example 2: Agent Refactoring Code

typescript
// Agent receives: "Make this code testable"

// Step 1: Identify issue (testability-patterns.md)
// → Mixed logic and side effects

// Step 2: Apply Pattern 1: Extract Pure Functions
// Before:
class OrderService {
  async processOrder(order) {
    let total = 0
    for (const item of order.items) {
      total += item.price * item.quantity
    }
    await this.db.save({ ...order, total })
  }
}

// After:
export function calculateOrderTotal(order) {
  return order.items.reduce((sum, item) => sum + item.price * item.quantity, 0)
}

class OrderService {
  async processOrder(order) {
    const total = calculateOrderTotal(order)
    await this.db.save({ ...order, total })
  }
}

// Step 3: Write tests (black-box-testing.md)
describe('calculateOrderTotal', () => {
  it.each([
    [{ items: [{ price: 10, quantity: 2 }] }, 20],
    [{ items: [{ price: 15, quantity: 3 }] }, 45],
  ])('calculates %o as %d', (order, expected) => {
    expect(calculateOrderTotal(order)).toBe(expected)
  })
})

🔗 External Resources

• Vitest Documentation - Official docs
• Testing Library - React/DOM testing
• MSW - API mocking
• @faker-js/faker - Test data generation

📋 Agent Checklist

When generating tests, ensure:

• ] Test follows F.I.R.S.T principles
• ] Test uses AAA structure
• ] Test uses black box approach
• ] External dependencies are mocked
• ] Error scenarios are covered
• ] Async operations handled correctly
• ] Test is fast (< 100ms), isolated, and repeatable

🎯 Common Agent Tasks

Task: Generate Unit Test

1. Read index.md → Identify test type
2. Apply first-principles.md → F.I.R.S.T
3. Structure with aaa-pattern.md
4. Mock using test-doubles.md
5. Reference cheatsheet.md for syntax

Task: Generate Component Test

1. Read component-testing.md
2. Use Testing Library queries
3. Test user interactions
4. Handle async operations
5. Cover error states

Task: Refactor for Testability

1. Read testability-patterns.md
2. Identify pattern (extract, inject, wrap)
3. Apply refactoring
4. Generate tests for refactored code

Task: Review Test Quality

1. Check F.I.R.S.T compliance
2. Verify AAA structure
3. Ensure black box approach
4. Validate mock usage
5. Check error coverage

📖 Skill Metadata

Version: 1.0.0 Type: Testing guidance Framework: Vitest Language: TypeScript/JavaScript Integration: typescript-coder agent, architecture-patterns skill Status: Production ready (core files complete)

Files: 20+ markdown documents Categories: Principles (3), Strategies (2), Patterns (7), Refactoring (1), Quick Reference (2)

💡 Quick Decision Trees

"What test should I write?"

Is it a new feature?
└─ YES → Unit test (black box) + [index.md](index.md#new-feature)

Is it a bug fix?
└─ YES → Regression test + [index.md](index.md#bug-fix)

Is it async code?
└─ YES → [async-testing.md](patterns/async-testing.md)

Is it a React component?
└─ YES → [component-testing.md](patterns/component-testing.md)

Is it an API client?
└─ YES → [api-testing.md](patterns/api-testing.md)

Is it complex logic?
└─ YES → Extract pure function + black box test

"How do I make this testable?"

Mixed logic and side effects?
└─ [testability-patterns.md](refactoring/testability-patterns.md#pattern-1)

Hard-coded dependencies?
└─ [testability-patterns.md](refactoring/testability-patterns.md#pattern-2)

Complex private method?
└─ [testability-patterns.md](refactoring/testability-patterns.md#pattern-3)

Time-dependent code?
└─ [testability-patterns.md](refactoring/testability-patterns.md#pattern-5)

This is the master reference for AI agents. For human-friendly navigation, see README.md.