jwt-auth-demo/docs/08-testing.md

08 — Testing

← edge cases · next: manual filter vs resource server →

The Boot 4 test-slice split

On Spring Boot 3, spring-boot-starter-test alone gave you @AutoConfigureMockMvc. On Boot 4 it does not — the test slices were moved into their own modules:

<dependency>
  <groupId>org.springframework.boot</groupId>
  <artifactId>spring-boot-starter-webmvc-test</artifactId>
  <scope>test</scope>
</dependency>
<dependency>
  <groupId>org.springframework.boot</groupId>
  <artifactId>spring-boot-starter-security-test</artifactId>
  <scope>test</scope>
</dependency>

The package moved with it:

// Boot 3
import org.springframework.boot.test.autoconfigure.web.servlet.AutoConfigureMockMvc;
// Boot 4
import org.springframework.boot.webmvc.test.autoconfigure.AutoConfigureMockMvc;

The compiler error is package org.springframework.boot.test.autoconfigure.web.servlet does not exist, which reads like a corrupt dependency rather than a relocation.

What is worth pinning

13 tests, all passing — test-run.txt. The valuable ones assert things that are easy to break without noticing.

The status-code contract. Not "it works" but which failure code:

@Test
void missingTokenIs401NotA403() throws Exception {
    this.mvc.perform(get("/api/me"))
            .andExpect(status().isUnauthorized())
            .andExpect(header().string("WWW-Authenticate", containsString("Bearer")));
}

@Test
void validTokenWithoutTheRoleIs403NotA401() throws Exception {
    String token = login("alice", "alice-password").get("accessToken");
    this.mvc.perform(get("/api/admin/stats").header("Authorization", "Bearer " + token))
            .andExpect(status().isForbidden())
            .andExpect(header().string("WWW-Authenticate", containsString("insufficient_scope")));
}

Non-disclosure. A byte comparison, because a helpful message is a regression:

@Test
void lockedAccountIsIndistinguishableFromABadPassword() throws Exception {
    // ... both requests ...
    assertThat(locked.getResponse().getContentAsString())
            .isEqualTo(wrong.getResponse().getContentAsString());
}

Filter order. Ordering is configuration, and configuration drifts:

@Test
void csrfFilterRunsLongBeforeAuthorizationFilter() {
    List<String> filters = this.filterChainProxy.getFilterChains().getFirst()
            .getFilters().stream().map(f -> f.getClass().getSimpleName()).toList();

    assertThat(filters.indexOf("AuthorizationFilter")).isEqualTo(filters.size() - 1);
    assertThat(filters.indexOf("CsrfFilter")).isLessThan(filters.indexOf("AuthorizationFilter"));
}

Revocation and replay, because both are easy to regress into no-ops.

The .with(csrf()) trap

spring-security-test provides a post-processor that attaches a valid CSRF token:

this.mvc.perform(post("/api/auth/login").with(csrf()) ... )

Convenient, and it will make a test pass against a configuration that 403s in production. CsrfBreaksPermitAllTests deliberately has both tests: one asserting the 403 without csrf(), one asserting the 200 with it. If you only ever write the second, you have tested your test.

@WithMockUser tests authorization, not authentication

@Test
@WithMockUser(roles = "ADMIN")
void adminCanSeeStats() { ... }

This installs an Authentication directly into the context and bypasses the entire filter chain — decoder, validators, token_type check, denylist. It is the right tool for testing @PreAuthorize rules and the wrong tool for testing that your JWT pipeline works. Every test in AuthenticationFlowTests goes through a real POST /api/auth/login and a real Authorization header for that reason.

spring-security-test also offers SecurityMockMvcRequestPostProcessors.jwt(), which constructs a Jwt without signing it. Same caveat: good for authorization rules, blind to decoder configuration.

Testing expiry

A token with a 2-second TTL is not expired 5 seconds later — JwtTimestampValidator allows 60 seconds of clock skew (doc 07 §3). A test that sleeps past exp and asserts 401 either sleeps 61 seconds or is flaky.

Two better options: build the JwtDecoder under test with a small skew (new JwtTimestampValidator(Duration.ZERO)), or inject a fixed Clock and issue a token already in the past.

Integration testing against the real server

jwt-authentication/scripts/curl-transcript.sh is the integration test that MockMvc cannot be — it exercises a real Tomcat, a real HTTP client, real header parsing, and real base64url. Several findings in these docs (the resource_metadata parameter, the FACTOR_BEARER authority, the bare WWW-Authenticate on a wrapped JwtException) came from that script, not from the test suite.