/testing-unit

name: testing-unit
license: MIT
compatibility: "Claude Code 2.1.277+."
description: "Unit test patterns: AAA, parametrized tests, fixture scope, MSW or VCR network mocks, data factories, for Vitest, Jest and pytest. Use when writing unit tests or setting up mocks and fixtures."
user-invocable: false
disable-model-invocation: false
targets:
  - library: vitest
    version: ">=5.0.3"
metadata:
  owner-agent: "test-generator"
  category: document-asset-creation
  version: "2.1.0"
  author: "OrchestKit"
  complexity: "medium"
  tags: "testing, unit, mocking, msw, vcr, fixtures, factories, vitest-4, aroundEach"
allowed-tools: "Read Glob Grep WebFetch WebSearch"
path_patterns: ["*.test.*", "*.spec.*", "**/vitest.config.*", "**/jest.config.*"]

Unit Testing Patterns

Focused patterns for writing isolated, fast, maintainable unit tests. Covers test structure (AAA), parametrization, fixture management, HTTP mocking (MSW/VCR), and test data generation with factories.

Each category has individual rule files in `rules/` loaded on-demand, plus reference material, checklists, and scaffolding scripts.

Core Principles (ALWAYS apply)

1. **AAA structure**: Every test MUST follow Arrange-Act-Assert. Use `// Arrange`, `// Act`, `// Assert` comments for clarity. 2. **Parametrize, don't duplicate**: Use `test.each` (TypeScript) or `@pytest.mark.parametrize` (Python) when testing multiple inputs. Never copy-paste the same test body with different values. 3. **Fixture scoping matters**: Use `scope="function"` (default) for mutable data. Use `scope="module"` or `scope="session"` ONLY for expensive read-only resources (DB engines, ML models). Mutable data with shared scope causes flaky tests. 4. **Speed target**: Each unit test should run under **100ms**. If it's slower, you're likely hitting I/O — mock it. 5. **Mock at the network level**: Use MSW (TypeScript) or VCR.py (Python) to intercept HTTP at the network layer. Never mock `fetch`/`axios`/`requests` directly.

Quick Reference

| Category | Rules | Impact | When to Use | |----------|-------|--------|-------------| | [Unit Test Structure](#unit-test-structure) | 3 | CRITICAL | Writing any unit test | | [HTTP Mocking](#http-mocking) | 2 | HIGH | Mocking API calls in frontend/backend tests | | [Test Data Management](#test-data-management) | 3 | MEDIUM | Setting up test data, factories, fixtures |

**Total: 8 rules across 3 categories, 4 references, 3 checklists, 1 example set, 3 scripts**

Unit Test Structure

Core patterns for structuring isolated unit tests with clear phases and efficient execution.

| Rule | File | Key Pattern | |------|------|-------------| | AAA Pattern | `rules/unit-aaa-pattern.md` | Arrange-Act-Assert with isolation | | Fixture Scoping | `rules/unit-fixture-scoping.md` | function/module/session scope selection | | Parametrized Tests | `rules/unit-parametrized.md` | test.each / @pytest.mark.parametrize |

**Reference:** `references/aaa-pattern.md` — detailed AAA implementation with checklist

HTTP Mocking

Network-level request interception for deterministic tests without hitting real APIs.

| Rule | File | Key Pattern | |------|------|-------------| | MSW 2.x | `rules/mocking-msw.md` | Network-level mocking for frontend (TypeScript) | | VCR.py | `rules/mocking-vcr.md` | Record/replay HTTP cassettes (Python) |

**References:**

• `references/msw-2x-api.md` — full MSW 2.x API (handlers, GraphQL, WebSocket, passthrough)
• `references/stateful-testing.md` — Hypothesis RuleBasedStateMachine for stateful tests

**Checklists:**

• `checklists/msw-setup-checklist.md` — MSW installation, handler setup, test writing
• `checklists/vcr-checklist.md` — VCR configuration, sensitive data filtering, CI setup

**Examples:** `examples/handler-patterns.md` — CRUD, error simulation, auth flow, file upload handlers

Test Data Management

Factories, fixtures, and seeding patterns for isolated, realistic test data.

| Rule | File | Key Pattern | |------|------|-------------| | Data Factories | `rules/data-factories.md` | FactoryBoy / @faker-js builders | | Data Fixtures | `rules/data-fixtures.md` | JSON fixtures with composition | | Seeding & Cleanup | `rules/data-seeding-cleanup.md` | Automated DB seeding and teardown |

**Reference:** `references/factory-patterns.md` — advanced factory patterns (Sequence, SubFactory, Traits)

**Checklist:** `checklists/test-data-checklist.md` — data generation, cleanup, isolation verification

Quick Start

TypeScript (Vitest + MSW)

import { describe, test, expect, beforeAll, afterEach, afterAll } from 'vitest';
import { http, HttpResponse } from 'msw';
import { setupServer } from 'msw/node';
import { calculateDiscount } from './pricing';

// 1. Pure unit test with AAA pattern
describe('calculateDiscount', () => {
  test.each([
    [100, 0],
    [150, 15],
    [200, 20],
  ])('for order $%i returns $%i discount', (total, expected) => {
    // Arrange
    const order = { total };

    // Act
    const discount = calculateDiscount(order);

    // Assert
    expect(discount).toBe(expected);
  });
});

// 2. MSW mocked API test
const server = setupServer(
  http.get('/api/users/:id', ({ params }) => {
    return HttpResponse.json({ id: params.id, name: 'Test User' });
  })
);

beforeAll(() => server.listen({ onUnhandledRequest: 'error' }));
afterEach(() => server.resetHandlers());
afterAll(() => server.close());

test('fetches user from API', async () => {
  // Arrange — MSW handler set up above

  // Act
  const response = await fetch('/api/users/123');
  const data = await response.json();

  // Assert
  expect(data.name).toBe('Test User');
});

Python (pytest + FactoryBoy)

import pytest
from factory import Factory, Faker, SubFactory

class UserFactory(Factory):
    class Meta:
        model = dict
    email = Faker('email')
    name = Faker('name')

class TestUserService:
    @pytest.mark.parametrize("role,can_edit", [
        ("admin", True),
        ("viewer