test-architecture-strategy

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

1. 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.

1. Classify the pain.

• Slow feedback.
• Brittle structure-coupled tests.
• Mock-heavy tests with low confidence.
• Missing boundary coverage.
• Too many end-to-end tests.

1. 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.

1. 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](references/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.