Architecture Testing

Architecture Testing

Purpose and scope

Turn an agreed architectural promise into a test that exercises its actual mechanism and fails for the intended violation. A green functional test does not establish transaction, dependency, concurrency or compatibility properties it never observes. This skill owns test design and implementation, not architecture selection or governance policy.

Before choosing version-sensitive test APIs, inspect compiler release/toolchains, resolved framework/test-library versions, runner configuration and the JDKs used by tests and deployment. The structural example uses release 17 source compilation; its recorded run used JDK 25, not a Java 17 runtime. Match the target project rather than upgrading it to fit an example. New dependencies, preview features and toolchain upgrades require their own justification and scope.

Workflow

1. Name the promise and failure. Obtain the relevant implementation, existing tests, package/contract or transaction boundary, dependency versions and build command. For data tests, also obtain engine/version, migrations, isolation and cache settings. For a budget, identify the operation and what is counted. If the promise or threshold is unknown, propose a conditional test design and request the missing contract; do not invent the architecture.
2. Choose the smallest setup that retains the mechanism. Use the table below. Fakes and mocks can isolate behavior but do not establish database or network semantics. A full context is justified when proxying, wiring or cross-layer behavior is the assertion; inspect slow-suite timing before assuming that a large context is the cause.
3. Control the observation. Define fixture state, transaction ownership, caches, execution scope, cleanup and time bounds. Count selected classes/tests or observed operations where an empty selection or disabled instrument could produce a false green.
4. Prove the test detects the defect. Use a small violating fixture or a temporary mutation: forbidden dependency, missing transaction, lazy fetch regression or stale write. Observe the intended assertion fail, then restore the valid state and rerun. A compile/setup error is not that proof. Keep mutations isolated and preserve unrelated work.
5. Report evidence and limits. Name the command, actual tests run and result, plus what remains untested. A configuration inspection is evidence of intent; a runtime result proves only the tested state/interleaving/version. For diagnosis, separate the suspected blind spot from a reproduced defect and name the experiment that would distinguish them.

Match the assertion to the mechanism

Read Boundary and contract tests for structural, web, gateway or compatibility checks. Read Persistence and concurrency tests for data, rollback, budget, migration or concurrency checks. Neither reference is required for a pure domain assertion.

Decision rules

• Choose doubles by the assertion. A fake can model useful state but can also drift; a mock can verify a meaningful interaction without freezing every call order. Neither proves the real adapter works. Avoid simulating vendor internals when a controlled boundary is available.
• An alternative in-memory engine can catch some defects; it cannot establish fidelity to the production engine's dialect, locking or constraints. Testcontainers is one provisioning option, not a substitute for matching versions/configuration or ensuring isolation.
• Do not replace semantic properties with convenient syntax. A suffix rule tests names, not aggregate ownership; an annotation-location rule does not prove a transaction executes.
• Test application/framework integration where it is your responsibility: constraints actually applied to the request, converters preserving precision, and advice mapping errors. Do not delete these checks merely because a framework implements part of the mechanism.
• Budget tests catch access growth, not acceptable latency or plans. Performance/plan checks may run in dedicated CI when representative resources exist; hand capacity claims to load-testing and diagnosis to architecture-and-performance.
• An overlap test covers a chosen schedule, not all races. A single-threaded sequence using stale detached state can verify optimistic version checks; it cannot establish concurrent lock behavior.
• Keep accepted exemptions narrow, named and explained. Do not widen imports, disable empty-rule failures, reset a baseline or weaken an assertion simply to make the build green.

Minimum deliverable

For a review: evidence, defect or coverage gap, consequence, adjustment and validation. For implementation: the focused test/change, its prerequisites, how the violating case fails, the passing run and any remaining coverage gap. Scale this to the task; no suite-wide report is needed for one guard.

Choosing thresholds and consequences belongs to architecture-fitness-functions; transaction design to enterprise-transactions; contract policy to rpc-and-api-contracts. Use Validation cases when evaluating this skill or rehearsing a difficult review. Those cases evaluate agent decisions, not the application under test.