Test Architecture Strategy
Use this skill to reason about the shape of a test suite, not one test at a time. The goal is a suite that gives confidence, runs quickly enough for flow, and still catches integration failures at important boundaries.
Source Traceability
Primary source: Harry Percival, Test-Driven Development with Python, 3rd ed. Guidance is transformed and paraphrased from chapter 27 and Appendix A, especially test desiderata, fast/slow test tradeoffs, test pyramid thinking, boundaries, ports and adapters, functional core/imperative shell, and when to rethink architecture.
Workflow
Inventory the current suite.
- Identify unit, integration, functional/end-to-end, smoke, and manual checks.
- Capture runtime, flake rate, CI split, and developer feedback path.
Classify the pain.
- Slow feedback.
- Brittle structure-coupled tests.
- Mock-heavy tests with low confidence.
- Missing boundary coverage.
- Too many end-to-end tests.
Choose the target shape.
- Fast tests for core logic and detailed cases.
- Integration tests at real boundaries.
- A small number of end-to-end tests for critical journeys.
- Production monitoring or smoke checks where tests are not enough.
Move one slice at a time.
- Extract pure logic or service boundaries.
- Replace exhaustive end-to-end coverage with lower-level tests plus one journey.
- Add contract or integration checks for external systems.
- Define a runtime red line before the suite becomes painful.
Read test-architecture-patterns.md for audit questions, migration patterns, and decision tables.
Decision Rules
- If tests are slow but valuable, first separate fast local feedback from full CI proof.
- If unit tests require databases or frameworks everywhere, identify pure core logic that can move inward.
- If mocks dominate, use architecture seams rather than more mocks.
- If end-to-end tests cover many detailed branches, demote detailed cases to lower-level tests.
- If integration bugs keep escaping, add boundary tests before deleting broad coverage.
Guardrails
- Do not chase a textbook test pyramid without respecting the product's real risks.
- Do not delete slow tests until replacement confidence exists.
- Do not make every piece of code "pure" at the cost of framework clarity.
- Do not optimize runtime without measuring.
Verification
Before finishing, produce:
- Current suite map.
- Pain classification with evidence.
- Target suite shape.
- First migration slice.
- Verification commands or metrics that prove progress.
1---2name: test-architecture-strategy3description: Design a sustainable test architecture using test desiderata, test pyramid tradeoffs, fast and slow test separation, integration boundaries, CI feedback loops, and architecture choices that make code testable. Use when a test suite is too slow, too brittle, too mock-heavy, unclear about unit vs integration coverage, or needs a testing strategy before major growth.4license: MIT5---67# Test Architecture Strategy89Use this skill to reason about the shape of a test suite, not one test at a time. The goal is a suite that gives confidence, runs quickly enough for flow, and still catches integration failures at important boundaries.1011## Source Traceability1213Primary source: Harry Percival, *Test-Driven Development with Python*, 3rd ed. Guidance is transformed and paraphrased from chapter 27 and Appendix A, especially test desiderata, fast/slow test tradeoffs, test pyramid thinking, boundaries, ports and adapters, functional core/imperative shell, and when to rethink architecture.1415## Workflow16171. Inventory the current suite.18 - Identify unit, integration, functional/end-to-end, smoke, and manual checks.19 - Capture runtime, flake rate, CI split, and developer feedback path.20212. Classify the pain.22 - Slow feedback.23 - Brittle structure-coupled tests.24 - Mock-heavy tests with low confidence.25 - Missing boundary coverage.26 - Too many end-to-end tests.27283. Choose the target shape.29 - Fast tests for core logic and detailed cases.30 - Integration tests at real boundaries.31 - A small number of end-to-end tests for critical journeys.32 - Production monitoring or smoke checks where tests are not enough.33344. Move one slice at a time.35 - Extract pure logic or service boundaries.36 - Replace exhaustive end-to-end coverage with lower-level tests plus one journey.37 - Add contract or integration checks for external systems.38 - Define a runtime red line before the suite becomes painful.3940Read [test-architecture-patterns.md](references/test-architecture-patterns.md) for audit questions, migration patterns, and decision tables.4142## Decision Rules4344- If tests are slow but valuable, first separate fast local feedback from full CI proof.45- If unit tests require databases or frameworks everywhere, identify pure core logic that can move inward.46- If mocks dominate, use architecture seams rather than more mocks.47- If end-to-end tests cover many detailed branches, demote detailed cases to lower-level tests.48- If integration bugs keep escaping, add boundary tests before deleting broad coverage.4950## Guardrails5152- Do not chase a textbook test pyramid without respecting the product's real risks.53- Do not delete slow tests until replacement confidence exists.54- Do not make every piece of code "pure" at the cost of framework clarity.55- Do not optimize runtime without measuring.5657## Verification5859Before finishing, produce:6061- Current suite map.62- Pain classification with evidence.63- Target suite shape.64- First migration slice.65- Verification commands or metrics that prove progress.
LVTD-LLC