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: MIT5compatibility: Codex, Claude Code, and other Agent Skills-compatible clients.6metadata:7 source: https://skillmd.com/skills/hashgraph-online/test-architecture-strategy8 version: "0.1.0"9 displayName: Test Architecture Strategy10 category: Testing11 tags: tdd,testing,architecture,ci,test-pyramid12---1314# Test Architecture Strategy1516Use 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.1718## Source Traceability1920Primary 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.2122## Workflow23241. Inventory the current suite.25 - Identify unit, integration, functional/end-to-end, smoke, and manual checks.26 - Capture runtime, flake rate, CI split, and developer feedback path.27282. Classify the pain.29 - Slow feedback.30 - Brittle structure-coupled tests.31 - Mock-heavy tests with low confidence.32 - Missing boundary coverage.33 - Too many end-to-end tests.34353. Choose the target shape.36 - Fast tests for core logic and detailed cases.37 - Integration tests at real boundaries.38 - A small number of end-to-end tests for critical journeys.39 - Production monitoring or smoke checks where tests are not enough.40414. Move one slice at a time.42 - Extract pure logic or service boundaries.43 - Replace exhaustive end-to-end coverage with lower-level tests plus one journey.44 - Add contract or integration checks for external systems.45 - Define a runtime red line before the suite becomes painful.4647Read [test-architecture-patterns.md](references/test-architecture-patterns.md) for audit questions, migration patterns, and decision tables.4849## Decision Rules5051- If tests are slow but valuable, first separate fast local feedback from full CI proof.52- If unit tests require databases or frameworks everywhere, identify pure core logic that can move inward.53- If mocks dominate, use architecture seams rather than more mocks.54- If end-to-end tests cover many detailed branches, demote detailed cases to lower-level tests.55- If integration bugs keep escaping, add boundary tests before deleting broad coverage.5657## Guardrails5859- Do not chase a textbook test pyramid without respecting the product's real risks.60- Do not delete slow tests until replacement confidence exists.61- Do not make every piece of code "pure" at the cost of framework clarity.62- Do not optimize runtime without measuring.6364## Verification6566Before finishing, produce:6768- Current suite map.69- Pain classification with evidence.70- Target suite shape.71- First migration slice.72- Verification commands or metrics that prove progress.