Architecture Testing
Overview
Enforce architectural boundaries with automated tests. Prevents coupling that causes maintenance debt.
REQUIRED: superpowers:test-driven-development, superpowers:verification-before-completion
When to Use
- User mentions architecture, boundaries, layers, dependency rules
- Creating production-quality application
- Opt-out offered: New apps without production/best-practice/pattern request
Detection and Deference
Before creating architecture tests, check for existing patterns:
Existing Tests Detection
| Pattern | Detection Command | If Found |
|---|---|---|
| .NET ArchTests | find . -name "*.ArchitectureTests.csproj" | Enhance existing |
| NetArchTest refs | grep -r "NetArchTest" *.csproj | Use existing project |
| ArchUnit (Java) | grep -r "archunit" pom.xml build.gradle | Use existing tests |
| docs/architecture | test -f docs/architecture-overview.md | Reference existing |
Deference Rules
When existing architecture tests are detected:
- Existing test project: Enhance with additional rules, do not create new project.
- Existing architecture doc: Update existing doc, do not create duplicate.
- Partial coverage: Add tests for uncovered boundaries only.
Only create new architecture test project when detection finds nothing.
Decision Capture
Architecture decisions must be captured in the target repository:
- Architecture ADR: Create
docs/decisions/NNNN-architecture-pattern.md - Architecture Overview: Update
docs/architecture-overview.md - Test Project README: Document which boundaries are tested
Architecture ADR Template
# ADR-NNNN: Architecture Pattern Selection
## Status
Accepted
## Context
Project needs defined architectural boundaries.
## Decision
Use [Clean Architecture / Hexagonal / Layered] pattern.
## Rationale
- [Why this pattern fits the project]
- [Trade-offs considered]
## Consequences
- Architecture tests enforce: [list of rules]
- Violations fail the build
This ensures future developers understand the architectural constraints.
Core Workflow
- Opt-out check: New app without production quality request? Offer opt-out explicitly
- Pattern selection: Clean, Hexagonal, Onion, Layered, or Modular Monolith
- Define boundaries: Minimum 3 layers with explicit dependency rules
- Add enforcement: NetArchTest (.NET), ArchUnit (Java), or custom
- CI integration: Tests in pipeline, fail build on violations
- Document: Update
docs/architecture-overview.md(human-readable) - Brownfield: Permissive initial tests, tighten incrementally
See Pattern Details and NetArchTest Examples.
Reference Templates
Use pre-built templates to accelerate architecture test setup:
| Pattern | Template | Use Case |
|---|---|---|
| Clean Architecture | templates/clean-architecture-tests.cs.template | Domain-centric apps |
| Layered Architecture | templates/layered-architecture-tests.cs.template | Traditional N-tier |
Using Templates
- Copy template to
tests/{Project}.ArchitectureTests/ - Replace
{NAMESPACE}with your root namespace - Add NetArchTest NuGet package
- Adjust layer names to match your project structure
- Run tests to verify boundaries
Rationalizations Table
| Excuse | Reality |
|---|---|
| "Can add architecture later" | Later never happens. 10 min now saves hours later. |
| "Speed over architecture" | Architecture prevents defects. Defects cost more time. |
| "Demo doesn't need it" | Demos become production. Start right or rewrite. |
| "Too disruptive to existing code" | Use brownfield approach: permissive tests, tighten gradually. |
| "Tech lead said skip it" | Clarify cost with tech lead. They may not realize impact. |
| "Working code ships" | Shipping debt accumulates interest. Pay now or pay more later. |
Red Flags - STOP
- "Can add architecture later"
- "Too simple for boundaries"
- "Would block the deploy" (without proposing brownfield)
- "Tech lead said skip it" (without clarifying cost)
All mean: Apply brownfield approach or document explicit opt-out in docs/exclusions.md.