Endpoint Testing & Assertions

@WithMockUser fabricates a simple principal from annotation attributes. @WithUserDetails loads a real principal via your UserDetailsService bean by username, so the principal is your actual UserDetails type. @WithSecurityContext is the extensible base that lets you build a fully custom SecurityContext/Authentication via a factory.

expectBody(Class) decodes one object; expectBodyList(Class) decodes an array to a List; expectBody() (untyped) gives jsonPath/json(...) assertions on raw JSON; returnResult(Class) exits the fluent chain to get the decoded body (a Flux for streaming) for custom assertions.

andReturn() gives you the MvcResult for custom assertions on the raw response. For async endpoints (returning DeferredResult/Callable/CompletableFuture), first andExpect(request().asyncStarted()), then re-dispatch with asyncDispatch(mvcResult). MockMvc's key limit: it runs the DispatcherServlet in-memory, not a real HTTP server.

Centralize preprocessors and URI config as defaults, extract reusable snippet/descriptor helpers, drive validation docs from Bean Validation via ConstraintDescriptions, and use snippet templates for consistency. The tradeoff: docs require and depend on maintained tests, and drift breaks the build (intentionally).

The 403 comes from missing CSRF tokens on mutating requests — @WithMockUser authenticates but doesn't add one; they must use .with(csrf()). The false-passing test likely tests without wiring Spring Security into MockMvc (no apply(springSecurity())) or a @WebMvcTest with mocked/absent filter chain, so security isn't actually enforced.

Use TestRestTemplate for blocking, real-HTTP integration tests in a classic MVC app — simple, imperative, RestTemplate-style API. Use WebTestClient for its fluent assertion DSL, for reactive/WebFlux apps, or when you want one client that can bind to a live server, MockMvc, or controllers. MockMvc tests the MVC stack without a real socket.

JsonPath maps small JSON integers to Integer and decimals to Double, so .value(1L) fails against 1. exists/doesNotExist test key presence; isEmpty/isNotEmpty test whether a present value is null/empty vs populated. A present-but-null field exists AND isEmpty.

The request builder is an AssertJ AssertProvider, so the request only runs when you call assertThat(...) or .exchange(). Adopt MockMvcTester for readable AssertJ servlet-slice tests; keep classic MockMvc where it's already entrenched; use WebTestClient for real-HTTP/WebFlux or full-stack tests.

Build a shared MockMvc via a base class or MockMvcBuilderCustomizer: apply(springSecurity()) for security plus alwaysDo(log()) for uniform, DEBUG-gated diagnostics. Keep global alwaysExpect minimal and add custom ResultHandlers only for cross-cutting captures.

Use fast mock-server tests (bindToController/context, webEnvironment MOCK) for most controller coverage; reserve slower running-server tests (RANDOM_PORT) for transport, filter-ordering, and true end-to-end concerns. Watch response timeouts, hidden config gaps, and security-context wiring.