10.2The Three-Step Workflow

Step 1: Feed Context and Generate

# Feed the spec and existing test as context, request a test suite
claude "Read the OpenAPI spec at ./docs/api-spec.yaml and the existing
test file at ./tests/test_users.py. Generate a comprehensive test suite
for the /api/v2/orders endpoint following the same patterns and style
as the users tests. Include error cases for all documented 4xx responses."

What happens under the hood:

• Claude reads ./docs/api-spec.yaml (the specification artifact)
• Claude reads ./tests/test_users.py (the style reference)
• Claude identifies the endpoint constraints, field types, auth requirements
• Claude generates a new test file following the existing patterns

Pro tips for Step 1:

• Point Claude at specific files rather than asking it to "find" things
• Mention the existing test file explicitly so it matches your team's style
• Be specific about what coverage you want ("all documented 4xx responses")

Step 2: Run and Self-Heal

# Ask Claude to run the tests and fix test bugs (not application bugs)
claude "Run the tests you just generated. Fix any failures that are
due to test bugs (not application bugs). Do not change assertions
that are testing real behavior."

What happens under the hood:

• Claude executes pytest tests/test_orders.py -v
• It reads the failure output
• It distinguishes between:
  • Test bugs: import errors, wrong fixture names, missing setup
  • Application bugs: assertions that fail because the app has a real defect
• It fixes only test bugs and reports application bugs

The critical instruction: "Do not change assertions that are testing real behavior." Without this, Claude might weaken assertions to make tests pass, defeating the purpose.

Step 3: Coverage Gap Analysis

# Run coverage and generate tests for uncovered lines
claude "Run pytest --cov=app.routes.orders --cov-report=term-missing
and tell me which lines in the orders route are not covered.
Generate additional tests to cover those lines."

What happens under the hood:

• Claude runs the coverage command
• It reads the Missing column to identify uncovered line ranges
• It reads those specific lines in the source file
• It generates additional tests targeting those lines specifically