Skip to main content
skill CX Codex

testing-unit — Claude Code skill: tests and installation

The testing-unit skill provides patterns for unit tests, HTTP mocks, fixtures, and test data in Vitest, Jest, and pytest. It applies while writing tests or setting up test doubles.

MIT 116 installs ★ 305 updated 2026-11-07

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓
npx skills add yonatangross/orchestkit --skill testing-unit -a claude-code
Open on GitHub

What testing-unit does

testing-unit organizes unit tests around Arrange-Act-Assert, replaces repeated cases with parametrized runs, and guides fixture scope choices. Its material covers Vitest, Jest, and pytest, with patterns for data factories and composed JSON fixtures.

HTTP tests use network interception rather than direct mocks of fetch, axios, or requests: MSW is covered for TypeScript and VCR.py for Python. The skill also includes rule files, references, checklists, scaffolding scripts, and examples for CRUD handlers, failures, authentication, and uploads. Its Vitest target is >=5.0.3.

Shared mutable fixtures can make tests flaky, so function scope is the stated choice for that data; module and session are reserved for expensive read-only resources. Claude Code requires version 2.1.277 or newer.

What it helps with

  • structure a unit test with Arrange-Act-Assert phases
  • replace copied cases with parametrized tests
  • intercept API traffic through MSW or VCR.py
  • choose fixture scope for mutable and read-only data
  • generate isolated test records with factories

Example prompts for the agent

  • Write unit tests for this service using the Arrange-Act-Assert pattern.
  • Turn these repeated Vitest or pytest cases into one parametrized test.
  • Set up MSW network handlers for the API tests and reset them between tests.

How to install testing-unit

1Skills CLI (Vercel)

npx skills add yonatangross/orchestkit --skill testing-unit -a claude-code

2Manually: put the files in place

~/.claude/skills/testing-unit/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/testing-unit/

Step by step, with commands for each platform: How to install skills in Claude Code: five ways

Questions about testing-unit

How do I install testing-unit in Claude Code?

Run npx skills add yonatangross/orchestkit --skill testing-unit -a claude-code, then check ~/.claude/skills/testing-unit/SKILL.md.

What does the testing-unit skill do?

It guides isolated unit tests, parametrized cases, fixture scope, and network-level HTTP mocks with MSW or VCR.py. It also covers factories and fixture data.

Which versions and test tools does testing-unit cover?

The patterns cover Vitest, Jest, and pytest. Claude Code requires version 2.1.277 or newer, while the Vitest target is >=5.0.3.

Source text

SKILL.md · MIT
---
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)

```typescript
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)

```python
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", False),
    ])
    def test_edit_permission(self, role, can_edit):
        # Arrange
        user = UserFactory(role=role)

        # Act
        result = user_can_edit(user)

        # Assert
        assert result == can_edit
```

## Vitest 4.1 Features

### aroundEach / aroundAll (preferred for DB transactions)

Wraps each test in setup/teardown — cleaner than separate `beforeEach`/`afterEach` for transactions:

```typescript
test.aroundEach(async (runTest, { db }) => {
  await db.transaction(runTest)  // auto-rollback on test end
})

test('insert user', async ({ db }) => {
  await db.insert({ name: 'Alice' })
  // transaction auto-rolls back — no cleanup needed
})
```

`aroundAll` wraps entire suites the same way.

### mockThrow / mockThrowOnce

Replaces the verbose `mockImplementation(() => { throw err })` pattern:

```typescript
const fn = vi.fn()
fn.mockThrow(new Error('connection lost'))  // always throws
fn.mockThrowOnce(new Error('timeout'))      // throws once, then normal
```

### vi.defineHelper (clean stack traces)

Custom assertion helpers that point errors to the call site, not the helper internals:

```typescript
const assertPair = vi.defineHelper((a, b) => {
  expect(a).toEqual(b)  // error points to where assertPair() was CALLED
})
```

### Test Tags

Filter tests by tags in CLI — useful for CI fast paths:

```typescript
// vitest.config.ts
test: {
  tags: {
    unit: { timeout: 5000 },
    flaky: { retry: 3 },
  }
}
```

```bash
vitest --tags-filter="unit and !flaky"
vitest --tags-filter="(unit or integration) and !slow"
```

### Agent Reporter

Minimal output (failures only) — use in AI agent / CI contexts:

```bash
AI_AGENT=copilot vitest    # auto-detect agent mode
```

## Key Decisions

| Decision | Recommendation |
|----------|----------------|
| Test framework (TS) | Vitest 4.1+ (modern, fast, aroundEach, test tags) or Jest (mature ecosystem) |
| Test framework (Python) | pytest with plugins (parametrize, asyncio, cov) |
| HTTP mocking (TS) | MSW 2.x at network level, never mock fetch/axios directly |
| HTTP mocking (Python) | VCR.py with cassettes, filter sensitive data |
| Test data | Factories (FactoryBoy/faker-js) over hardcoded fixtures |
| Fixture scope | `scope="function"` for mutable (default). `module`/`session` ONLY for expensive immutable resources |
| Execution time | Under **100ms** per unit test — if slower, mock external calls |
| Coverage target | 90%+ business logic, 100% critical paths |

## Common Mistakes

1. **Testing implementation details** instead of public behavior (brittle tests)
2. **Mocking fetch/axios directly** instead of using MSW at network level (incomplete coverage)
3. **Shared mutable state** between tests via module-scoped fixtures (flaky tests)
4. **Hard-coded test data** with duplicate IDs (test conflicts in parallel runs)
5. **No cleanup** after database seeding (state leaks between tests)
6. **Over-mocking** — testing your mocks instead of your code (false confidence)
7. **Verbose throw mocking** — `mockImplementation(() => { throw err })` instead of `mockThrow(err)` (Vitest 4.1+)

## Scripts

| Script | File | Purpose |
|--------|------|---------|
| Create Test Case | `scripts/create-test-case.md` | Scaffold test file with auto-detected framework |
| Create Test Fixture | `scripts/create-test-fixture.md` | Scaffold pytest fixture with context detection |
| Create MSW Handler | `scripts/create-msw-handler.md` | Scaffold MSW handler for an API endpoint |

© OrchestKit · MIT · yonatangross/orchestkit

Similar skills

All skills for Testing and QA →

From the same set86

The whole set →
product-analytics The product-analytics skill evaluates A/B tests, cohort retention, and funnels. It helps explain adoption changes, conversion losses, and experiment outcomes. CX Codex +1 120installs testing-perf The testing-perf skill for Claude Code runs load and performance tests with k6 and Locust and parallelizes pytest with xdist. It activates when writing load tests or speeding up test suite runs. CX Codex +1 120installs chain-patterns chain-patterns — a set of patterns for multi-stage pipelines: MCP checks, handoff files, checkpoint recovery, isolated worktree agents, and cron monitoring. CX Codex +1 118installs design-to-code design-to-code — a skill for Claude Code that turns screenshots, descriptions, and URLs into React components. Assembles UI elements while reusing existing Storybook pieces and design tokens. CX Codex +1 116installs design-context-extract design-context-extract extracts colors, typography, spacing, components, and motion from screenshots, URLs, or recordings. It returns tokens or Tailwind-ready output. CX Codex +1 112installs component-search The component-search Claude Code skill searches 21st.dev for React components and ranks the matches. It runs when a request asks for a UI component or a replacement. CX Codex +1 106installs mcp-visual-output The mcp-visual-output skill for Claude Code transforms MCP tool JSON results into interactive dashboards. It activates when visual data presentation is more effective than plain text output. CX Codex +1 105installs cover Generates missing tests. Runs when new features lack test coverage across unit, integration, or e2e tiers. CX Codex +1 100installs

Project sponsors

Companies that keep this analytics open