Skip to content
Skills Library
Programming · Testing

spring-testing-web

/spring-testing-web

HTTP-level tests for Spring Boot web apps with MockMvcTester, RestTestClient or WebTestClient - requests, JSON assertions, stubbing collaborators, full-server RANDOM_PORT tests. Use when testing controllers, REST/JSON endpoints, error handling and status codes, or WebFlux handlers.

Licence
Apache-2.0
Last repository change
29.10.2026

Assessment and security

100/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
2
Scripts
0
HTML comments
0
URLs in SKILL.md
2
Deprecation

No signals detected. Repository changed on 29.10.2026, without references to retired models or APIs.

Licence

Apache-2.0, otwarta: można używać i zmieniać, z zachowaniem licencji i informacji o zmianach.

What it does and when to use it

HTTP-level tests for Spring Boot web apps with MockMvcTester, RestTestClient or WebTestClient - requests, JSON assertions, stubbing collaborators, full-server RANDOM_PORT tests. Use when testing controllers, REST/JSON endpoints, error handling and status codes, or WebFlux handlers.

Original author description

HTTP-level tests for Spring Boot web apps with MockMvcTester, RestTestClient or WebTestClient - requests, JSON assertions, stubbing collaborators, full-server RANDOM_PORT tests. Use when testing controllers, REST/JSON endpoints, error handling and status codes, or WebFlux handlers.

How it works

  1. Steps: writing a web test class
  2. MockMvcTester reference
  3. Web slice: @WebMvcTest
  4. What the mock MVC stack does not run
  5. Full-server tests
Original SKILL.md headings · 131 lines, 890 words
SKILL.md preview
---
name: spring-testing-web
description: HTTP-level tests for Spring Boot web apps with MockMvcTester, RestTestClient or WebTestClient - requests, JSON assertions, stubbing collaborators, full-server RANDOM_PORT tests. Use when testing controllers, REST/JSON endpoints, error handling and status codes, or WebFlux handlers.
---

# Testing Spring web applications

Default stack (Spring Boot 4 / Spring Framework 7, Spring MVC): `@SpringBootTest` + `@AutoConfigureMockMvc` + `MockMvcTester` with AssertJ. The test dependency is `org.springframework.boot:spring-boot-starter-webmvc-test`, in `test` scope.

```java
import org.springframework.boot.test.context.SpringBootTest;
import org.springframework.boot.webmvc.test.autoconfigure.AutoConfigureMockMvc;
import org.springframework.test.context.bean.override.mockito.MockitoBean;
import org.springframework.test.web.servlet.assertj.MockMvcTester;
import static org.assertj.core.api.Assertions.assertThat;
```

Other cases:

- **WebFlux apps**, legacy `MockMvc` / `TestRestTemplate`, or `WebTestClient` / `RestTestClient` style: read [other-clients.md](other-clients.md).
- **HTML structure, forms, clicks, JavaScript**: load `spring-testing-browser`.
- **Secured endpoints** (401/403, CSRF, fake users): load `spring-testing-security` alongside this skill.

## Steps: writing a web test class

1. **Start from the suite's shared test annotation** if one exists, otherwise `@SpringBootTest @AutoConfigureMockMvc`. Any extra per-class configuration costs a new context; load `spring-testing-fast` first.
2. **Stub external systems.** `@MockitoBean` the beans that reach outside the app (third-party APIs, remote services). Give them default answers in `@BeforeEach`, and override per test where the scenario needs it.
3. **Reset state** in `@BeforeEach` (`repository.deleteAll()`), because the context and its data are shared across test classes.
4. **Add domain helpers** for repeated arrange steps (`selectCity("Paris")`), so each test reads as intent.
5. **Write each test as arrange / act / assert.** Keep the exchange result in a `response` variable, then assert.
6. **Cover the error paths**, not just the happy path: validation failures (400), not found (404), conflicts (409), and whatever `@ExceptionHandler` / `@ControllerAdvice` maps. Use `doThrow(...).when(mock).method(...)` for `void` methods.

Done when every endpoint you touched has at least its success status, its body contract and each mapped error status asserted.

```java
@SpringBootTest
@AutoConfigureMockMvc
class WeatherApiTests {

    @Autowired MockMvcTester mvc;
    @Autowired SelectionRepository selectionRepository;
    @MockitoBean WeatherService weatherService;

    @BeforeEach
    void setUp() {
        selectionRepository.deleteAll();
        when(weatherService.getCurrentWeather(anyDouble(), anyDouble()))
            .thenReturn(new WeatherData(20, 0, 0));
    }

    @Test
    void getWeather() {
        var paris = selectCity("Paris");

        var response = mvc.get().uri("/api/weather").exchange();

        assertThat(response)
            .hasStatus(HttpStatus.OK)
            .bodyJson()
            .isLenientlyEqualTo("""
                [ { "cityName": "Paris", "country": "France", "temperature": 20.0 } ]
                """)
            .extractingPath("$.[0].cityId").isEqualTo(paris.getId());
    }
}
```

## MockMvcTester reference

**Requests**: `mvc.get() | post() | put() | delete()`, then:

- `.uri("/api/city/{id}", id)`: always a path, never a host or port. There is no server.
- `.queryParam(k, v)`, `.header(k, v)`, `.cookie(c)`, `.accept(type)`, `.apiVersion(v)`.
- `.formField(name, value)` submits an HTML form.
- `.content(stringOrBytes)` sends the body as-is: also set `.contentType(MediaType.APPLICATION_JSON)`.
- `.with(postProcessor)` applies a `RequestPostProcessor`. Wrap headers or cookies repeated on many requests in one, for example `private static RequestPostProcessor apiUser(String name) { return request -> { request.addHeader(...); request.setCookies(...); return request; }; }`.
- `.exchange()` performs the request. `.exchange().assertThat()…` chains straight into assertions.

**Assertions** on `assertThat(response)`:

- Status and headers: `.hasStatus(HttpStatus.CREATED)`, `.hasStatus2xxSuccessful()`, `.hasRedirectedUrl("/login")`, `.hasErrorMessage(...)`, `.body().isEmpty()`.
- `.bodyText().contains(...)`: fine for a sanity check on HTML; for structure, load `spring-testing-browser`. On failure it prints the whole page.
- JSON:
  - `.bodyJson().isLenientlyEqualTo(json)` ignores property order and properties missing from the expected document. Prefer it: assert the stable fields, skip generated ids.
  - `.bodyJson().isEqualTo(json)` is strict.
  - `.bodyJson().extractingPath("$.[0].cityId").isEqualTo(id)` checks a JsonPath; `extractingPath("$.[*].name").asArray().containsOnly(...)`, `extractingPath("$.length()")`.
  - `.bodyJson().convertTo(InstanceOfAssertFactories.list(WeatherResponse.class))` converts through the app's message converters, so you can use regular AssertJ on objects. Declare a test record with `@JsonIgnoreProperties(ignoreUnknown = true)` holding only the fields you check.
- Ignore specific values in a strict comparison: `.bodyJson().isEqualTo(expected, JsonAssert.comparator(new CustomComparator(JSONCompareMode.LENIENT, new Customization("[*].cityId", (a, e) -> true))))`.
- `MockMvcTester` deserializes JSON only. For XML or other formats, read `response.getResponse().getContentAsByteArray()` and parse it yourself.

## Web slice: `@WebMvcTest`

Only for a large, slow-starting app where you want a fast loop on the web layer; otherwise use the shared `@SpringBootTest` (load `spring-testing-strategy` for the trade-off).

- `@WebMvcTest(controllers = { A.class, B.class })` (`org.springframework.boot.webmvc.test.autoconfigure`) loads those controllers, `@ControllerAdvice`, converters, filters and other web components, and auto-configures `MockMvcTester`. Services and repositories are not loaded.
- Provide the controllers' dependencies with `@MockitoBean`.
- Group related controllers that share dependencies in one slice. A slice per controller is one context per controller, which thrashes the cache.
- A slice doesn't load your `SecurityFilterChain`: import it (load `spring-testing-security`).
- Everything else in this skill (requests, assertions, the mock MVC limits below) applies unchanged.

## What the mock MVC stack does not run

`webEnvironment = MOCK` (the default) calls the `DispatcherServlet` directly from the test thread. No servlet container starts. Consequences:

- **No container features**: error pages (`/error/404.html` comes back with an empty body), container-managed sessions, Tomcat valves. Spring's own error message is still available through `.hasErrorMessage(...)`.
- **Controllers run on the test thread**: thread-locals such as the `SecurityContext` or a test-level `@Transactional` reach the controller.
- **Requires Spring MVC**: WebFlux apps use `WebTestClient` (see [other-clients.md](other-clients.md)).

## Full-server tests

When you need what the container does, start the real server on a random port:

```java
@SpringBootTest(webEnvironment = SpringBootTest.WebEnvironment.RANDOM_PORT)
@AutoConfigureRestTestClient // org.springframework.boot.resttestclient.autoconfigure
class ErrorPageTests {

    @Autowired RestTestClient client; // base URL preset to the running server

    @Test
    void displaysCustom404Page() {
        var spec = client.get().uri("/does-not-exist").accept(MediaType.TEXT_HTML).exchange();
        var response = RestTestClientResponse.from(spec); // AssertJ bridge

        assertThat(response).hasStatus(HttpStatus.NOT_FOUND)
            .bodyText().containsIgnoringCase("404 NOT FOUND");
    }
}
```

- Use `RANDOM_PORT`. `DEFINED_PORT` collides with other processes and with other test contexts, so use it only when the port must be known before startup.
- `@LocalServerPort int port` gives the port to clients you build yourself, such as `RestClient.builder().baseUrl("http://localhost:" + port)`.
- **Debugging**: put a breakpoint in the test, read `port`, and open `http://localhost:<port>` in a browser to see the app with the test's data. In IntelliJ IDEA, set the breakpoint to suspend only the test thread (right-click › Suspend › Thread), otherwise the server is frozen too.
- Each `webEnvironment` value is a separate cached context: keep full-server tests to the ones that need the container.
Files in this package (2)
  • SKILL.md 8 KB
  • other-clients.md 3 KB

Versions

The database has no other skills named spring-testing-web.

Database snapshot: 13.11.2026 · package version 064cf3e82605 (SHA-256 digest of the entire package)

Downloads in the last 30 days: 0 · ranking

Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.

Similar skills

  • 100java-spring-boot-testing
    Complete guide to testing in Spring Boot — unit tests with Mockito, controller tests (MockMVC standalone, @WebMvcTest, MockMvcTester, @SpringBootTest, WebTestClient), JPA repository tests, Testcontainers, Spring Cloud Contract, and stress testing. Use when writing or reviewing any Spring Boot test.
  • 100spring-testing
    Write, repair, and modernise tests in an existing Spring Boot 4 project (Maven or Gradle) — Testcontainers 2.x, integration vs unit routing, and the Boot 4 test API (@MockitoBean, MockMvcTester, RestTestClient). Use when asked to add or fix tests, set up Testcontainers, or…
  • 100322-frameworks-spring-boot-testing-integration-tests
    Use when you need to write or improve integration tests — including Testcontainers with @ServiceConnection, @DataJdbcTest persistence slices, TestRestTemplate or MockMvcTester for HTTP, data isolation, and container lifecycle management for Spring Boot 4.0.x. This should trigger…
  • 100spring-boot-web-api
    Spring Boot 4 REST API implementation patterns. Use when creating REST controllers, REST endpoints, request validation, exception handlers with ProblemDetail (RFC 9457), API versioning, content negotiation, WebFlux reactive endpoints, HTTP clients with @HttpExchange, JSON…
  • 100spring-boot-engineer
    Generates Spring Boot 3.x configurations, creates REST controllers, implements Spring Security 6 authentication flows, sets up Spring Data JPA repositories, and configures reactive WebFlux endpoints. Use when building Spring Boot 3.x applications, microservices, or reactive Java…
  • 100spring-boot-testing
    Write unit, integration, and slice tests for Spring Boot 3 applications. Use when writing unit tests, integration tests, or slice tests for Spring Boot 3 applications.

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.