test-design-architecture-template.md 9.1KB
workflowStatus: “ totalSteps: 5 stepsCompleted: [] lastStep: “ nextStep: “ lastSaved: “ workflowType: ‘testarch-test-design’
inputDocuments: []
Test Design for Architecture: {Feature Name}
Purpose: Architectural concerns, testability gaps, and NFR requirements for review by Architecture/Dev teams. Serves as a contract between QA and Engineering on what must be addressed before test development begins.
Date: {date} Author: {author} Status: Architecture Review Pending Project: {project_name} PRD Reference: {prd_link} ADR Reference: {adr_link}
Executive Summary
Scope: {Brief description of feature scope}
Business Context (from PRD):
- Revenue/Impact: {Business metrics if applicable}
- Problem: {Problem being solved}
- GA Launch: {Target date or timeline}
Architecture (from ADR {adr_number}):
- Key Decision 1: {e.g., OAuth 2.1 authentication}
- Key Decision 2: {e.g., Centralized MCP Server pattern}
- Key Decision 3: {e.g., Stack: TypeScript, SDK v1.x}
Expected Scale (from ADR):
- {RPS, volume, users, etc.}
Risk Summary:
- Total risks: {N}
- High-priority (≥6): {N} risks requiring immediate mitigation
- Test effort: ~{N} tests (~{X} weeks for 1 QA, ~{Y} weeks for 2 QAs)
Quick Guide
🚨 BLOCKERS - Team Must Decide (Can’t Proceed Without)
Pre-Implementation Critical Path - These MUST be completed before QA can write integration tests:
- {Blocker ID}: {Blocker Title} - {What architecture must provide} (recommended owner: {Team/Role})
- {Blocker ID}: {Blocker Title} - {What architecture must provide} (recommended owner: {Team/Role})
- {Blocker ID}: {Blocker Title} - {What architecture must provide} (recommended owner: {Team/Role})
What we need from team: Complete these {N} items pre-implementation or test development is blocked.
⚠️ HIGH PRIORITY - Team Should Validate (We Provide Recommendation, You Approve)
- {Risk ID}: {Title} - {Recommendation + who should approve} (implementation phase)
- {Risk ID}: {Title} - {Recommendation + who should approve} (implementation phase)
- {Risk ID}: {Title} - {Recommendation + who should approve} (implementation phase)
What we need from team: Review recommendations and approve (or suggest changes).
📋 INFO ONLY - Solutions Provided (Review, No Decisions Needed)
- Test strategy: {Test level split} ({Rationale})
- Tooling: {Test frameworks and utilities}
- Tiered CI/CD: {Execution tiers with timing}
- Coverage: ~{N} test scenarios prioritized P0-P3 with risk-based classification
- Quality gates: {Pass criteria}
What we need from team: Just review and acknowledge (we already have the solution).
For Architects and Devs - Open Topics 👷
Risk Assessment
Total risks identified: {N} ({X} high-priority score ≥6, {Y} medium, {Z} low)
High-Priority Risks (Score ≥6) - IMMEDIATE ATTENTION
| Risk ID | Category | Description | Probability | Impact | Score | Mitigation | Owner | Timeline |
|---|---|---|---|---|---|---|---|---|
| {R-ID} | {CAT} | {Description} | {1-3} | {1-3} | {Score} | {Mitigation strategy} | {Owner} | {Date} |
Medium-Priority Risks (Score 3-5)
| Risk ID | Category | Description | Probability | Impact | Score | Mitigation | Owner |
|---|---|---|---|---|---|---|---|
| {R-ID} | {CAT} | {Description} | {1-3} | {1-3} | {Score} | {Mitigation} | {Owner} |
Low-Priority Risks (Score 1-2)
| Risk ID | Category | Description | Probability | Impact | Score | Action |
|---|---|---|---|---|---|---|
| {R-ID} | {CAT} | {Description} | {1-3} | {1-3} | {Score} | Monitor |
Risk Category Legend
- TECH: Technical/Architecture (flaws, integration, scalability)
- SEC: Security (access controls, auth, data exposure)
- PERF: Performance (SLA violations, degradation, resource limits)
- DATA: Data Integrity (loss, corruption, inconsistency)
- BUS: Business Impact (UX harm, logic errors, revenue)
- OPS: Operations (deployment, config, monitoring)
NFR Testability Requirements
Purpose: Capture what architecture must provide so NFR validation can be automated later. This is planning guidance, not final evidence assessment.
| NFR Category | Threshold / Requirement | Current Design Support | Gap / Decision Needed | Planned Evidence |
|---|---|---|---|---|
| Security | {Auth/authz/data protection requirement} | {Supported/partial/unknown} | {Architecture gap or decision} | {Security tests, scan, audit log} |
| Performance | {Latency/throughput/resource requirement} | {Supported/partial/unknown} | {Architecture gap or decision} | {k6/APM/load report} |
| Reliability | {Availability/error-rate/recovery requirement} | {Supported/partial/unknown} | {Architecture gap or decision} | {Burn-in, monitoring, failover report} |
| Maintainability | {Coverage/code quality/observability requirement} | {Supported/partial/unknown} | {Architecture gap or decision} | {Coverage, static analysis, docs audit} |
Unknown thresholds: {List any missing NFR thresholds. Unknown thresholds should become risks or clarification items, not guessed values.}
Assessment boundary: Final PASS/CONCERNS/FAIL status belongs in nfr-assess after implementation evidence exists.
Testability Concerns and Architectural Gaps
🚨 ACTIONABLE CONCERNS - Architecture Team Must Address
{If system has critical testability concerns, list them here. If architecture supports testing well, state “No critical testability concerns identified” and skip to Testability Assessment Summary}
1. Blockers to Fast Feedback (WHAT WE NEED FROM ARCHITECTURE)
| Concern | Impact | What Architecture Must Provide | Owner | Timeline |
|---|---|---|---|---|
| {Concern name} | {Impact on testing} | {Specific architectural change needed} | {Team} | {Milestone} |
Example:
- No API for test data seeding → Cannot parallelize tests → Provide POST /test/seed endpoint (Backend, pre-implementation)
2. Architectural Improvements Needed (WHAT SHOULD BE CHANGED)
{List specific improvements that would make the system more testable}
- {Improvement name}
- Current problem: {What’s wrong}
- Required change: {What architecture must do}
- Impact if not fixed: {Consequences}
- Owner: {Team}
- Timeline: {Milestone}
Testability Assessment Summary
📊 CURRENT STATE - FYI
{Only include this section if there are passing items worth mentioning. Otherwise omit.}
What Works Well
- ✅ {Passing item 1} (e.g., “API-first design supports parallel test execution”)
- ✅ {Passing item 2} (e.g., “Feature flags enable test isolation”)
- ✅ {Passing item 3}
Accepted Trade-offs (No Action Required)
For {Feature} Phase 1, the following trade-offs are acceptable:
- {Trade-off 1} - {Why acceptable for now}
- {Trade-off 2} - {Why acceptable for now}
{This is technical debt OR acceptable for Phase 1} that {should be revisited post-GA OR maintained as-is}
Risk Mitigation Plans (High-Priority Risks ≥6)
Purpose: Detailed mitigation strategies for all {N} high-priority risks (score ≥6). These risks MUST be addressed before {GA launch date or milestone}.
{R-ID}: {Risk Description} (Score: {Score}) - {CRITICALITY LEVEL}
Mitigation Strategy:
- {Step 1}
- {Step 2}
- {Step 3}
Owner: {Owner} Timeline: {Milestone or date} Status: Planned / In Progress / Complete Verification: {How to verify mitigation is effective}
{Repeat for all high-priority risks}
Assumptions and Dependencies
Assumptions
- {Assumption about architecture or requirements}
- {Assumption about team or timeline}
- {Assumption about scope or constraints}
Dependencies
- {Dependency} - Required by {date/milestone}
- {Dependency} - Required by {date/milestone}
Risks to Plan
- Risk: {Risk to the test plan itself}
- Impact: {How it affects testing}
- Contingency: {Backup plan}
End of Architecture Document
Next Steps for Architecture Team:
- Review Quick Guide (🚨/⚠️/📋) and prioritize blockers
- Assign owners and timelines for high-priority risks (≥6)
- Validate assumptions and dependencies
- Provide feedback to QA on testability gaps
Next Steps for QA Team:
- Wait for pre-implementation blockers to be resolved
- Refer to companion QA doc (test-design-qa.md) for test scenarios
- Begin test infrastructure setup (factories, fixtures, environments)