analyzing-test-coverage

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.

• Writing new tests
• Analyzing test coverage gaps
• Setting up mocks for testing
• Organizing test files
• Debugging test failures

• [Testing Stack](#testing-stack)
• [Test Organization](#test-organization)
• [Quick Pattern Reference](#quick-pattern-reference)
• [Running Tests](#running-tests)
• [Test Quality Checklist](#test-quality-checklist)
• [Common Pitfalls](#common-pitfalls)
• [References](#references)

| 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 |

```

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

```

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

```bash

# 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 for advanced options and coverage configuration.

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

| Phase | Validate | Command |

|-------|----------|---------|

| Test written | File exists | Check *.test.ts created |

| Tests pass | All green | pnpm test |

| Coverage adequate | Key paths covered | pnpm test --coverage |

| Mocks typed | No any in mocks | npx tsc --noEmit |

Not Resetting Mocks:

```typescript

beforeEach(() => {

vi.clearAllMocks(); // Always reset!

});

```

Testing Implementation Details:

```typescript

// BAD - tests internal structure

expect(service.internalMap.size).toBe(1);

// GOOD - tests behavior

expect(await service.findBySlug('test')).toBeDefined();

```

Flaky Async Tests:

```typescript

// BAD - race condition

const result = service.process();

expect(result).toBe(expected);

// GOOD - await properly

const result = await service.process();

expect(result).toBe(expected);

```

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

• 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

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