/test-harness

name: test-harness
description: 'Generates pytest test suites with happy path, edge cases, error conditions, fixture scaffolding, mocks, async patterns. Triggers on: "generate tests", "write tests for", "test this function", "create test suite", "pytest for", "unit tests for", "mock strategy for".'
metadata:
  version: 1.1.1
  category: development
  tags: [testing, pytest, test-generation, python]
  difficulty: intermediate
  phase: build

Test Harness

Systematic test suite generation that transforms source code into comprehensive, runnable pytest files. Analyzes function signatures, dependency graphs, and complexity hotspots to produce tests covering happy paths, boundary conditions, error states, and async flows — with properly scoped fixtures and focused mocks.

Reference Files

| File | Contents | Load When | | -------------------------------- | ---------------------------------------------------------------------- | -------------------------------- | | `references/pytest-patterns.md` | Fixture scopes, parametrize, marks, conftest layout, built-in fixtures | Always | | `references/mock-strategies.md` | Mock decision tree, patch boundaries, assertions, anti-patterns | Target has external dependencies | | `references/async-testing.md` | pytest-asyncio modes, event loop fixtures, async mocking | Target contains async code | | `references/fixture-design.md` | Factory fixtures, yield teardown, scope selection, composition | Test requires non-trivial setup | | `references/coverage-targets.md` | Threshold table, branch vs line, pytest-cov config, exclusion patterns | Coverage assessment requested |

Prerequisites

• **pytest** >= 7.0
• **Python** >= 3.10
• **pytest-asyncio** — required only when generating async tests
• **pytest-mock** — optional, provides `mocker` fixture as alternative to `unittest.mock`

Workflow

Phase 1: Reconnaissance

Before writing a single test, build a model of the target code:

1. **Identify scope** — What functions, classes, or modules need tests? If unspecified, check for recent modifications: `git diff --name-only HEAD~5` 2. **Read function signatures** — Parameters, types, return types, defaults. Every parameter is a test dimension. 3. **Map dependencies** — Which calls go to external systems (DB, API, filesystem, clock)? These are mock candidates. 4. **Detect complexity hotspots** — Functions with high branch counts, deep nesting, or multiple return paths need more test cases. 5. **Check existing tests** — If tests already exist, understand what they cover. Do not duplicate; extend. 6. **Read project conventions** — Check CLAUDE.md, conftest.py, pytest.ini/pyproject.toml for fixtures, markers, and test organization patterns already in use.

Phase 2: Test Case Enumeration

For each function under test, enumerate cases across four categories:

| Category | What to Test | Example | | ---------- | ---------------------------------------------- | ------------------------------------------- | | Happy path | Expected inputs produce expected outputs | `add(2, 3)` returns `5` | | Boundary | Edge values at limits of valid input | Empty string, zero, max int, single element | | Error | Invalid inputs trigger proper exceptions | `None` where `str` expected, negative index | | State | State transitions produce correct side effects | Object moves from `pending` to `active` |

For each case, note:

• Input values (concrete, not abstract)
• Expected output or exception
• Required setup (fixtures)
• Required mocks (external calls to suppress)

Parametrize cases that share the same test logic but differ only in input/output values.

Phase 3: Fixture Design

1. **Identify shared setup** — If 3+ tests need the same object, extract a fixture. 2. **Select scope** — Use the narrowest scope that avoids redundant setup:

| Scope | Use When | Example | | ---------- | ------------------------------------------ | ---------------------------- | | `function` | Default. Each test gets fresh state | Most unit tests | | `class` | Tests within a class share expensive setup | DB connection per test class | | `module` | All tests in a file share setup | Loaded config file | | `session` | Entire test run shares setup | Docker container startup |

3. **Design teardown** — Use `yield` fixtures when cleanup is needed. Never leave side effects (temp files, DB rows, monkey-patches) after a test. 4. **Identify conftest candidates** — Fixtures used across multiple test files belong in `conftest.py`. Fixtures used in one file stay in that file.

Phase 4: Mock Strategy

1. **Decide what to mock** — Mock external dependencies only:

• Network calls (API, database, message queues)
• Filesystem operations (when testing logic, not I/O)
• Time-dependent behavior (`datetime.now`, `time.sleep`)
• Random/non-deterministic behavior

2. **Decide what NOT to mock** — Never mock:

• The function under test
• Pure functions called by the target (test them through the target)
• Data structures and value objects

3. **Choose mock level** — Patch at the import boundary of the module under test, not at the definition site. `@patch('mymodule.requests.get')`, not `@patch('requests.get')`.

4. **Add mock assertions** — Every mock should assert it was called with expected arguments and the expected number of times. Mocks without assertions are coverage holes.

Phase 5: Output

Generate the test file following this structure:

1. Imports (pytest, mocks, target module) 2. Constants