Codebase testing guide

Codebase Testing Guide

Document the testing setup of a codebase. The output answers: "If I need to write a test in this project, what framework do I use, where does the file go, how do I mock dependencies, and what patterns am I expected to follow?"

Scope

This skill is narrow by design. It covers ONLY:

• Test framework and config
• Where tests live (colocated vs separate, naming conventions)
• Mocking approach and patterns
• Fixtures, factories, and test helpers
• How to run the suite (and individual tests)
• Coverage setup (if any)
• Recurring testing patterns (table-driven, snapshot, golden file, property-based, etc.)

For everything else, point the user to a sister skill: codebase-overview for architecture, codebase-conventions for naming, codebase-error-handling for errors, codebase-glossary for domain vocabulary.

What to Produce

A Markdown file with the structure below. Every section must include real examples from the actual codebase — real test file paths, real mock setups, real fixture definitions copied verbatim.

# {Project Name} — Testing Guide

> Generated by codebase-testing-guide on {YYYY-MM-DD}

## Framework & Config

{Test runner name and version, config file path, any plugins or extensions in use, language/transpiler setup if relevant.}

**Config file:** `{path}`

**Key settings:**
\```{language}
{Real excerpt from the config file showing notable settings}
\```

## How to Run Tests

{Commands to run: full suite, single file, single test by name, watch mode, with coverage. Pull from the actual `package.json` scripts / `Makefile` / `justfile` / `pyproject.toml` / `pubspec.yaml` — don't invent commands.}

## Test Structure

{Where tests live (colocated next to source, separate `tests/` directory, `__tests__/` subdirectory). Naming convention (`.test.ts`, `_test.go`, `test_*.py`, etc.). How tests are organized within a file (describe/it, test classes, table tests, top-level functions).}

**Real example:** `{actual/test/file/path}`
\```{language}
{Real test snippet from the project showing the structure}
\```

## Mocking & Stubbing

{What gets mocked (network calls, time, filesystem, database, external SDKs), how (jest.mock / vi.mock / unittest.mock / pytest fixtures / dependency injection), and where mocks are defined (inline vs centralized).}

**Real example:**
\```{language}
{Real mock setup from an existing test}
\```

## Fixtures & Factories

{Fixture/factory pattern in use (pytest fixtures, factory-boy, faker, MSW handlers, custom builder functions). Where fixture files live. How they're shared across tests.}

**Real example:**
\```{language}
{Real fixture or factory definition from the codebase}
\```

## Test Helpers & Utilities

{Shared test setup — custom render functions for React, request builders for API tests, time freezers, seed helpers. Where they live.}

**Real example:**
\```{language}
{Real helper function from the test suite}
\```

## Coverage

{Coverage tool (if any), config, target threshold, where reports go, whether coverage is enforced in CI. If coverage isn't tracked, say so explicitly: "Coverage not configured."}

## Notable Testing Patterns

For each pattern detected, include a description, where it shows up, and a real snippet.

### {Pattern 1 — e.g., "Table-driven tests in Go"}

{2–3 sentence description}

**Where it shows up:** `{file 1}`, `{file 2}`

**Snippet:**
\```{language}
{Real code from one of the files above}
\```

### {Pattern 2}
...

## Inconsistencies & Notes

{Tests that follow a different convention from the rest, abandoned test files, integration tests mixed with unit tests, suspicious skipped tests with `it.skip`/`xit`/`@pytest.mark.skip`/etc. — anything a new contributor would want to know but wouldn't discover from reading the rest cleanly.}

{If you couldn't find a clear pattern in some area, list it here.}

How to Scan

# Test files — broad sample
find . \( -name "*.test.*" -o -name "*.spec.*" -o -name "test_*.py" -o -name "*_test.go" -o -name "*_spec.rb" -o -name "*_test.dart" \) -not -path '*/node_modules/*' -not -path '*/.git/*' -not -path '*/vendor/*' 2>/dev/null | head -30

# Test count by type
find . \( -name "*.test.*" -o -name "*.spec.*" -o -name "test_*.py" -o -name "*_test.go" \) -not -path '*/node_modules/*' 2>/dev/null | wc -l

# Test framework config
cat vitest.config.* jest.config.* karma.conf.* playwright.config.* 2>/dev/null | head -60
cat pytest.ini setup.cfg conftest.py 2>/dev/null | head -40
grep -A 20 '\[tool.pytest' pyproject.toml 2>/dev/null
cat go.mod 2>/dev/null | head -10  # Go uses built-in testing
grep -A 10 'dev_dependencies' pubspec.yaml 2>/dev/null  # Dart/Flutter

# Run scripts
grep -A 30 '"scripts"' package.json 2>/dev/null
grep -E '^test|^check' Makefile justfile 2>/dev/null
grep -A 5 '\[tool.poetry.scripts\]\|\[project.scripts\]' pyproject.toml 2>/dev/null

# Mocking patterns (broad)
grep -rn "vi\.mock\|jest\.mock\|@mock\|Mock()\|patch(\|@patch\|mockito\|gomock\|sinon" --include="*.test.*" --include="*.spec.*" --include="test_*.py" --include="*_test.go" --include="*_test.dart" 2>/dev/null | head -15

# Fixtures
grep -rn "@fixture\|@pytest\.fixture\|beforeEach\|beforeAll\|setUp(\|setup(" --include="*.test.*" --include="*.spec.*" --include="test_*.py" --include="*_test.go" 2>/dev/null | head -15

# Factory patterns (factory-boy, fishery, Faker, etc.)
grep -rn "factory\.Sequence\|class Meta\|fishery\|Faker()\|faker\." --include="*.py" --include="*.ts" --include="*.tsx" 2>/dev/null | head -10

# Skipped / disabled tests — surface as a note
grep -rn "\.skip\|xit(\|xdescribe\|@pytest\.mark\.skip\|t\.Skip" --include="*.test.*" --include="*.spec.*" --include="test_*.py" --include="*_test.go" 2>/dev/null | head -10

# Coverage config
ls .coveragerc coverage.xml 2>/dev/null
grep -A 5 'coverage' jest.config.* vitest.config.* pyproject.toml package.json 2>/dev/null | head -20

# CI test step
grep -E 'test|pytest|vitest|jest|go test|flutter test' .github/workflows/*.yml .gitlab-ci.yml 2>/dev/null | head -10

When you find an interesting test, read the file and copy a real snippet — don't paraphrase. Show the test in full enough context that the convention is visible.

Where to Save

Check for an existing docs location:

• If docs/ exists, save as docs/testing-guide.md
• If documentation/ exists, save as documentation/testing-guide.md
• If .claude/ exists, save as .claude/testing-guide.md
• Otherwise propose docs/testing-guide.md and ask the user before creating

For monorepos where each package has its own test setup, ask the user whether to produce one guide for the whole repo or one per package.

Principles

Real examples only. Every section must include at least one real, copy-pasteable example from the actual test suite. Generic descriptions like "the project uses Jest" without showing a real test fail this skill's contract.

Cite locations. When you show an example, include the file path. The user should be able to open the file and see the test in context.

Show full enough context. A 5–10 line snippet that shows the surrounding describe / setUp / fixture is more useful than a 1-line excerpt of the assertion.

Surface skipped tests. Tests marked .skip, xit, @pytest.mark.skip, etc. are tribal knowledge — usually they're flaky, broken, or temporarily disabled. Surface them in "Inconsistencies & Notes" with the file path. Don't analyze why they're skipped, just flag them.

Don't invent commands. Pull run commands from the actual package.json / Makefile / pyproject.toml. If the project has a just test recipe, document just test, not pytest.

Don't drift in scope. If you find yourself documenting architecture, naming, or error handling, stop. Note the observation as a one-liner at the end and point the user to the right sister skill.

After Producing

1. Save the file to the chosen location.
2. In chat, surface the 1–2 most surprising or non-obvious patterns — these are the ones a new contributor is most likely to need help with on their first test.
3. If you found skipped tests, broken tests, or a test directory that doesn't run in CI, call those out — that's signal the team will care about.
4. Provide a path or link to the saved file.