Spring Boot Testing
Own the configuration and lifetime of the harness that makes a Boot test meaningful.
Activate when assembling evidence for a new service, or for missing slice collaborators,
unexpected overrides, misleading transaction assertions, server-test cleanup, or
context/container reuse failures. Preserve a sound harness; a failing test alone does
not justify widening it to @SpringBootTest.
Start with a test of the project's actual behavior and its existing Boot facilities:
@WebMvcTest, @DataJpaTest, supported bean overrides, and test-service connections.
Do not introduce an example application, a generic test interface, a connection helper,
or a framework lifecycle probe merely to demonstrate an annotation. A diagnostic probe
is justified only when it distinguishes a concrete unresolved failure; keep it separate
from reusable application code.
Establish what actually runs
Inspect the project's build, wrapper, compiler/toolchain, resolved Boot/Framework/test versions, test annotations/imports, active properties and CI command. This skill's executable baseline is Java 25, Boot 4.1.1, with Boot-managed dependencies and no preview flags. Apply version-sensitive APIs only after checking the target; selecting the skill does not authorize an upgrade or changing its build tool.
Use the official Spring Boot documentation for test modules, slices and service connections; consult Spring Data JPA for repository and persistence claims and Spring Security for filter-chain and security-test claims. Select versions matching the project's resolved dependencies. Read the sections relevant to the decision, with Framework documentation as a complement for test transactions, overrides and context caching.
Trace the named assertion to its real collaborators, request transport, thread,
transaction, database and cleanup owner. Inspect fresh test reports: an undiscovered,
disabled or environmentally skipped test provides no behavioral evidence. Keep test
services and configuration isolated from real application environments.
If startup customization is part of the claim, inspect the selected application class,
its main method and the test's useMainMethod policy. A full context or live server
does not by itself establish that the application's launch customization ran.
Recover the expected behavior from consumer contracts, acceptance criteria and relevant
ADRs; inspect the test contribution guide, fixtures and CI infrastructure before choosing
a new harness. An incidental existing test is not a testing policy, and current output
alone does not decide a disputed contract. Ask only about unresolved choices that change
the test: for example, which published client contract must remain compatible when schema
and validation disagree. Recommend preserving that contract pending an explicit change;
continue independent harness diagnosis while the policy decision is open. Use explicit,
reversible assumptions for local fixture details, not access or consistency guarantees.
Choose the discriminating check
- New service or acceptance review: name each required observable behavior and identify the harness that can expose its failure. Include a real path through the selected HTTP, security and persistence boundaries; mocks and coverage counts cannot establish that those boundaries work together. Read service acceptance boundaries to distinguish real collaborators from real transport. Reuse an adequate context and test service; add a boundary only when an agreed claim requires it. Defer unrelated acceptance gaps with their risk and trigger for follow-up; a narrow repair does not require a new suite.
- Slice configuration: compare loaded configuration with the real application's relevant controller advice, converters and filter chains. Import the necessary real wiring and replace only the boundary outside the test's claim. A successful request with filters disabled does not validate authorization. Read slice and override diagnosis.
- Persistence or live-server state: identify where commit happens and observe it independently. Flush, test rollback and server commit are different events; cleanup must survive the test's rollback. Read transaction observability.
- Suite-only failures or repeated startup: compare context keys, forks and resource lifetimes before changing caching. A service must remain available as long as a cached client needs it; resetting shared state is separate from rebuilding the context. Read context and service lifetime.
When implementing or repairing tests, read the focused execution and handoff procedure in verification; its routed asset instructions provide concrete MVC replacement and persistence test shapes. The runnable examples cover those two boundaries; full service acceptance, context/container and listener-phase guidance are conditional references. Adapt the relevant test to existing application types. Do not copy the fixture's build or all its tests into an existing project.
For a repair, deliver the focused configuration change and a check that would expose the original harness defect. For diagnosis/review, state the observation, why the current test cannot establish its claim, and the next discriminating check. Report executed counts and material coverage gaps without requiring a large report for a small fix. Update the existing test guide when invocation, prerequisites or cleanup ownership changes; preserve its local/CI split. Missing Docker permits compilation and other tests, not a claim that a required container-backed path passed.
Responsibility boundaries
Use java-testing-strategy for coverage allocation and CI discovery policy,
java-test-design for assertions and test structure, and java-test-doubles for the
choice of replacement. This skill owns their Boot configuration consequences.
Use spring-boot for application bean/property composition, spring-boot-web for HTTP
contracts, spring-security-for-apis for authorization/authentication policy,
spring-boot-jpa for mappings and SQL, and spring-transactions-and-events for
application transaction/event semantics. Pass the harness, actual versions, failing
request or transaction trace, and the missing observation; expect a domain correction
that this harness can test. These are optional handoffs, not required installations.
If unavailable, preserve the boundary and state the unresolved domain claim.