a-pavithraa/springboot-skills-marketplace / plugins/springboot-architecture/skills/writing-springboot-tests
writing-springboot-tests
VerifiedUse when writing or adding tests or integration tests for Spring Boot code at a service's edges: HTTP clients that call other services (WireMock: 4xx and 5xx responses, timeouts, retries), Kafka or RabbitMQ listeners (redelivery, poison messages, dead-letter topics), events published to other services, or full-API tests against real databases with Testcontainers; domain logic whose rules must hold for every input (calculations, value objects, state transitions, parsing and formatting), tested as properties over generated inputs; also when a Boot 4 test needs the right imports, slices or container wiring. Supplies verified Boot 4.1 templates and the framework traps that make such tests pass without proving anything. Not for reviewing existing tests (see code-reviewer) or Boot 3 to 4 test migration (see springboot-migration).
Writing Spring Boot Tests
Use this for tests where the framework, not the logic, decides whether the test proves anything: calls and messages between services, retries, timeouts, transactions, and Boot 4 test wiring. For domain logic, see "Domain rules as properties". For other plain unit tests you need nothing here beyond the rules.
Rules
- Cases come from the contract, clause by clause. Every sentence of the Javadoc, the provider's API documentation, or an agreed message format is a case: units and formats (cents or decimals, field names), status codes with a special meaning (a 409 that means "already done"), headers, time limits, delivery promises (once only, after commit, poison messages dead-lettered). Call the code the way its callers do, with their values, so conversions run.
- Run the real thing at the edge. Real HTTP (WireMock), the real broker and database (Testcontainers), real transactions. A mocked client, template, or transaction manager can't show timeouts, retries, redelivery, or publish-after-commit. Timeout tests use the production timeout value. Build the client the way production does (its bean, or its builder settings) and point it at the stub. If the client can't be pointed elsewhere, make its base URL or endpoint configurable: that improves the design. If it has no timeout at all, report that as a finding instead of skipping the test. AWS SDK clients count: see
traps.md. - Show each test failing once, and treat a failing test as a finding. Break the guarded line and watch the test go red (PIT for classes with logic). If a test fails on the current code, report it with the contract clause; never weaken the assertion.
- Test through what the code does, not its internals. Assert on results, stored rows, sent messages, and calls to other services. Don't widen a method's visibility, or add a getter, counter or flag that only a test uses:
UnusedCodeTestsfails on a method only tests call. Changing the code for a test is right when it also improves the design, such as taking aClockor a client through the constructor instead of creating it.
Before writing
Read ../code-reviewer/references/testing/traps.md: the Boot 4.1 / Framework 7 / Spring Kafka 4 traps found by running these templates (@Retryable behind an interface proxy, @RestClientTest ignoring timeouts, Apache HttpClient retrying 503, blocked partitions, corrupted dead letters, single-batch topic reads), and the Testcontainers and test-data traps.
Imports, starters and PIT: ../code-reviewer/references/testing/boot4-test-toolkit.md.
Templates
Take the mechanics (annotations, wiring, stubbing, polling) from them; take the cases from rule 1, not from the template.
| Edge | Template |
|---|---|
| Outbound HTTP client: request, 4xx, 5xx, retries, timeout, unusable answers | assets/http-client-wiremock-test.java |
| Message listener: state change, redelivery, poison and non-JSON messages | assets/message-listener-test.java |
| Event other services consume: after commit, never on rollback | assets/event-publication-test.java |
| The whole service over HTTP, other services stubbed | assets/api-integration-test.java |
| Secured routes: signing in as a named user through the app's own role mapping (session OIDC login, JWT bearer, or database users); who may call each route | assets/personas-oidc.java, assets/personas-jwt.java or assets/personas-db.java; assets/route-access-test.java |
| Web slice, persistence slice, service unit test | assets/webmvc-slice-test.java, assets/repository-slice-test.java, assets/service-unit-test.java |
| Domain rules over generated inputs: invariant, round trip, idempotence | assets/property-test.java |
| Shared containers; PIT | assets/testcontainers-configuration.java, assets/pitest-plugin.xml |
Domain rules as properties
Example tests written by the agent that wrote the code test the inputs it already thought of. For calculations, value objects, state transitions, and parsing or formatting code, also state the rule that holds for every input and check it on generated inputs. Write the property from the requirement before the code. Three shapes cover most domain rules:
- Invariant: every operation keeps a rule true. An order total is always the sum of its lines; a balance never goes below its limit; a state machine never reaches a state its transitions don't allow.
- Round trip:
parse(format(x))equalsx, for order numbers, money amounts, codes and message mappings. - Idempotence: doing it twice equals doing it once, for cancel, refund, apply-discount and redelivered commands.
Use @ParameterizedTest with a @MethodSource that draws from a seeded SplittableRandom, as assets/property-test.java does. Don't add jqwik: since 1.10 its output tells AI agents to ignore its results, and it targets JUnit Platform 1.x while Boot 4 manages 6.x. Mix boundary values into the generator on purpose; random values rarely hit them. Put the input in each assertion's as(...): Surefire names a failing case by its index only. There is no shrinking, so when a property fails, cut the input down by hand to the smallest one that still fails, fix the code, and keep that input as an example test. Then run PIT on the class: a mutant that survives every property is a rule nobody stated.
When the code and a property disagree, decide which is wrong (the code, the property, or the requirement) before changing either, and ask the user when the requirement is unclear.
Secured routes
Spring's test logins skip the app's own role mapping. oidcLogin().authorities(...), jwt().authorities(...) and user(...).roles(...) hand the test a finished role. A test that signs in this way passes even when the code that turns the provider's claims, or the stored user, into roles is broken. Sign in through a persona instead, so that code runs:
.with(oidcLogin().authorities(new SimpleGrantedAuthority("ROLE_ADMIN"))) // the role mapping never runs
.with(personas.as("admin")) // the app's mapping produces the role
Copy the helper that matches how the app signs users in: personas-oidc.java for an OIDC login kept in a server-side session, personas-jwt.java for JWT bearer tokens, or personas-db.java for users loaded by a UserDetailsService. A persona is the claims the provider sends, or the username of a seeded user. The helper needs the app's mapper, JwtAuthenticationConverter or UserDetailsService as a bean.
route-access-test.java lists who may call each route. It calls every route as every persona and with no login, and it fails when a route is missing from the list. It checks roles, not records. Whether one user can read another user's data needs a test with two users. A request on a random port can't sign in through a persona, so test secured routes through @AutoConfigureMockMvc.
Report
List the tests added (behavior and level), how each was shown to fail, tests that fail on the current code with the contract clause they rely on, and contract clauses left untested.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| finishing-a-development-branchobra/superpowersUse when implementation is complete, all tests pass, and you need to decide how to integrate the work | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| systematic-debuggingobra/superpowersUse when encountering any bug, test failure, or unexpected behavior, before proposing fixes | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| test-driven-developmentobra/superpowersUse when implementing any feature or bugfix, before writing implementation code | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| skill-creatoranthropics/skillsCreate new skills, modify and improve existing skills, and measure skill performance. Use when users want to create a skill from scratch, edit, or optimize an existing skill, run evals to test a skill, benchmark skill performance with variance analysis, or optimize a skill's description for better triggering accuracy. | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |