--- name: tests-testability-review description: Reviews code for unit-testability and reports minimal design changes needed for fast, isolated, maintainable tests. Use when the user asks if code is testable, requests a testability review, wants unit-test readiness feedback, or needs code shaped for testing in any language or framework. --- # Tests Testability Review ## Purpose Review code and decide whether high-quality tests can be written without excessive setup, slow dependencies, brittle mocks, or implementation-detail assertions. ## Review Workflow Use this checklist: ```markdown Testability review checklist - [ ] Identify the unit of work and its observable end result - [ ] List dependencies: IO, DB, network, clock, randomness, globals, threads, framework runtime - [ ] Check whether dependencies can be controlled or replaced - [ ] Check whether behavior can be asserted through public API, state, or call contract - [ ] Check whether edge/error states are easy to construct - [ ] Flag design choices that force slow, flaky, or overspecified tests - [ ] Propose the smallest refactor that unlocks useful tests ``` ## What To Flag Flag as testability risks: 1. Hidden dependencies: module singletons, service locators, implicit globals, ambient context. 2. Direct external IO in logic that should be unit tested. 3. Hard-coded time, random values, generated IDs, or current user/session state. 4. Constructors or static initializers that perform logic or external work. 5. Concrete dependency creation inside methods with business logic. 6. Static methods/classes used as behavior dependencies in static languages. 7. Large methods that combine parsing, validation, persistence, side effects, and formatting. 8. Private methods that seem to deserve direct tests because public behavior is too broad. 9. Outputs that require peeking into private state or exact internal call order. 10. Shared mutable state that can leak between tests. ## Preferred Design Signals Prefer and reward: - public behavior with clear inputs and outputs - explicit dependency injection for required collaborators - small role interfaces or function/delegate parameters where they clarify dependencies - wrappers around cross-cutting concerns such as time, random, environment, and logging - pure transformation logic separated from side effects - typed errors/results that tests can assert directly - factories or local factory methods when direct construction would hide dependencies - reset hooks for unavoidable global/singleton state ## Refactor Guidance Recommend the smallest useful change: - Extract pure logic before changing broad architecture. - Introduce a seam at the shallowest understandable layer. - Prefer constructor injection for required dependencies. - Prefer parameter injection for per-call behavior. - Prefer a focused wrapper for cross-cutting dependencies used throughout the app. - For legacy code, add characterization/integration coverage before refactoring. - Do not add broad abstractions only for hypothetical future tests. ## Output Format Return findings in this format: ```markdown Testability Review: Overall: Pass | Needs changes Score: <0-100> Strengths - Risks - : Minimal Refactors 1. 2. Suggested First Tests - __ - __ ``` ## Scoring Rubric - 25: Observable behavior through public contracts - 25: Dependency control and useful seams - 20: Determinism and isolation - 15: Edge/error state reachability - 15: Simplicity/readability of expected tests Interpretation: - 85-100: Ready for high-quality unit tests - 70-84: Testable with minor cleanup - 50-69: Needs focused refactor before efficient unit tests - 0-49: Not unit-test friendly yet ## Feedback Style - Lead with concrete blockers and their testing impact. - Tie every recommendation to a specific test that becomes easier. - Avoid broad rewrites unless the current design blocks meaningful tests. - Mention integration testing when unit isolation would produce low-value abstractions.

tests-testability-review

Install this skill

Comments