unit-testing（单元测试）

Discovery Questions

1. Framework: Jest, Vitest, or pytest? Check package.json or pyproject.toml.
2. Coverage tooling: Already configured? Look for jest.config.*, vitest.config.*, .nycrc, [tool.coverage].
3. Mocking strategy: Manual mocks, auto-mocking, or dependency injection? Check for __mocks__/ dirs or DI containers.
4. Existing conventions: Check .agents/qa-project-context.md first for project-specific guidelines.

Core Principles

1. Test behavior, not implementation. Verify *what* code does, not *how*. Refactoring internals should not break tests.

// Bad — implementation detail        // Good — observable behavior
expect(svc._cache.size).toBe(3);      expect(svc.getUser("abc")).toEqual({ id: "abc", name: "Alice" });

2. Fast, isolated, deterministic. No network/disk/DB. No shared mutable state. No uncontrolled Date.now() or Math.random().

3. Arrange-Act-Assert.

it("should apply discount for orders over $100", () => {
  // Arrange
  const order = createOrder({ subtotal: 150 });
  const svc = new DiscountService(0.1);
  // Act
  const result = svc.apply(order);
  // Assert
  expect(result.total).toBe(135);
});

4. One assertion concept per test (multiple expect calls are fine if they verify the same concept).

5. Descriptive test names: "should [behavior] when [condition]", not "test calculateTotal".

Framework-Specific Patterns

Jest

describe/it structure with setup/teardown:

describe("UserService", () => {
  let service: UserService;
  let mockRepo: jest.Mocked<UserRepository>;

  beforeEach(() => {
    mockRepo = { findById: jest.fn(), save: jest.fn() } as jest.Mocked<UserRepository>;
    service = new UserService(mockRepo);
  });
  afterEach(() => jest.restoreAllMocks());

  it("should return user when found", async () => {
    mockRepo.findById.mockResolvedValue({ id: "1", name: "Alice" });
    const result = await service.getUser("1");
    expect(result).toEqual({ id: "1", name: "Alice" });
  });

  it("should throw when user not found", async () => {
    mockRepo.findById.mockResolvedValue(null);
    await expect(service.getUser("999")).rejects.toThrow(NotFoundError);
  });
});

Module mocking (jest.mock):

jest.mock("./email-client", () => ({
  sendEmail: jest.fn().mockResolvedValue({ sent: true }),
}));
// Partial mock — keep original, override one export
jest.mock("./utils", () => ({ ...jest.requireActual("./utils"), generateId: jest.fn(() => "fixed") }));

Spying (jest.spyOn): wraps real method, records calls.

const spy = jest.spyOn(console, "warn").mockImplementation();
service.deprecatedMethod();
expect(spy).toHaveBeenCalledWith(expect.stringContaining("deprecated"));

Timer mocking:

beforeEach(() => jest.useFakeTimers());
afterEach(() => jest.useRealTimers());

it("should debounce", () => {
  const fn = jest.fn();
  const debounced = debounce(fn, 300);
  debounced();
  expect(fn).not.toHaveBeenCalled();
  jest.advanceTimersByTime(300);
  expect(fn).toHaveBeenCalledTimes(1);
});

Async: await expect(fn()).resolves.toEqual(...) / await expect(fn()).rejects.toThrow(...).

Vitest

Same API as Jest but Vite-native. Key differences:

// vitest.config.ts
import { defineConfig } from "vitest/config";
export default defineConfig({
  test: {
    globals: true,
    environment: "node",
    coverage: { provider: "v8", reporter: ["text", "html", "lcov"] },
  },
});

Mocking with vi:

vi.mock("./email-client", () => ({ sendConfirmation: vi.fn().mockResolvedValue(true) }));
const spy = vi.spyOn(repository, "save");

In-source testing (useful for utilities):

export function clamp(val: number, min: number, max: number) {
  return Math.min(Math.max(val, min), max);
}
if (import.meta.vitest) {
  const { it, expect } = import.meta.vitest;
  it("clamps below", () => expect(clamp(-5, 0, 10)).toBe(0));
  it("clamps above", () => expect(clamp(15, 0, 10)).toBe(10));
}

Enable: test: {includeSource: ["src/**/*.ts"]} and define: {"import.meta.vitest": "undefined"}.

Monorepo workspaces:

// vitest.workspace.ts
export default ["packages/*/vitest.config.ts"];

pytest

Fixtures and conftest.py:

# conftest.py
@pytest.fixture
def db():
    database = Database(":memory:")
    database.migrate()
    yield database
    database.close()

@pytest.fixture
def user_service(db):
    return UserService(db)

class TestUserService:
    def test_create_returns_id(self, user_service):
        uid = user_service.create({"name": "Alice"})
        assert uid is not None

    def test_get_nonexistent_raises(self, user_service):
        with pytest.raises(UserNotFoundError):
            user_service.get("nonexistent")

Parametrize for data-driven tests:

@pytest.mark.parametrize("input_val,expected", [
    ("hello world", "Hello World"), ("", ""), ("CAPS", "Caps"),
])
def test_title_case(input_val, expected):
    assert title_case(input_val) == expected

Monkeypatch for mocking:

def test_uses_env(monkeypatch):
    monkeypatch.setenv("APP_URL", "https://test.local")
    assert fetch_config()["source"] == "https://test.local"

def test_retry(monkeypatch):
    calls = {"n": 0}
    def fake(url):
        calls["n"] += 1
        if calls["n"] < 3: raise ConnectionError
        return {"ok": True}
    monkeypatch.setattr("app.client.http_request", fake)
    assert fetch_with_retry("https://api.test") == {"ok": True}

Markers: @pytest.mark.slow, then run pytest -m "not slow". Use -k "test_create" for name matching.

Mocking Taxonomy

// Stub — just a return value
const pricing = { getPrice: () => 9.99 };

// Spy — real behavior, tracked
const spy = vi.spyOn(logger, "info");

// Mock — replaced + verified
const notifier = { send: vi.fn().mockResolvedValue(true) };
expect(notifier.send).toHaveBeenCalledWith(expect.objectContaining({ type: "done" }));

// Fake — working substitute
class FakeRepo implements UserRepository {
  private data = new Map<string, User>();
  async findById(id: string) { return this.data.get(id) ?? null; }
  async save(u: User) { this.data.set(u.id, { ...u }); }
}

Rule of thumb: Use the simplest double. Prefer stubs over mocks. Reserve fakes for stateful dependencies. Never call real external APIs in unit tests.

Coverage

Configuration

Jest:

// jest.config.js
module.exports = {
  coverageProvider: "v8",
  collectCoverageFrom: ["src/**/*.ts", "!src/**/*.{d,test,stories}.ts", "!src/**/index.ts"],
  coverageThresholds: { global: { branches: 80, functions: 80, lines: 80, statements: 80 } },
};

Vitest: set test.coverage in vitest.config.ts with provider: "v8", thresholds: {branches: 80,...}.

pytest:

# pyproject.toml
[tool.coverage.run]
source = ["src"]
omit = ["src/**/test_*.py", "src/**/conftest.py"]
[tool.coverage.report]
fail_under = 80
show_missing = true
exclude_lines = ["pragma: no cover", "if TYPE_CHECKING:"]

Coverage Types

Priority: Branch > Line > Statement > Function.

Meaningful Thresholds

• 80% line coverage as baseline gate, not a vanity target.
• Branch coverage matters more than line coverage.
• Focus on: business logic, transformations, error paths, edge cases.
• Skip: generated code, type definitions, barrel exports, trivial getters, framework boilerplate.

CI Gate

# Jest/Vitest exit non-zero when thresholds fail. For pytest:
- run: pytest --cov=src --cov-fail-under=80

Mutation Testing

Coverage tells you what code *ran*. Mutation testing tells you if tests would *catch a bug*.

It works by making small source changes (e.g., > to >=, true to false), running tests against each mutant. If tests still pass, the mutant survived -- your tests missed that logic.

Stryker (JS/TS)

npm i -D @stryker-mutator/core @stryker-mutator/jest-runner  # or vitest-runner

// stryker.config.mjs
export default {
  testRunner: "jest",
  coverageAnalysis: "perTest",
  mutate: ["src/**/*.ts", "!src/**/*.test.ts"],
  thresholds: { high: 80, low: 60, break: 50 },
  reporters: ["html", "clear-text", "progress"],
};

Run: npx stryker run

mutmut (Python)

pip install mutmut
mutmut run --paths-to-mutate=src/
mutmut results           # summary
mutmut show 42           # inspect surviving mutant #42

Interpreting Scores

Run mutation testing on critical business logic, not entire codebases. Ignore equivalent mutants (logically identical code).

Snapshot Testing

When to Use

• UI component render output, serialized data structures, CLI formatting
• Output where exact structure matters and is hard to assert field-by-field

When NOT to Use

• Frequently changing output (snapshot fatigue, rubber-stamp reviews)
• Large snapshots (hard to review), implementation details (CSS classes, internal IDs)
• As substitute for targeted assertions when specific values matter

File vs Inline Snapshots

// File snapshot — stored in __snapshots__/*.snap
expect(tree).toMatchSnapshot();

// Inline snapshot — stored in the test file, auto-updated
expect(tree).toMatchInlineSnapshot(`<header><h1>Dashboard</h1></header>`);

Prefer inline for small output (<20 lines). Use property matchers for dynamic values:

expect(user).toMatchSnapshot({ id: expect.any(String), createdAt: expect.any(Date) });

Anti-Patterns (with Fixes)

Testing private methods -- Test through the public API instead. If a private method needs its own tests, extract it to its own module.

Mocking everything -- Only mock external boundaries (network, filesystem, DB, time). Let fast, deterministic internal collaborators use real implementations.

Snapshot overuse -- Use expect(x).toBe("active") for specific values. Reserve snapshots for structured output.

Non-descriptive names -- Replace "works" with "should return empty array when no items match the filter".

Shared mutable state -- Initialize in beforeEach, not at module scope:

// Bad: shared mutation               // Good: fresh per test
const items = [];                     let items: string[];
it("A", () => items.push("a"));      beforeEach(() => { items = []; });
it("B", () => {                      it("A", () => { items.push("a"); expect(items).toHaveLength(1); });
  items.push("b");                   it("B", () => { items.push("b"); expect(items).toHaveLength(1); });
  expect(items).toHaveLength(1); // FAILS
});

Done When

• Coverage thresholds configured in jest.config.*, vitest.config.*, or pyproject.toml and enforced as a CI gate (non-zero exit on failure)
• Test files follow the project's co-location or __tests__ directory convention consistently — no test files in ad-hoc locations
• Mocking strategy documented (in qa-project-context.md or inline): which boundaries get mocked (HTTP, DB, time) and which internal collaborators use real implementations
• No test reaches outside the process boundary — no real HTTP calls, no real database, no filesystem writes to shared state
• All snapshot tests are intentional and reviewed: no auto-accepted snapshots with --updateSnapshot in CI

Related Skills

• coverage-analysis -- Interpreting coverage reports, identifying meaningful gaps, CI integration.
• ci-cd-integration -- Test stages in pipelines, parallelization, caching, deployment gating.
• ai-test-generation -- AI-assisted test generation, edge case discovery, legacy code bootstrapping.
• shift-left-testing -- Pre-commit hooks, IDE integration, developer workflow optimization.