Testing Strategy Analyst

Overview

Guide the creation of comprehensive tests following project patterns for unit tests, integration tests, and E2E tests using Vitest, MSW, and project-specific test helpers.

When to Use

• Writing new tests for entities or services
• Analyzing test coverage gaps
• Setting up mocks (MSW handlers, vi.fn)
• Organizing test files in the module structure
• Debugging test failures

Testing Stack

Tool	Purpose
Vitest	Test runner and assertion library
MSW	Mock Service Worker for network mocking
vi	Vitest mock utilities
test-helpers/	Project-specific test utilities

Test Organization

src/
├── modules/
│   └── category/
│       ├── category-service.ts
│       ├── category-service.test.ts        # Unit tests
│       ├── repository.ts
│       ├── repository.test.ts              # Repository tests
│       └── category.integration.test.ts    # Integration tests
├── core/
│   └── diff/
│       └── comparators/
│           ├── category-comparator.ts
│           └── category-comparator.test.ts
├── test-helpers/
│   ├── config-file-builder.ts
│   ├── graphql-mocks.ts
│   ├── config-fixtures.ts
│   └── cli-runner.ts
└── lib/
    └── test-setup.ts                       # Global test setup

e2e/
└── ...                                     # End-to-end tests

Quick Pattern Reference

Service Tests

See references/patterns.md for full examples. Key structure:

• Declare dependencies at suite level
• Reset mocks in beforeEach with vi.clearAllMocks()
• Use describe blocks for method grouping
• Follow Arrange-Act-Assert pattern

Repository Tests with MSW

See references/patterns.md for MSW setup. Key steps:

1. Define handlers with graphql.query() / graphql.mutation()
2. Setup server with beforeAll / afterAll
3. Override handlers for specific test cases with server.use()

Test Data Builders

See references/test-builders.md for implementations. Pattern:

• Create builder class with fluent interface
• Validate with Zod schema in build()
• Provide factory functions for convenience

Mock Functions

See references/patterns.md for examples. Common patterns:

• vi.fn() for simple mocks
• vi.mocked() for typed access
• vi.mock() for module mocking

Running Tests

pnpm test                                    # All tests
pnpm test -- --filter=category-service       # Specific file
pnpm test -- --grep="should create category" # Pattern match
pnpm test -- --watch                         # Watch mode
pnpm test -- --coverage                      # With coverage

See references/commands-reference.md for advanced options and coverage configuration.

Test Quality Checklist

For Every Test

• Follows Arrange-Act-Assert pattern
• Has descriptive test name
• Tests one thing per test
• Includes both positive and negative cases
• Uses typed mocks (not any)
• Cleans up after itself (beforeEach/afterEach)

For Test Suites

• Covers all public methods
• Covers error scenarios
• Covers edge cases
• Uses schema-validated test data
• Has integration tests for complex flows

Validation Checkpoints

Phase	Validate	Command
Test written	File exists	Check *.test.ts created
Tests pass	All green	pnpm test <file>
Coverage adequate	Key paths covered	pnpm test --coverage
Mocks typed	No any in mocks	npx tsc --noEmit

Common Mistakes

Mistake	Fix
Not resetting mocks	Add vi.clearAllMocks() in beforeEach
Testing implementation details	Test behavior (public API output), not internal state
Flaky async tests	Always await async operations before asserting
Using any in mocks	Use vi.mocked() for typed mock access
Missing error case tests	Add tests for rejection, validation failure, empty input

References

Skill Reference Files

• references/patterns.md - Detailed test patterns with full code examples
• references/test-builders.md - Builder pattern implementations
• references/commands-reference.md - Complete command reference

Project Resources

• {baseDir}/src/test-helpers/ - Test utilities
• {baseDir}/vitest.config.ts - Test configuration
• {baseDir}/docs/TESTING_PROTOCOLS.md - Testing protocols

External Documentation

• Vitest docs: https://vitest.dev
• MSW docs: https://mswjs.io

Related Skills

• Complete entity workflow: See adding-entity-types for E2E implementation including tests
• Zod test patterns: See designing-zod-schemas for schema validation tests
• GraphQL mocking: See writing-graphql-operations for MSW handlers

Quick Reference Rule

For a condensed quick reference, see .claude/rules/testing-standards.md (automatically loaded when editing *.test.ts files).