Testing Strategy Analyst

Purpose

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
• Analyzing test coverage gaps
• Setting up mocks for testing
• Organizing test files
• Debugging test failures

Table of Contents

• Testing Stack
• Test Organization
• Quick Pattern Reference
• Running Tests
• Test Quality Checklist
• Common Pitfalls
• References

Testing Stack

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

• 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

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

• Create builder class with fluent interface
• Validate with Zod schema in

  build()

• Provide factory functions for convenience

Mock Functions

See

references/patterns.md

• vi.fn()

  for simple mocks

• vi.mocked()

  for typed access

• vi.mock()

  for module mocking

Running Tests

# Run all tests
pnpm test

# Run specific test file
pnpm test -- --filter=category-service

# Run tests matching pattern
pnpm test -- --grep="should create category"

# Watch mode
pnpm test -- --watch

# With coverage
pnpm test -- --coverage

See

references/commands-reference.md

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

*.test.ts

pnpm test <file>

pnpm test --coverage

any

npx tsc --noEmit

Common Pitfalls

Not Resetting Mocks:

beforeEach(() => {
  vi.clearAllMocks(); // Always reset!
});

Testing Implementation Details:

// BAD - tests internal structure
expect(service.internalMap.size).toBe(1);

// GOOD - tests behavior
expect(await service.findBySlug('test')).toBeDefined();

Flaky Async Tests:

// BAD - race condition
const result = service.process();
expect(result).toBe(expected);

// GOOD - await properly
const result = await service.process();
expect(result).toBe(expected);

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

*.test.ts