Spring Boot Course · Lesson 11

Testing the Web Layer

Lesson 10's tests prove the service makes the right decisions. They say nothing about what a client actually receives: the URL that routes to a method, the UUID parsed from the path, @Valid rejecting a bad body, the JSON shape, the 201 and its Location header, the ProblemDetail for a 404. All of that is Spring MVC's work, wrapped around controller methods that are mostly one line long. This lesson tests that layer the way a client sees it — HTTP request in, HTTP response out — with the service mocked, no database, and no server.

The win

Twenty-two tests that pin down the API's contract: BookControllerTest covers every book endpoint, success and failure — the JSON body, 201 with Location, 204, the 400 field-error map, the 404 problem, a malformed id, and the Pageable the list endpoint hands the service — and AuthorControllerTest does the same for every author endpoint, plus the Lesson 7 409. You'll use a test slice (@WebMvcTest), a mocked bean (@MockitoBean), and MockMvcTester, which sends requests through Spring MVC and asserts on the responses in AssertJ style — all with no database running.

What the service tests can't see

Look at BookController.byId: one line, return BookResponse.from(books.getById(id));. Calling it directly from a test, controller.byId(id), would prove almost nothing, because nearly everything the client experiences happens around that line:

GET /api/books/{id} has to route to this method, and the {id} text has to convert to a UUID — or fail as a 400.
The returned record has to serialize to the JSON the client expects, with the authors in name order (Lesson 6).
A NotFoundException from the service has to become a 404 application/problem+json body, through ApiExceptionHandler (Lesson 7).
On POST, @Valid has to reject a bad body before the method runs, and the success has to come back as 201 with a Location header.

To test that, Spring MVC has to be running — but not the whole application. A @WebMvcTest starts only the web layer, for the one controller under test, and the service it calls is a Mockito mock. That is a test slice: the middle of the Lesson 10 pyramid. It loads @Controller and @ControllerAdvice beans, converters, filters and Spring MVC's configuration, and leaves out ordinary @Components ^[docs] — so no repositories, no JPA, no DataSeeder, no database. ApiExceptionHandler is a @RestControllerAdvice, so it is in the slice, and the error bodies are tested for real.

Nothing to add to pom.xml: spring-boot-starter-webmvc-test, which spring init put there in Lesson 1, brings @WebMvcTest along with JUnit, Mockito and AssertJ.

Step 1 — The test class and a first request

The test lives next to the controller it covers, in src/test/java/com/example/library/book/. Here is the class with its first test, GET /api/books/{id} for a book that exists:

1
package com.example.library.book;
2

3
import java.util.Set;
4
import com.example.library.author.Author;
5
import org.junit.jupiter.api.DisplayName;
6
import org.junit.jupiter.api.Test;
7
import org.springframework.beans.factory.annotation.Autowired;
8
import org.springframework.boot.webmvc.test.autoconfigure.WebMvcTest;
9
import org.springframework.http.MediaType;
10
import org.springframework.test.context.bean.override.mockito.MockitoBean;
11
import org.springframework.test.web.servlet.assertj.MockMvcTester;
12

13
import static org.assertj.core.api.Assertions.assertThat;
14
import static org.mockito.Mockito.when;
15

16
@WebMvcTest(BookController.class)                // only the web layer, and only this controller
17
class BookControllerTest {
18

19
    @Autowired MockMvcTester mvc;                // sends requests through Spring MVC, no server
20
    @MockitoBean BookService books;              // a Mockito mock, registered as the BookService bean
21

22
    Author hunt = new Author("Andrew Hunt");
23
    Author thomas = new Author("David Thomas");
24
    Book book = new Book("The Pragmatic Programmer", 1999, Set.of(thomas, hunt));
25

26
    @Test
27
    @DisplayName("GET /api/books/{id} returns the book as JSON, authors sorted by name")
28
    void byId_found() {
29
        when(books.getById(book.getId())).thenReturn(book);
30

31
        assertThat(mvc.get().uri("/api/books/{id}", book.getId()))
32
            .hasStatusOk()
33
            .hasContentType(MediaType.APPLICATION_JSON)
34
            .bodyJson()                                  // strict: every field, nothing extra, arrays in order
35
            .isStrictlyEqualTo("""
36
                {
37
                  "id": "%s",
38
                  "title": "The Pragmatic Programmer",
39
                  "year": 1999,
40
                  "authors": [
41
                    { "id": "%s", "name": "Andrew Hunt" },
42
                    { "id": "%s", "name": "David Thomas" }
43
                  ]
44
                }
45
                """.formatted(book.getId(), hunt.getId(), thomas.getId()));
46
    }
47
}

Read it top-down:

@WebMvcTest(BookController.class) builds the slice for this one controller. Without the argument it would load every controller, and each one's service would need a mock.
@MockitoBean BookService books is the Spring counterpart of Lesson 10's @Mock. There, the test built the service itself and handed it the mocks with new. Here Spring builds BookController, and it takes the constructor argument from the application context — so that's where the mock has to be. @MockitoBean creates a Mockito mock of BookService and registers it in the context as the BookService bean, replacing the real one if the context has one and creating it if not ^[docs] (the slice doesn't load @Service beans, so here it's created). Spring then injects it into the controller. The object is the same kind of mock as @Mock: unstubbed methods return defaults — null for a Book or a Page — when(...) scripts it, and verify(...) interrogates it. Spring resets it after each test method ^[docs], clearing its stubs and recorded calls, so no test sees another's.
@Autowired MockMvcTester mvc is the client. mvc.get().uri(...) builds a request; wrapping it in assertThat(...) sends it through Spring MVC's DispatcherServlet — the same routing, conversion, validation and exception handling as the real app — and gives back a response to assert on ^[docs]. No port is opened; the request and response are in-memory objects.
The fields hunt, thomas and book are fixtures. JUnit creates a new instance of the test class for every test method, so each test gets fresh objects with fresh UUIDv7 ids, and no test can disturb another's data.

The book is built with its authors in the "wrong" order, Set.of(thomas, hunt) — and a Set has no order anyway. The expected JSON lists Hunt before Thomas, so this test also proves BookResponse.from sorts the authors by name.

`@Mock` or `@MockitoBean`?

Both annotations make the same kind of Mockito mock. They differ in where the mock ends up, and that depends on one question: who calls the constructor of the class under test?

	`@Mock`	`@MockitoBean`
Who builds the class under test	the test, with `new BookService(books, authors)`	Spring, when it starts the test's context
Where the mock goes	into the constructor call you write	into the application context, as a bean Spring injects
What sets it up	`@ExtendWith(MockitoExtension.class)`	a Spring test annotation, here `@WebMvcTest`
Spring context	none — the test runs in milliseconds	one is started — the test costs seconds
In this course	`BookServiceTest`, `AuthorServiceTest`	`BookControllerTest`, `AuthorControllerTest`

So: if you can build the class yourself and that tests what you want, use @Mock — it's the cheaper test. Use @MockitoBean only when the test needs Spring to build the class, because the behaviour under test lives in Spring. That is exactly the controller's case. You could write new BookController(mockService) and call byId(id) directly, but then no routing, no @Valid, no JSON and no ApiExceptionHandler would run — the very things this lesson tests. Spring has to build the controller, so its service has to be a bean.

Mixing them up fails at once, in different ways:

@Mock in a @WebMvcTest: nothing puts the mock into the context, so Spring can't build the controller. The test fails before it starts: Failed to load ApplicationContext … No qualifying bean of type 'com.example.library.book.BookService' available.
@MockitoBean in a plain Mockito test: no Spring context is started, so nothing reads the annotation and the field stays null. new BookService(books, authors) gets nulls, and the first call fails with NullPointerException: Cannot invoke "com.example.library.book.BookRepository.findById(java.util.UUID)" because "this.books" is null.

Why MockMvcTester, and what MockMvc looks like

The course asserts web responses with MockMvcTester, which Spring Framework 6.2 added on top of MockMvc. @WebMvcTest auto-configures it whenever AssertJ is on the classpath ^[docs], so the controller tests read like Lesson 10's: assertThat(...) and a fluent chain. Much existing code uses the older API on MockMvc itself, and you will meet it. The same test looks like this there:

1
mockMvc.perform(get("/api/books/{id}", book.getId()))
2
    .andExpect(status().isOk())
3
    .andExpect(jsonPath("$.title").value("The Pragmatic Programmer"));

Same engine, same request — perform sends it, and each andExpect takes a Hamcrest-style matcher from a static import. Reading one style is enough to read the other.

@MockitoBean, not @MockBean

In code written for Spring Boot 3 you'll see @MockBean doing this job. Spring Boot 4.0 removed it in favour of Spring Framework's @MockitoBean ^[docs], so on this project's Spring Boot it doesn't exist.

The whole body, compared strictly

bodyJson().isStrictlyEqualTo(...) compares the response with the expected JSON in strict mode: every value must match, a field the expected JSON doesn't list fails the test, and arrays must come in the same order ^[docs].

Every test in this lesson writes out the whole response body and compares it strictly, so reading a test shows exactly what the client receives — every field, nothing left to guess. It is also how the test catches the changes a client would notice: a field added to BookResponse — say, an internal flag that should never leave the server — fails here, and so do authors out of name order.

You'll meet two looser checks in other code. isLenientlyEqualTo(...) lets unlisted fields through and ignores array order; extractingPath("$.title") checks one value, picked out with a JSONPath expression ($ is the document root). Both leave part of the response unwritten: the test no longer shows it, and a change there passes unnoticed. They are for a value a test can't know in advance, such as a timestamp or an id the server generates. These responses have none: the ids come from the fixtures, and everything else is fixed.

Step 2 — Errors are part of the contract

A client gets error responses as often as successes, and Lesson 7 made them a deliberate format. Two tests: a missing book, and an id that isn't a UUID at all.


3 collapsed lines
1
package com.example.library.book;
2

3
import java.util.Set;
4
import java.util.UUID;
5
import com.example.library.author.Author;
6
import com.example.library.error.NotFoundException;
4 collapsed lines
7
import org.junit.jupiter.api.DisplayName;
8
import org.junit.jupiter.api.Test;
9
import org.springframework.beans.factory.annotation.Autowired;
10
import org.springframework.boot.webmvc.test.autoconfigure.WebMvcTest;
11
import org.springframework.http.HttpStatus;
5 collapsed lines
12
import org.springframework.http.MediaType;
13
import org.springframework.test.context.bean.override.mockito.MockitoBean;
14
import org.springframework.test.web.servlet.assertj.MockMvcTester;
15

16
import static org.assertj.core.api.Assertions.assertThat;
17
import static org.mockito.Mockito.verifyNoInteractions;
34 collapsed lines
18
import static org.mockito.Mockito.when;
19

20
@WebMvcTest(BookController.class)                // only the web layer, and only this controller
21
class BookControllerTest {
22

23
    @Autowired MockMvcTester mvc;                // sends requests through Spring MVC, no server
24
    @MockitoBean BookService books;              // a Mockito mock, registered as the BookService bean
25

26
    Author hunt = new Author("Andrew Hunt");
27
    Author thomas = new Author("David Thomas");
28
    Book book = new Book("The Pragmatic Programmer", 1999, Set.of(thomas, hunt));
29

30
    @Test
31
    @DisplayName("GET /api/books/{id} returns the book as JSON, authors sorted by name")
32
    void byId_found() {
33
        when(books.getById(book.getId())).thenReturn(book);
34

35
        assertThat(mvc.get().uri("/api/books/{id}", book.getId()))
36
            .hasStatusOk()
37
            .hasContentType(MediaType.APPLICATION_JSON)
38
            .bodyJson()                                  // strict: every field, nothing extra, arrays in order
39
            .isStrictlyEqualTo("""
40
                {
41
                  "id": "%s",
42
                  "title": "The Pragmatic Programmer",
43
                  "year": 1999,
44
                  "authors": [
45
                    { "id": "%s", "name": "Andrew Hunt" },
46
                    { "id": "%s", "name": "David Thomas" }
47
                  ]
48
                }
49
                """.formatted(book.getId(), hunt.getId(), thomas.getId()));
50
    }
51

52
    @Test
53
    @DisplayName("GET /api/books/{id} for a missing book is a 404 problem")
54
    void byId_missing() {
55
        UUID id = UUID.randomUUID();
56
        when(books.getById(id)).thenThrow(new NotFoundException("No book with id " + id));
57

58
        assertThat(mvc.get().uri("/api/books/{id}", id))
59
            .hasStatus(HttpStatus.NOT_FOUND)
60
            .hasContentType(MediaType.APPLICATION_PROBLEM_JSON)
61
            .bodyJson()
62
            .isStrictlyEqualTo("""
63
                {
64
                  "status": 404,
65
                  "title": "Resource not found",
66
                  "detail": "No book with id %s",
67
                  "instance": "/api/books/%s"
68
                }
69
                """.formatted(id, id));
70
    }
71

72
    @Test
73
    @DisplayName("GET /api/books/{id} with a malformed id is a 400 and never reaches the service")
74
    void byId_malformedId() {
75
        assertThat(mvc.get().uri("/api/books/{id}", "not-a-uuid"))
76
            .hasStatus(HttpStatus.BAD_REQUEST)
77
            .hasContentType(MediaType.APPLICATION_PROBLEM_JSON)
78
            .bodyJson()
79
            .isStrictlyEqualTo("""
80
                {
81
                  "status": 400,
82
                  "title": "Bad Request",
83
                  "detail": "Failed to convert 'id' with value: 'not-a-uuid'",
84
                  "instance": "/api/books/not-a-uuid"
85
                }
86
                """);
87

88
        verifyNoInteractions(books);                     // the request never got past Spring MVC
89
    }
90
}

byId_missing scripts the mock to throw: thenThrow is thenReturn's twin for exceptions. The service's real "no such book" logic was proven in Lesson 10; this test proves what the web layer does with the exception — ApiExceptionHandler turns it into a 404 with the application/problem+json media type, the title Resource not found, and the exception's message as the detail. That's where Lesson 10 said the exact wording belongs in a test: here it is the contract, the text the client reads.

The body has one field the handler doesn't set: instance, which Spring fills in with the request path. The client receives it, so the test lists it too.

byId_malformedId stubs nothing. not-a-uuid can't convert to a UUID, so Spring MVC answers 400 before byId is ever called — the ResponseEntityExceptionHandler that ApiExceptionHandler extends turns the conversion failure into a problem body titled Bad Request, with a detail naming the parameter and the value. That wording is Spring's, not ours, but it is what the client reads: if a Spring upgrade ever rewords it, this test fails and tells you the API's response changed. Then verifyNoInteractions(books) asserts the mock received no calls at all: the bad request was stopped at the door.

Step 3 — The list endpoint: page shape and the `Pageable`

GET /api/books does more in the controller than any other endpoint: @PageableDefault fills in page 0, size 20, sort by title; Lesson 8's Pageables.withIdTiebreaker appends id; and serialization-mode=via_dto decides the JSON shape. None of that is in the service, so none of it was tested yet.

1
package com.example.library.book;
2

3
import java.util.List;
6 collapsed lines
4
import java.util.Set;
5
import java.util.UUID;
6
import com.example.library.author.Author;
7
import com.example.library.error.NotFoundException;
8
import org.junit.jupiter.api.DisplayName;
9
import org.junit.jupiter.api.Test;
10
import org.mockito.ArgumentCaptor;
11
import org.springframework.beans.factory.annotation.Autowired;
12
import org.springframework.boot.webmvc.test.autoconfigure.WebMvcTest;
13
import org.springframework.data.domain.PageImpl;
14
import org.springframework.data.domain.PageRequest;
15
import org.springframework.data.domain.Pageable;
16
import org.springframework.data.domain.Sort;
6 collapsed lines
17
import org.springframework.http.HttpStatus;
18
import org.springframework.http.MediaType;
19
import org.springframework.test.context.bean.override.mockito.MockitoBean;
20
import org.springframework.test.web.servlet.assertj.MockMvcTester;
21

22
import static org.assertj.core.api.Assertions.assertThat;
23
import static org.mockito.ArgumentMatchers.any;
24
import static org.mockito.ArgumentMatchers.eq;
25
import static org.mockito.ArgumentMatchers.isNull;
26
import static org.mockito.Mockito.verify;
74 collapsed lines
27
import static org.mockito.Mockito.verifyNoInteractions;
28
import static org.mockito.Mockito.when;
29

30
@WebMvcTest(BookController.class)                // only the web layer, and only this controller
31
class BookControllerTest {
32

33
    @Autowired MockMvcTester mvc;                // sends requests through Spring MVC, no server
34
    @MockitoBean BookService books;              // a Mockito mock, registered as the BookService bean
35

36
    Author hunt = new Author("Andrew Hunt");
37
    Author thomas = new Author("David Thomas");
38
    Book book = new Book("The Pragmatic Programmer", 1999, Set.of(thomas, hunt));
39

40
    @Test
41
    @DisplayName("GET /api/books/{id} returns the book as JSON, authors sorted by name")
42
    void byId_found() {
43
        when(books.getById(book.getId())).thenReturn(book);
44

45
        assertThat(mvc.get().uri("/api/books/{id}", book.getId()))
46
            .hasStatusOk()
47
            .hasContentType(MediaType.APPLICATION_JSON)
48
            .bodyJson()                                  // strict: every field, nothing extra, arrays in order
49
            .isStrictlyEqualTo("""
50
                {
51
                  "id": "%s",
52
                  "title": "The Pragmatic Programmer",
53
                  "year": 1999,
54
                  "authors": [
55
                    { "id": "%s", "name": "Andrew Hunt" },
56
                    { "id": "%s", "name": "David Thomas" }
57
                  ]
58
                }
59
                """.formatted(book.getId(), hunt.getId(), thomas.getId()));
60
    }
61

62
    @Test
63
    @DisplayName("GET /api/books/{id} for a missing book is a 404 problem")
64
    void byId_missing() {
65
        UUID id = UUID.randomUUID();
66
        when(books.getById(id)).thenThrow(new NotFoundException("No book with id " + id));
67

68
        assertThat(mvc.get().uri("/api/books/{id}", id))
69
            .hasStatus(HttpStatus.NOT_FOUND)
70
            .hasContentType(MediaType.APPLICATION_PROBLEM_JSON)
71
            .bodyJson()
72
            .isStrictlyEqualTo("""
73
                {
74
                  "status": 404,
75
                  "title": "Resource not found",
76
                  "detail": "No book with id %s",
77
                  "instance": "/api/books/%s"
78
                }
79
                """.formatted(id, id));
80
    }
81

82
    @Test
83
    @DisplayName("GET /api/books/{id} with a malformed id is a 400 and never reaches the service")
84
    void byId_malformedId() {
85
        assertThat(mvc.get().uri("/api/books/{id}", "not-a-uuid"))
86
            .hasStatus(HttpStatus.BAD_REQUEST)
87
            .hasContentType(MediaType.APPLICATION_PROBLEM_JSON)
88
            .bodyJson()
89
            .isStrictlyEqualTo("""
90
                {
91
                  "status": 400,
92
                  "title": "Bad Request",
93
                  "detail": "Failed to convert 'id' with value: 'not-a-uuid'",
94
                  "instance": "/api/books/not-a-uuid"
95
                }
96
                """);
97

98
        verifyNoInteractions(books);                     // the request never got past Spring MVC
99
    }
100

101
    @Test
102
    @DisplayName("GET /api/books asks for page 0 of 20 by title then id, and returns the stable page shape")
103
    void all_defaults() {
104
        Pageable expected = PageRequest.of(0, 20, Sort.by("title", "id"));   // what the controller should ask for
105
        when(books.findAll(isNull(), any(Pageable.class)))                     // stub loosely: any page request...
106
            .thenReturn(new PageImpl<>(List.of(book), expected, 1));          // ...gets the page answering `expected`
107

108
        assertThat(mvc.get().uri("/api/books"))
109
            .hasStatusOk()
110
            .bodyJson()
111
            .isStrictlyEqualTo("""
112
                {
113
                  "content": [
114
                    {
115
                      "id": "%s",
116
                      "title": "The Pragmatic Programmer",
117
                      "year": 1999,
118
                      "authors": [
119
                        { "id": "%s", "name": "Andrew Hunt" },
120
                        { "id": "%s", "name": "David Thomas" }
121
                      ]
122
                    }
123
                  ],
124
                  "page": { "size": 20, "number": 0, "totalElements": 1, "totalPages": 1 }
125
                }
126
                """.formatted(book.getId(), hunt.getId(), thomas.getId()));
127

128
        ArgumentCaptor<Pageable> pageable = ArgumentCaptor.forClass(Pageable.class);
129
        verify(books).findAll(isNull(), pageable.capture());                  // ...verify exactly
130
        assertThat(pageable.getValue()).isEqualTo(expected);
131
    }
132

133
    @Test
134
    @DisplayName("GET /api/books passes the author filter and the client's sort, id still last")
135
    void all_filteredAndSorted() {
136
        UUID authorId = UUID.randomUUID();
137
        Pageable expected = PageRequest.of(1, 5, Sort.by(Sort.Order.desc("year"), Sort.Order.asc("id")));
138
        when(books.findAll(eq(authorId), any(Pageable.class)))
139
            .thenReturn(new PageImpl<>(List.of(), expected, 1));              // one match: page 1 is past the end
140

141
        assertThat(mvc.get().uri("/api/books?authorId={a}&page=1&size=5&sort=year,desc", authorId))
142
            .hasStatusOk()
143
            .bodyJson()
144
            .isStrictlyEqualTo("""
145
                {
146
                  "content": [],
147
                  "page": { "size": 5, "number": 1, "totalElements": 1, "totalPages": 1 }
148
                }
149
                """);
150

151
        ArgumentCaptor<Pageable> pageable = ArgumentCaptor.forClass(Pageable.class);
152
        verify(books).findAll(eq(authorId), pageable.capture());
153
        assertThat(pageable.getValue()).isEqualTo(expected);
154
    }
155
}

Each test names the page request the controller should make, expected, and then does three things with it.

The stub answers any request. any(Pageable.class) matches whatever Pageable the controller passes, and the mock always returns the same page: a PageImpl — the Page implementation Spring Data itself returns — holding the books, built for expected, with the total row count. It is the page a database would return for that request. So the "size": 20 and "number": 0 in the response come from the stub, not from the request: a controller that asked for size 10 would still get this page back.

What went out. The expected body is the { content, page } shape from Lesson 8: the books in content, in the same JSON as Step 1's, then the page's size, number and totals. That proves the serialization — if someone deletes serialization-mode=via_dto from application.properties, the body falls back to the raw PageImpl layout, with no page object, and this test fails; the slice reads application.properties like the real app does. In the second test the client asks for page 1 of an author's books, and the author has only one: the page is past the end, so content is empty while totalElements still says 1.

What came in. This is what proves the controller's paging. The Pageable is built inside the controller, so — exactly as with the saved Book in Lesson 10 — an ArgumentCaptor reaches it after the fact, and isEqualTo(expected) compares it in one line: a PageRequest is equal to another with the same page number, size and sort. Without query parameters that is page 0, size 20, sorted by title then id — the @PageableDefault plus the tiebreaker. In the second test the client asks for its own page, size and sort, and the tiebreaker still comes last. Change the default to size = 10 and only this line notices — the body still says 20, because the stub's page does:

expected: Page request [number: 0, size 20, sort: title: ASC,id: ASC]
 but was: Page request [number: 0, size 10, sort: title: ASC,id: ASC]

isNull() and eq(authorId) are argument matchers like any(); Mockito requires that once one argument uses a matcher, every argument does, which is why the plain authorId is wrapped in eq(...).

Stub loosely, verify exactly

Why not stub the exact request — when(books.findAll(null, expected)) — and skip the captor? Because a stub written for exact arguments simply doesn't match when the controller passes something else, and an unmatched call on a Mockito mock returns null. BookController then calls .map(...) on that null, the catch-all handler turns the NullPointerException into a 500, and the test fails with expected 200 but was 500 — true, but pointing nowhere near the bug. So the stub accepts any arguments, and the exact ones are checked afterwards — with a captor here, with verify in Step 4. The failure then lands on the argument itself, expected and actual side by side, as above.

Step 4 — Creating a book: `201`, `Location`, and what reaches the service


23 collapsed lines
1
package com.example.library.book;
2

3
import java.util.List;
4
import java.util.Set;
5
import java.util.UUID;
6
import com.example.library.author.Author;
7
import com.example.library.error.NotFoundException;
8
import org.junit.jupiter.api.DisplayName;
9
import org.junit.jupiter.api.Test;
10
import org.mockito.ArgumentCaptor;
11
import org.springframework.beans.factory.annotation.Autowired;
12
import org.springframework.boot.webmvc.test.autoconfigure.WebMvcTest;
13
import org.springframework.data.domain.PageImpl;
14
import org.springframework.data.domain.PageRequest;
15
import org.springframework.data.domain.Pageable;
16
import org.springframework.data.domain.Sort;
17
import org.springframework.http.HttpStatus;
18
import org.springframework.http.MediaType;
19
import org.springframework.test.context.bean.override.mockito.MockitoBean;
20
import org.springframework.test.web.servlet.assertj.MockMvcTester;
21

22
import static org.assertj.core.api.Assertions.assertThat;
23
import static org.mockito.ArgumentMatchers.any;
24
import static org.mockito.ArgumentMatchers.anyInt;
132 collapsed lines
25
import static org.mockito.ArgumentMatchers.eq;
26
import static org.mockito.ArgumentMatchers.isNull;
27
import static org.mockito.Mockito.verify;
28
import static org.mockito.Mockito.verifyNoInteractions;
29
import static org.mockito.Mockito.when;
30

31
@WebMvcTest(BookController.class)                // only the web layer, and only this controller
32
class BookControllerTest {
33

34
    @Autowired MockMvcTester mvc;                // sends requests through Spring MVC, no server
35
    @MockitoBean BookService books;              // a Mockito mock, registered as the BookService bean
36

37
    Author hunt = new Author("Andrew Hunt");
38
    Author thomas = new Author("David Thomas");
39
    Book book = new Book("The Pragmatic Programmer", 1999, Set.of(thomas, hunt));
40

41
    @Test
42
    @DisplayName("GET /api/books/{id} returns the book as JSON, authors sorted by name")
43
    void byId_found() {
44
        when(books.getById(book.getId())).thenReturn(book);
45

46
        assertThat(mvc.get().uri("/api/books/{id}", book.getId()))
47
            .hasStatusOk()
48
            .hasContentType(MediaType.APPLICATION_JSON)
49
            .bodyJson()                                  // strict: every field, nothing extra, arrays in order
50
            .isStrictlyEqualTo("""
51
                {
52
                  "id": "%s",
53
                  "title": "The Pragmatic Programmer",
54
                  "year": 1999,
55
                  "authors": [
56
                    { "id": "%s", "name": "Andrew Hunt" },
57
                    { "id": "%s", "name": "David Thomas" }
58
                  ]
59
                }
60
                """.formatted(book.getId(), hunt.getId(), thomas.getId()));
61
    }
62

63
    @Test
64
    @DisplayName("GET /api/books/{id} for a missing book is a 404 problem")
65
    void byId_missing() {
66
        UUID id = UUID.randomUUID();
67
        when(books.getById(id)).thenThrow(new NotFoundException("No book with id " + id));
68

69
        assertThat(mvc.get().uri("/api/books/{id}", id))
70
            .hasStatus(HttpStatus.NOT_FOUND)
71
            .hasContentType(MediaType.APPLICATION_PROBLEM_JSON)
72
            .bodyJson()
73
            .isStrictlyEqualTo("""
74
                {
75
                  "status": 404,
76
                  "title": "Resource not found",
77
                  "detail": "No book with id %s",
78
                  "instance": "/api/books/%s"
79
                }
80
                """.formatted(id, id));
81
    }
82

83
    @Test
84
    @DisplayName("GET /api/books/{id} with a malformed id is a 400 and never reaches the service")
85
    void byId_malformedId() {
86
        assertThat(mvc.get().uri("/api/books/{id}", "not-a-uuid"))
87
            .hasStatus(HttpStatus.BAD_REQUEST)
88
            .hasContentType(MediaType.APPLICATION_PROBLEM_JSON)
89
            .bodyJson()
90
            .isStrictlyEqualTo("""
91
                {
92
                  "status": 400,
93
                  "title": "Bad Request",
94
                  "detail": "Failed to convert 'id' with value: 'not-a-uuid'",
95
                  "instance": "/api/books/not-a-uuid"
96
                }
97
                """);
98

99
        verifyNoInteractions(books);                     // the request never got past Spring MVC
100
    }
101

102
    @Test
103
    @DisplayName("GET /api/books asks for page 0 of 20 by title then id, and returns the stable page shape")
104
    void all_defaults() {
105
        Pageable expected = PageRequest.of(0, 20, Sort.by("title", "id"));   // what the controller should ask for
106
        when(books.findAll(isNull(), any(Pageable.class)))                     // stub loosely: any page request...
107
            .thenReturn(new PageImpl<>(List.of(book), expected, 1));          // ...gets the page answering `expected`
108

109
        assertThat(mvc.get().uri("/api/books"))
110
            .hasStatusOk()
111
            .bodyJson()
112
            .isStrictlyEqualTo("""
113
                {
114
                  "content": [
115
                    {
116
                      "id": "%s",
117
                      "title": "The Pragmatic Programmer",
118
                      "year": 1999,
119
                      "authors": [
120
                        { "id": "%s", "name": "Andrew Hunt" },
121
                        { "id": "%s", "name": "David Thomas" }
122
                      ]
123
                    }
124
                  ],
125
                  "page": { "size": 20, "number": 0, "totalElements": 1, "totalPages": 1 }
126
                }
127
                """.formatted(book.getId(), hunt.getId(), thomas.getId()));
128

129
        ArgumentCaptor<Pageable> pageable = ArgumentCaptor.forClass(Pageable.class);
130
        verify(books).findAll(isNull(), pageable.capture());                  // ...verify exactly
131
        assertThat(pageable.getValue()).isEqualTo(expected);
132
    }
133

134
    @Test
135
    @DisplayName("GET /api/books passes the author filter and the client's sort, id still last")
136
    void all_filteredAndSorted() {
137
        UUID authorId = UUID.randomUUID();
138
        Pageable expected = PageRequest.of(1, 5, Sort.by(Sort.Order.desc("year"), Sort.Order.asc("id")));
139
        when(books.findAll(eq(authorId), any(Pageable.class)))
140
            .thenReturn(new PageImpl<>(List.of(), expected, 1));              // one match: page 1 is past the end
141

142
        assertThat(mvc.get().uri("/api/books?authorId={a}&page=1&size=5&sort=year,desc", authorId))
143
            .hasStatusOk()
144
            .bodyJson()
145
            .isStrictlyEqualTo("""
146
                {
147
                  "content": [],
148
                  "page": { "size": 5, "number": 1, "totalElements": 1, "totalPages": 1 }
149
                }
150
                """);
151

152
        ArgumentCaptor<Pageable> pageable = ArgumentCaptor.forClass(Pageable.class);
153
        verify(books).findAll(eq(authorId), pageable.capture());
154
        assertThat(pageable.getValue()).isEqualTo(expected);
155
    }
156

157
    @Test
158
    @DisplayName("POST /api/books creates the book: 201, Location header, body")
159
    void create_valid() {
160
        when(books.create(any(), anyInt(), any())).thenReturn(book);   // stub loosely...
161

162
        assertThat(mvc.post().uri("/api/books")
163
                .contentType(MediaType.APPLICATION_JSON)
164
                .content("""
165
                    {
166
                      "title": "The Pragmatic Programmer",
167
                      "year": 1999,
168
                      "authorIds": ["%s", "%s"]
169
                    }
170
                    """.formatted(hunt.getId(), thomas.getId())))
171
            .hasStatus(HttpStatus.CREATED)
172
            .hasHeader("Location", "/api/books/" + book.getId())
173
            .bodyJson()
174
            .isStrictlyEqualTo("""
175
                {
176
                  "id": "%s",
177
                  "title": "The Pragmatic Programmer",
178
                  "year": 1999,
179
                  "authors": [
180
                    { "id": "%s", "name": "Andrew Hunt" },
181
                    { "id": "%s", "name": "David Thomas" }
182
                  ]
183
                }
184
                """.formatted(book.getId(), hunt.getId(), thomas.getId()));
185

186
        verify(books).create("The Pragmatic Programmer", 1999, Set.of(hunt.getId(), thomas.getId()));   // ...verify exactly
187
    }
188
}

The request is built the way a client builds it: a Content-Type header and a body. The body is written out as JSON text, not produced by serializing a CreateBookRequest. JSON is the contract; the record is an implementation detail. If someone renamed authorIds in the record, a test that serialized the record would rename it in the request too and keep passing — while every real client broke. With the JSON written out, the test sends what clients send and fails.

On the way out, the test checks the 201, the Location header the controller builds from the saved book's id, and the body: that same book, in full.

The service call follows Step 3's rule, stub loosely and verify exactly. The stub accepts any arguments, any(), anyInt(), any(), so the request always gets a book back; the controller's own job here is unpacking the request into create(title, year, authorIds), and verify(books).create(...) checks exactly that, afterwards. The arguments are all plain values, so verify compares them directly — no captor needed.

Step 5 — Validation: a `400` that names each field


188 collapsed lines
1
package com.example.library.book;
2

3
import java.util.List;
4
import java.util.Set;
5
import java.util.UUID;
6
import com.example.library.author.Author;
7
import com.example.library.error.NotFoundException;
8
import org.junit.jupiter.api.DisplayName;
9
import org.junit.jupiter.api.Test;
10
import org.mockito.ArgumentCaptor;
11
import org.springframework.beans.factory.annotation.Autowired;
12
import org.springframework.boot.webmvc.test.autoconfigure.WebMvcTest;
13
import org.springframework.data.domain.PageImpl;
14
import org.springframework.data.domain.PageRequest;
15
import org.springframework.data.domain.Pageable;
16
import org.springframework.data.domain.Sort;
17
import org.springframework.http.HttpStatus;
18
import org.springframework.http.MediaType;
19
import org.springframework.test.context.bean.override.mockito.MockitoBean;
20
import org.springframework.test.web.servlet.assertj.MockMvcTester;
21

22
import static org.assertj.core.api.Assertions.assertThat;
23
import static org.mockito.ArgumentMatchers.any;
24
import static org.mockito.ArgumentMatchers.anyInt;
25
import static org.mockito.ArgumentMatchers.eq;
26
import static org.mockito.ArgumentMatchers.isNull;
27
import static org.mockito.Mockito.verify;
28
import static org.mockito.Mockito.verifyNoInteractions;
29
import static org.mockito.Mockito.when;
30

31
@WebMvcTest(BookController.class)                // only the web layer, and only this controller
32
class BookControllerTest {
33

34
    @Autowired MockMvcTester mvc;                // sends requests through Spring MVC, no server
35
    @MockitoBean BookService books;              // a Mockito mock, registered as the BookService bean
36

37
    Author hunt = new Author("Andrew Hunt");
38
    Author thomas = new Author("David Thomas");
39
    Book book = new Book("The Pragmatic Programmer", 1999, Set.of(thomas, hunt));
40

41
    @Test
42
    @DisplayName("GET /api/books/{id} returns the book as JSON, authors sorted by name")
43
    void byId_found() {
44
        when(books.getById(book.getId())).thenReturn(book);
45

46
        assertThat(mvc.get().uri("/api/books/{id}", book.getId()))
47
            .hasStatusOk()
48
            .hasContentType(MediaType.APPLICATION_JSON)
49
            .bodyJson()                                  // strict: every field, nothing extra, arrays in order
50
            .isStrictlyEqualTo("""
51
                {
52
                  "id": "%s",
53
                  "title": "The Pragmatic Programmer",
54
                  "year": 1999,
55
                  "authors": [
56
                    { "id": "%s", "name": "Andrew Hunt" },
57
                    { "id": "%s", "name": "David Thomas" }
58
                  ]
59
                }
60
                """.formatted(book.getId(), hunt.getId(), thomas.getId()));
61
    }
62

63
    @Test
64
    @DisplayName("GET /api/books/{id} for a missing book is a 404 problem")
65
    void byId_missing() {
66
        UUID id = UUID.randomUUID();
67
        when(books.getById(id)).thenThrow(new NotFoundException("No book with id " + id));
68

69
        assertThat(mvc.get().uri("/api/books/{id}", id))
70
            .hasStatus(HttpStatus.NOT_FOUND)
71
            .hasContentType(MediaType.APPLICATION_PROBLEM_JSON)
72
            .bodyJson()
73
            .isStrictlyEqualTo("""
74
                {
75
                  "status": 404,
76
                  "title": "Resource not found",
77
                  "detail": "No book with id %s",
78
                  "instance": "/api/books/%s"
79
                }
80
                """.formatted(id, id));
81
    }
82

83
    @Test
84
    @DisplayName("GET /api/books/{id} with a malformed id is a 400 and never reaches the service")
85
    void byId_malformedId() {
86
        assertThat(mvc.get().uri("/api/books/{id}", "not-a-uuid"))
87
            .hasStatus(HttpStatus.BAD_REQUEST)
88
            .hasContentType(MediaType.APPLICATION_PROBLEM_JSON)
89
            .bodyJson()
90
            .isStrictlyEqualTo("""
91
                {
92
                  "status": 400,
93
                  "title": "Bad Request",
94
                  "detail": "Failed to convert 'id' with value: 'not-a-uuid'",
95
                  "instance": "/api/books/not-a-uuid"
96
                }
97
                """);
98

99
        verifyNoInteractions(books);                     // the request never got past Spring MVC
100
    }
101

102
    @Test
103
    @DisplayName("GET /api/books asks for page 0 of 20 by title then id, and returns the stable page shape")
104
    void all_defaults() {
105
        Pageable expected = PageRequest.of(0, 20, Sort.by("title", "id"));   // what the controller should ask for
106
        when(books.findAll(isNull(), any(Pageable.class)))                     // stub loosely: any page request...
107
            .thenReturn(new PageImpl<>(List.of(book), expected, 1));          // ...gets the page answering `expected`
108

109
        assertThat(mvc.get().uri("/api/books"))
110
            .hasStatusOk()
111
            .bodyJson()
112
            .isStrictlyEqualTo("""
113
                {
114
                  "content": [
115
                    {
116
                      "id": "%s",
117
                      "title": "The Pragmatic Programmer",
118
                      "year": 1999,
119
                      "authors": [
120
                        { "id": "%s", "name": "Andrew Hunt" },
121
                        { "id": "%s", "name": "David Thomas" }
122
                      ]
123
                    }
124
                  ],
125
                  "page": { "size": 20, "number": 0, "totalElements": 1, "totalPages": 1 }
126
                }
127
                """.formatted(book.getId(), hunt.getId(), thomas.getId()));
128

129
        ArgumentCaptor<Pageable> pageable = ArgumentCaptor.forClass(Pageable.class);
130
        verify(books).findAll(isNull(), pageable.capture());                  // ...verify exactly
131
        assertThat(pageable.getValue()).isEqualTo(expected);
132
    }
133

134
    @Test
135
    @DisplayName("GET /api/books passes the author filter and the client's sort, id still last")
136
    void all_filteredAndSorted() {
137
        UUID authorId = UUID.randomUUID();
138
        Pageable expected = PageRequest.of(1, 5, Sort.by(Sort.Order.desc("year"), Sort.Order.asc("id")));
139
        when(books.findAll(eq(authorId), any(Pageable.class)))
140
            .thenReturn(new PageImpl<>(List.of(), expected, 1));              // one match: page 1 is past the end
141

142
        assertThat(mvc.get().uri("/api/books?authorId={a}&page=1&size=5&sort=year,desc", authorId))
143
            .hasStatusOk()
144
            .bodyJson()
145
            .isStrictlyEqualTo("""
146
                {
147
                  "content": [],
148
                  "page": { "size": 5, "number": 1, "totalElements": 1, "totalPages": 1 }
149
                }
150
                """);
151

152
        ArgumentCaptor<Pageable> pageable = ArgumentCaptor.forClass(Pageable.class);
153
        verify(books).findAll(eq(authorId), pageable.capture());
154
        assertThat(pageable.getValue()).isEqualTo(expected);
155
    }
156

157
    @Test
158
    @DisplayName("POST /api/books creates the book: 201, Location header, body")
159
    void create_valid() {
160
        when(books.create(any(), anyInt(), any())).thenReturn(book);   // stub loosely...
161

162
        assertThat(mvc.post().uri("/api/books")
163
                .contentType(MediaType.APPLICATION_JSON)
164
                .content("""
165
                    {
166
                      "title": "The Pragmatic Programmer",
167
                      "year": 1999,
168
                      "authorIds": ["%s", "%s"]
169
                    }
170
                    """.formatted(hunt.getId(), thomas.getId())))
171
            .hasStatus(HttpStatus.CREATED)
172
            .hasHeader("Location", "/api/books/" + book.getId())
173
            .bodyJson()
174
            .isStrictlyEqualTo("""
175
                {
176
                  "id": "%s",
177
                  "title": "The Pragmatic Programmer",
178
                  "year": 1999,
179
                  "authors": [
180
                    { "id": "%s", "name": "Andrew Hunt" },
181
                    { "id": "%s", "name": "David Thomas" }
182
                  ]
183
                }
184
                """.formatted(book.getId(), hunt.getId(), thomas.getId()));
185

186
        verify(books).create("The Pragmatic Programmer", 1999, Set.of(hunt.getId(), thomas.getId()));   // ...verify exactly
187
    }
188

189
    @Test
190
    @DisplayName("POST /api/books with invalid fields is a 400 naming each one, and nothing is created")
191
    void create_invalid() {
192
        assertThat(mvc.post().uri("/api/books")
193
                .contentType(MediaType.APPLICATION_JSON)
194
                .content("""
195
                    { "title": " ", "year": 0, "authorIds": [] }
196
                    """))
197
            .hasStatus(HttpStatus.BAD_REQUEST)
198
            .hasContentType(MediaType.APPLICATION_PROBLEM_JSON)
199
            .bodyJson()
200
            .isStrictlyEqualTo("""
201
                {
202
                  "status": 400,
203
                  "title": "Validation failed",
204
                  "detail": "One or more fields are invalid.",
205
                  "instance": "/api/books",
206
                  "errors": {
207
                    "title": "must not be blank",
208
                    "year": "must be greater than 0",
209
                    "authorIds": "must not be empty"
210
                  }
211
                }
212
                """);
213

214
        verifyNoInteractions(books);                     // @Valid stopped it before the controller ran
215
    }
216
}

One body breaks all three constraints from Lesson 7 at once: a title that is only a space (@NotBlank rejects whitespace), year 0 (@Positive), and an empty authorIds (@NotEmpty). The expected body is the whole problem that ApiExceptionHandler's handleMethodArgumentNotValid override builds: its title and detail, and the errors map with one entry per field, in Bean Validation's default messages. And verifyNoInteractions(books) is this layer's version of Lesson 10's verify(books, never()).save(any()): @Valid rejects the body before create runs, so the service is never asked to do anything.

Step 6 — Replace and delete

The last three book endpoints: PUT returns the replaced book, DELETE returns 204 with no body — or 404 when there is nothing to delete.


26 collapsed lines
1
package com.example.library.book;
2

3
import java.util.List;
4
import java.util.Set;
5
import java.util.UUID;
6
import com.example.library.author.Author;
7
import com.example.library.error.NotFoundException;
8
import org.junit.jupiter.api.DisplayName;
9
import org.junit.jupiter.api.Test;
10
import org.mockito.ArgumentCaptor;
11
import org.springframework.beans.factory.annotation.Autowired;
12
import org.springframework.boot.webmvc.test.autoconfigure.WebMvcTest;
13
import org.springframework.data.domain.PageImpl;
14
import org.springframework.data.domain.PageRequest;
15
import org.springframework.data.domain.Pageable;
16
import org.springframework.data.domain.Sort;
17
import org.springframework.http.HttpStatus;
18
import org.springframework.http.MediaType;
19
import org.springframework.test.context.bean.override.mockito.MockitoBean;
20
import org.springframework.test.web.servlet.assertj.MockMvcTester;
21

22
import static org.assertj.core.api.Assertions.assertThat;
23
import static org.mockito.ArgumentMatchers.any;
24
import static org.mockito.ArgumentMatchers.anyInt;
25
import static org.mockito.ArgumentMatchers.eq;
26
import static org.mockito.ArgumentMatchers.isNull;
27
import static org.mockito.Mockito.doThrow;
190 collapsed lines
28
import static org.mockito.Mockito.verify;
29
import static org.mockito.Mockito.verifyNoInteractions;
30
import static org.mockito.Mockito.when;
31

32
@WebMvcTest(BookController.class)                // only the web layer, and only this controller
33
class BookControllerTest {
34

35
    @Autowired MockMvcTester mvc;                // sends requests through Spring MVC, no server
36
    @MockitoBean BookService books;              // a Mockito mock, registered as the BookService bean
37

38
    Author hunt = new Author("Andrew Hunt");
39
    Author thomas = new Author("David Thomas");
40
    Book book = new Book("The Pragmatic Programmer", 1999, Set.of(thomas, hunt));
41

42
    @Test
43
    @DisplayName("GET /api/books/{id} returns the book as JSON, authors sorted by name")
44
    void byId_found() {
45
        when(books.getById(book.getId())).thenReturn(book);
46

47
        assertThat(mvc.get().uri("/api/books/{id}", book.getId()))
48
            .hasStatusOk()
49
            .hasContentType(MediaType.APPLICATION_JSON)
50
            .bodyJson()                                  // strict: every field, nothing extra, arrays in order
51
            .isStrictlyEqualTo("""
52
                {
53
                  "id": "%s",
54
                  "title": "The Pragmatic Programmer",
55
                  "year": 1999,
56
                  "authors": [
57
                    { "id": "%s", "name": "Andrew Hunt" },
58
                    { "id": "%s", "name": "David Thomas" }
59
                  ]
60
                }
61
                """.formatted(book.getId(), hunt.getId(), thomas.getId()));
62
    }
63

64
    @Test
65
    @DisplayName("GET /api/books/{id} for a missing book is a 404 problem")
66
    void byId_missing() {
67
        UUID id = UUID.randomUUID();
68
        when(books.getById(id)).thenThrow(new NotFoundException("No book with id " + id));
69

70
        assertThat(mvc.get().uri("/api/books/{id}", id))
71
            .hasStatus(HttpStatus.NOT_FOUND)
72
            .hasContentType(MediaType.APPLICATION_PROBLEM_JSON)
73
            .bodyJson()
74
            .isStrictlyEqualTo("""
75
                {
76
                  "status": 404,
77
                  "title": "Resource not found",
78
                  "detail": "No book with id %s",
79
                  "instance": "/api/books/%s"
80
                }
81
                """.formatted(id, id));
82
    }
83

84
    @Test
85
    @DisplayName("GET /api/books/{id} with a malformed id is a 400 and never reaches the service")
86
    void byId_malformedId() {
87
        assertThat(mvc.get().uri("/api/books/{id}", "not-a-uuid"))
88
            .hasStatus(HttpStatus.BAD_REQUEST)
89
            .hasContentType(MediaType.APPLICATION_PROBLEM_JSON)
90
            .bodyJson()
91
            .isStrictlyEqualTo("""
92
                {
93
                  "status": 400,
94
                  "title": "Bad Request",
95
                  "detail": "Failed to convert 'id' with value: 'not-a-uuid'",
96
                  "instance": "/api/books/not-a-uuid"
97
                }
98
                """);
99

100
        verifyNoInteractions(books);                     // the request never got past Spring MVC
101
    }
102

103
    @Test
104
    @DisplayName("GET /api/books asks for page 0 of 20 by title then id, and returns the stable page shape")
105
    void all_defaults() {
106
        Pageable expected = PageRequest.of(0, 20, Sort.by("title", "id"));   // what the controller should ask for
107
        when(books.findAll(isNull(), any(Pageable.class)))                     // stub loosely: any page request...
108
            .thenReturn(new PageImpl<>(List.of(book), expected, 1));          // ...gets the page answering `expected`
109

110
        assertThat(mvc.get().uri("/api/books"))
111
            .hasStatusOk()
112
            .bodyJson()
113
            .isStrictlyEqualTo("""
114
                {
115
                  "content": [
116
                    {
117
                      "id": "%s",
118
                      "title": "The Pragmatic Programmer",
119
                      "year": 1999,
120
                      "authors": [
121
                        { "id": "%s", "name": "Andrew Hunt" },
122
                        { "id": "%s", "name": "David Thomas" }
123
                      ]
124
                    }
125
                  ],
126
                  "page": { "size": 20, "number": 0, "totalElements": 1, "totalPages": 1 }
127
                }
128
                """.formatted(book.getId(), hunt.getId(), thomas.getId()));
129

130
        ArgumentCaptor<Pageable> pageable = ArgumentCaptor.forClass(Pageable.class);
131
        verify(books).findAll(isNull(), pageable.capture());                  // ...verify exactly
132
        assertThat(pageable.getValue()).isEqualTo(expected);
133
    }
134

135
    @Test
136
    @DisplayName("GET /api/books passes the author filter and the client's sort, id still last")
137
    void all_filteredAndSorted() {
138
        UUID authorId = UUID.randomUUID();
139
        Pageable expected = PageRequest.of(1, 5, Sort.by(Sort.Order.desc("year"), Sort.Order.asc("id")));
140
        when(books.findAll(eq(authorId), any(Pageable.class)))
141
            .thenReturn(new PageImpl<>(List.of(), expected, 1));              // one match: page 1 is past the end
142

143
        assertThat(mvc.get().uri("/api/books?authorId={a}&page=1&size=5&sort=year,desc", authorId))
144
            .hasStatusOk()
145
            .bodyJson()
146
            .isStrictlyEqualTo("""
147
                {
148
                  "content": [],
149
                  "page": { "size": 5, "number": 1, "totalElements": 1, "totalPages": 1 }
150
                }
151
                """);
152

153
        ArgumentCaptor<Pageable> pageable = ArgumentCaptor.forClass(Pageable.class);
154
        verify(books).findAll(eq(authorId), pageable.capture());
155
        assertThat(pageable.getValue()).isEqualTo(expected);
156
    }
157

158
    @Test
159
    @DisplayName("POST /api/books creates the book: 201, Location header, body")
160
    void create_valid() {
161
        when(books.create(any(), anyInt(), any())).thenReturn(book);   // stub loosely...
162

163
        assertThat(mvc.post().uri("/api/books")
164
                .contentType(MediaType.APPLICATION_JSON)
165
                .content("""
166
                    {
167
                      "title": "The Pragmatic Programmer",
168
                      "year": 1999,
169
                      "authorIds": ["%s", "%s"]
170
                    }
171
                    """.formatted(hunt.getId(), thomas.getId())))
172
            .hasStatus(HttpStatus.CREATED)
173
            .hasHeader("Location", "/api/books/" + book.getId())
174
            .bodyJson()
175
            .isStrictlyEqualTo("""
176
                {
177
                  "id": "%s",
178
                  "title": "The Pragmatic Programmer",
179
                  "year": 1999,
180
                  "authors": [
181
                    { "id": "%s", "name": "Andrew Hunt" },
182
                    { "id": "%s", "name": "David Thomas" }
183
                  ]
184
                }
185
                """.formatted(book.getId(), hunt.getId(), thomas.getId()));
186

187
        verify(books).create("The Pragmatic Programmer", 1999, Set.of(hunt.getId(), thomas.getId()));   // ...verify exactly
188
    }
189

190
    @Test
191
    @DisplayName("POST /api/books with invalid fields is a 400 naming each one, and nothing is created")
192
    void create_invalid() {
193
        assertThat(mvc.post().uri("/api/books")
194
                .contentType(MediaType.APPLICATION_JSON)
195
                .content("""
196
                    { "title": " ", "year": 0, "authorIds": [] }
197
                    """))
198
            .hasStatus(HttpStatus.BAD_REQUEST)
199
            .hasContentType(MediaType.APPLICATION_PROBLEM_JSON)
200
            .bodyJson()
201
            .isStrictlyEqualTo("""
202
                {
203
                  "status": 400,
204
                  "title": "Validation failed",
205
                  "detail": "One or more fields are invalid.",
206
                  "instance": "/api/books",
207
                  "errors": {
208
                    "title": "must not be blank",
209
                    "year": "must be greater than 0",
210
                    "authorIds": "must not be empty"
211
                  }
212
                }
213
                """);
214

215
        verifyNoInteractions(books);                     // @Valid stopped it before the controller ran
216
    }
217

218
    @Test
219
    @DisplayName("PUT /api/books/{id} replaces the book and returns it")
220
    void replace_valid() {
221
        when(books.replace(any(), any(), anyInt(), any())).thenReturn(book);
222

223
        assertThat(mvc.put().uri("/api/books/{id}", book.getId())
224
                .contentType(MediaType.APPLICATION_JSON)
225
                .content("""
226
                    {
227
                      "title": "The Pragmatic Programmer",
228
                      "year": 1999,
229
                      "authorIds": ["%s", "%s"]
230
                    }
231
                    """.formatted(hunt.getId(), thomas.getId())))
232
            .hasStatusOk()
233
            .bodyJson()
234
            .isStrictlyEqualTo("""
235
                {
236
                  "id": "%s",
237
                  "title": "The Pragmatic Programmer",
238
                  "year": 1999,
239
                  "authors": [
240
                    { "id": "%s", "name": "Andrew Hunt" },
241
                    { "id": "%s", "name": "David Thomas" }
242
                  ]
243
                }
244
                """.formatted(book.getId(), hunt.getId(), thomas.getId()));
245

246
        verify(books).replace(book.getId(), "The Pragmatic Programmer", 1999, Set.of(hunt.getId(), thomas.getId()));
247
    }
248

249
    @Test
250
    @DisplayName("DELETE /api/books/{id} is a 204 with no body")
251
    void delete_found() {
252
        assertThat(mvc.delete().uri("/api/books/{id}", book.getId()))
253
            .hasStatus(HttpStatus.NO_CONTENT)
254
            .body().isEmpty();
255

256
        verify(books).delete(book.getId());
257
    }
258

259
    @Test
260
    @DisplayName("DELETE /api/books/{id} for a missing book is a 404 problem")
261
    void delete_missing() {
262
        UUID id = UUID.randomUUID();
263
        doThrow(new NotFoundException("No book with id " + id)).when(books).delete(id);   // delete is void
264

265
        assertThat(mvc.delete().uri("/api/books/{id}", id))
266
            .hasStatus(HttpStatus.NOT_FOUND)
267
            .hasContentType(MediaType.APPLICATION_PROBLEM_JSON)
268
            .bodyJson()
269
            .isStrictlyEqualTo("""
270
                {
271
                  "status": 404,
272
                  "title": "Resource not found",
273
                  "detail": "No book with id %s",
274
                  "instance": "/api/books/%s"
275
                }
276
                """.formatted(id, id));
277
    }
278
}

replace_valid follows create_valid's pattern, and its verify adds the one thing PUT has that POST doesn't: the id from the path has to reach the service as its first argument.

delete_found stubs nothing. BookService.delete returns void, and a mock's void method does nothing unless told otherwise — which is exactly the success case. body().isEmpty() checks that the 204 really has no body.

delete_missing needs the mock to throw from a void method, and when(...) can't express that: when(books.delete(id)) doesn't compile, because there is no return value to pass to when. Mockito's doThrow(...).when(books).delete(id) turns the sentence around: first the behaviour, then the mock, then the call it applies to.

Step 7 — The author controller, and its `409`

AuthorController gets its own slice, with an AuthorService mock, and the same coverage: every author endpoint, success and failure. Most of its tests mirror the book tests you've just written, with name in place of the book's fields; the new one is delete_stillHasBooks, the 409 Conflict from Lesson 7 — the response when an author can't be deleted because books still point at them.

1
package com.example.library.author;
2

3
import java.util.List;
4
import java.util.UUID;
5
import com.example.library.error.ConflictException;
6
import com.example.library.error.NotFoundException;
7
import org.junit.jupiter.api.DisplayName;
8
import org.junit.jupiter.api.Test;
9
import org.mockito.ArgumentCaptor;
10
import org.springframework.beans.factory.annotation.Autowired;
11
import org.springframework.boot.webmvc.test.autoconfigure.WebMvcTest;
12
import org.springframework.data.domain.PageImpl;
13
import org.springframework.data.domain.PageRequest;
14
import org.springframework.data.domain.Pageable;
15
import org.springframework.data.domain.Sort;
16
import org.springframework.http.HttpStatus;
17
import org.springframework.http.MediaType;
18
import org.springframework.test.context.bean.override.mockito.MockitoBean;
19
import org.springframework.test.web.servlet.assertj.MockMvcTester;
20

21
import static org.assertj.core.api.Assertions.assertThat;
22
import static org.mockito.ArgumentMatchers.any;
23
import static org.mockito.Mockito.doThrow;
24
import static org.mockito.Mockito.verify;
25
import static org.mockito.Mockito.verifyNoInteractions;
26
import static org.mockito.Mockito.when;
27

28
@WebMvcTest(AuthorController.class)
29
class AuthorControllerTest {
30

31
    @Autowired MockMvcTester mvc;
32
    @MockitoBean AuthorService authors;
33

34
    Author hunt = new Author("Andrew Hunt");
35

36
    @Test
37
    @DisplayName("GET /api/authors/{id} returns the author as JSON")
38
    void byId_found() {
39
        when(authors.getById(hunt.getId())).thenReturn(hunt);
40

41
        assertThat(mvc.get().uri("/api/authors/{id}", hunt.getId()))
42
            .hasStatusOk()
43
            .bodyJson()
44
            .isStrictlyEqualTo("""
45
                { "id": "%s", "name": "Andrew Hunt" }
46
                """.formatted(hunt.getId()));
47
    }
48

49
    @Test
50
    @DisplayName("GET /api/authors/{id} for a missing author is a 404 problem")
51
    void byId_missing() {
52
        UUID id = UUID.randomUUID();
53
        when(authors.getById(id)).thenThrow(new NotFoundException("No author with id " + id));
54

55
        assertThat(mvc.get().uri("/api/authors/{id}", id))
56
            .hasStatus(HttpStatus.NOT_FOUND)
57
            .hasContentType(MediaType.APPLICATION_PROBLEM_JSON)
58
            .bodyJson()
59
            .isStrictlyEqualTo("""
60
                {
61
                  "status": 404,
62
                  "title": "Resource not found",
63
                  "detail": "No author with id %s",
64
                  "instance": "/api/authors/%s"
65
                }
66
                """.formatted(id, id));
67
    }
68

69
    @Test
70
    @DisplayName("GET /api/authors/{id} with a malformed id is a 400 and never reaches the service")
71
    void byId_malformedId() {
72
        assertThat(mvc.get().uri("/api/authors/{id}", "not-a-uuid"))
73
            .hasStatus(HttpStatus.BAD_REQUEST)
74
            .hasContentType(MediaType.APPLICATION_PROBLEM_JSON)
75
            .bodyJson()
76
            .isStrictlyEqualTo("""
77
                {
78
                  "status": 400,
79
                  "title": "Bad Request",
80
                  "detail": "Failed to convert 'id' with value: 'not-a-uuid'",
81
                  "instance": "/api/authors/not-a-uuid"
82
                }
83
                """);
84

85
        verifyNoInteractions(authors);
86
    }
87

88
    @Test
89
    @DisplayName("GET /api/authors asks for page 0 of 20 by name then id, and returns the stable page shape")
90
    void all_defaults() {
91
        Pageable expected = PageRequest.of(0, 20, Sort.by("name", "id"));
92
        when(authors.findAll(any(Pageable.class)))
93
            .thenReturn(new PageImpl<>(List.of(hunt), expected, 1));
94

95
        assertThat(mvc.get().uri("/api/authors"))
96
            .hasStatusOk()
97
            .bodyJson()
98
            .isStrictlyEqualTo("""
99
                {
100
                  "content": [
101
                    { "id": "%s", "name": "Andrew Hunt" }
102
                  ],
103
                  "page": { "size": 20, "number": 0, "totalElements": 1, "totalPages": 1 }
104
                }
105
                """.formatted(hunt.getId()));
106

107
        ArgumentCaptor<Pageable> pageable = ArgumentCaptor.forClass(Pageable.class);
108
        verify(authors).findAll(pageable.capture());
109
        assertThat(pageable.getValue()).isEqualTo(expected);
110
    }
111

112
    @Test
113
    @DisplayName("POST /api/authors creates the author: 201, Location header, body")
114
    void create_valid() {
115
        when(authors.create(any())).thenReturn(hunt);
116

117
        assertThat(mvc.post().uri("/api/authors")
118
                .contentType(MediaType.APPLICATION_JSON)
119
                .content("""
120
                    { "name": "Andrew Hunt" }
121
                    """))
122
            .hasStatus(HttpStatus.CREATED)
123
            .hasHeader("Location", "/api/authors/" + hunt.getId())
124
            .bodyJson()
125
            .isStrictlyEqualTo("""
126
                { "id": "%s", "name": "Andrew Hunt" }
127
                """.formatted(hunt.getId()));
128

129
        verify(authors).create("Andrew Hunt");
130
    }
131

132
    @Test
133
    @DisplayName("POST /api/authors with a blank name is a 400, and nothing is created")
134
    void create_blankName() {
135
        assertThat(mvc.post().uri("/api/authors")
136
                .contentType(MediaType.APPLICATION_JSON)
137
                .content("""
138
                    { "name": "" }
139
                    """))
140
            .hasStatus(HttpStatus.BAD_REQUEST)
141
            .hasContentType(MediaType.APPLICATION_PROBLEM_JSON)
142
            .bodyJson()
143
            .isStrictlyEqualTo("""
144
                {
145
                  "status": 400,
146
                  "title": "Validation failed",
147
                  "detail": "One or more fields are invalid.",
148
                  "instance": "/api/authors",
149
                  "errors": { "name": "must not be blank" }
150
                }
151
                """);
152

153
        verifyNoInteractions(authors);
154
    }
155

156
    @Test
157
    @DisplayName("PUT /api/authors/{id} replaces the author and returns it")
158
    void replace_valid() {
159
        when(authors.replace(any(), any())).thenReturn(hunt);
160

161
        assertThat(mvc.put().uri("/api/authors/{id}", hunt.getId())
162
                .contentType(MediaType.APPLICATION_JSON)
163
                .content("""
164
                    { "name": "Andrew Hunt" }
165
                    """))
166
            .hasStatusOk()
167
            .bodyJson()
168
            .isStrictlyEqualTo("""
169
                { "id": "%s", "name": "Andrew Hunt" }
170
                """.formatted(hunt.getId()));
171

172
        verify(authors).replace(hunt.getId(), "Andrew Hunt");
173
    }
174

175
    @Test
176
    @DisplayName("PUT /api/authors/{id} with a blank name is a 400, and nothing is replaced")
177
    void replace_blankName() {
178
        assertThat(mvc.put().uri("/api/authors/{id}", hunt.getId())
179
                .contentType(MediaType.APPLICATION_JSON)
180
                .content("""
181
                    { "name": "" }
182
                    """))
183
            .hasStatus(HttpStatus.BAD_REQUEST)
184
            .hasContentType(MediaType.APPLICATION_PROBLEM_JSON)
185
            .bodyJson()
186
            .isStrictlyEqualTo("""
187
                {
188
                  "status": 400,
189
                  "title": "Validation failed",
190
                  "detail": "One or more fields are invalid.",
191
                  "instance": "/api/authors/%s",
192
                  "errors": { "name": "must not be blank" }
193
                }
194
                """.formatted(hunt.getId()));
195

196
        verifyNoInteractions(authors);
197
    }
198

199
    @Test
200
    @DisplayName("PUT /api/authors/{id} for a missing author is a 404 problem")
201
    void replace_missing() {
202
        UUID id = UUID.randomUUID();
203
        when(authors.replace(id, "Andrew Hunt")).thenThrow(new NotFoundException("No author with id " + id));
204

205
        assertThat(mvc.put().uri("/api/authors/{id}", id)
206
                .contentType(MediaType.APPLICATION_JSON)
207
                .content("""
208
                    { "name": "Andrew Hunt" }
209
                    """))
210
            .hasStatus(HttpStatus.NOT_FOUND)
211
            .hasContentType(MediaType.APPLICATION_PROBLEM_JSON)
212
            .bodyJson()
213
            .isStrictlyEqualTo("""
214
                {
215
                  "status": 404,
216
                  "title": "Resource not found",
217
                  "detail": "No author with id %s",
218
                  "instance": "/api/authors/%s"
219
                }
220
                """.formatted(id, id));
221
    }
222

223
    @Test
224
    @DisplayName("DELETE /api/authors/{id} is a 204 with no body")
225
    void delete_found() {
226
        assertThat(mvc.delete().uri("/api/authors/{id}", hunt.getId()))
227
            .hasStatus(HttpStatus.NO_CONTENT)
228
            .body().isEmpty();
229

230
        verify(authors).delete(hunt.getId());
231
    }
232

233
    @Test
234
    @DisplayName("DELETE /api/authors/{id} for a missing author is a 404 problem")
235
    void delete_missing() {
236
        UUID id = UUID.randomUUID();
237
        doThrow(new NotFoundException("No author with id " + id)).when(authors).delete(id);
238

239
        assertThat(mvc.delete().uri("/api/authors/{id}", id))
240
            .hasStatus(HttpStatus.NOT_FOUND)
241
            .hasContentType(MediaType.APPLICATION_PROBLEM_JSON)
242
            .bodyJson()
243
            .isStrictlyEqualTo("""
244
                {
245
                  "status": 404,
246
                  "title": "Resource not found",
247
                  "detail": "No author with id %s",
248
                  "instance": "/api/authors/%s"
249
                }
250
                """.formatted(id, id));
251
    }
252

253
    @Test
254
    @DisplayName("DELETE /api/authors/{id} for an author who still has books is a 409 problem")
255
    void delete_stillHasBooks() {
256
        UUID id = UUID.randomUUID();
257
        doThrow(new ConflictException("Author " + id + " still has books; delete or re-author them first"))
258
            .when(authors).delete(id);
259

260
        assertThat(mvc.delete().uri("/api/authors/{id}", id))
261
            .hasStatus(HttpStatus.CONFLICT)
262
            .hasContentType(MediaType.APPLICATION_PROBLEM_JSON)
263
            .bodyJson()
264
            .isStrictlyEqualTo("""
265
                {
266
                  "status": 409,
267
                  "title": "Conflict",
268
                  "detail": "Author %s still has books; delete or re-author them first",
269
                  "instance": "/api/authors/%s"
270
                }
271
                """.formatted(id, id));
272
    }
273
}

The service decides whether an author still has books — Lesson 10 tested that with existsByAuthorsId. This test takes the decision as given (doThrow a ConflictException) and checks the part the client sees: 409, a problem body titled Conflict, and the message telling them what to do about it. Between the two lessons, the whole path from the database check to the HTTP response is covered, and neither test needs a database.

Step 8 — Run them

./mvnw test

[INFO]  T E S T S
[INFO] Running com.example.library.author.AuthorControllerTest
…
2026-10-07T09:24:22.171Z  INFO 321 --- [           main] c.e.library.author.AuthorControllerTest  : Started AuthorControllerTest in 4.364 seconds (process running for 7.15)
[INFO] Tests run: 12, Failures: 0, Errors: 0, Skipped: 0, Time elapsed: 6.750 s -- in com.example.library.author.AuthorControllerTest
[INFO] Running com.example.library.author.AuthorServiceTest
[INFO] Tests run: 9, Failures: 0, Errors: 0, Skipped: 0, Time elapsed: 0.852 s -- in com.example.library.author.AuthorServiceTest
[INFO] Running com.example.library.book.BookControllerTest
…
2026-10-07T09:24:26.203Z  INFO 321 --- [           main] c.e.library.book.BookControllerTest      : Started BookControllerTest in 1.364 seconds (process running for 11.182)
[INFO] Tests run: 10, Failures: 0, Errors: 0, Skipped: 0, Time elapsed: 2.426 s -- in com.example.library.book.BookControllerTest
[INFO] Running com.example.library.book.BookServiceTest
[INFO] Tests run: 11, Failures: 0, Errors: 0, Skipped: 0, Time elapsed: 0.130 s -- in com.example.library.book.BookServiceTest
[INFO] Running com.example.library.LibraryApplicationTests
[WARNING] Tests run: 1, Failures: 0, Errors: 0, Skipped: 1, Time elapsed: 0 s -- in com.example.library.LibraryApplicationTests
…
[INFO] Tests run: 43, Failures: 0, Errors: 0, Skipped: 1
…
[INFO] BUILD SUCCESS

The two controller classes: 12 and 10 tests, all green. The service-test counts, 9 and 11, include Lesson 10's exercises; if you wrote only its four listed tests, you'll see Tests run: 4 for BookServiceTest, no AuthorServiceTest, and a smaller total.

Unlike the service tests, each @WebMvcTest class starts a Spring context — the Spring Boot banner, and the Started … in … seconds line. The first one also pays for loading Spring's classes into the JVM (4.4 seconds here); the second starts in 1.4. That is more than a plain unit test costs, and far less than the whole application with a database. Still no PostgreSQL, no Docker, no open port.

Watch one fail

A test you've only seen pass hasn't shown you it can catch anything. Open BookController and delete @Valid from the create method's parameter, so it reads create(@RequestBody CreateBookRequest req). Run only this class:

./mvnw test -Dtest=BookControllerTest

2026-10-06T14:19:19.239Z ERROR 11678 --- [           main] c.e.library.error.ApiExceptionHandler    : Unhandled exception

java.lang.NullPointerException: Cannot invoke "com.example.library.book.Book.getId()" because "saved" is null
  at com.example.library.book.BookController.create(BookController.java:48) ~[classes/:na]
…

MockHttpServletRequest:
      HTTP Method = POST
      Request URI = /api/books
       Parameters = {}
          Headers = [Content-Type:"application/json;charset=UTF-8", Content-Length:"45"]
             Body = { "title": " ", "year": 0, "authorIds": [] }
…
Handler:
             Type = com.example.library.book.BookController
           Method = com.example.library.book.BookController#create(CreateBookRequest)
…
MockHttpServletResponse:
           Status = 500
…
             Body = {"detail":"An unexpected error occurred.","instance":"/api/books","status":500,"title":"Internal Server Error"}
…
[ERROR] Failures:
[ERROR]   BookControllerTest.create_invalid:198 [HTTP status code]
expected: 400
 but was: 500
[INFO]
[ERROR] Tests run: 10, Failures: 1, Errors: 0, Skipped: 0

create_invalid fails, and the output tells the whole story, bottom to top:

The assertion: expected: 400 but was: 500, at the hasStatus line of the test.
The exchange: because the test failed, MockMvcTester printed the request, the handler that ran, and the response. The Handler section shows the bad body reached BookController#create — nothing stopped it at the door any more.
The cause, at the top: in create, the mock had no stub for this call, returned null, and saved.getId() threw. ApiExceptionHandler's catch-all logged it and answered 500 — the same trap Step 3's stub-loosely callout describes, met for real.

Without @Valid, a bad request becomes a server error instead of a 400 that tells the client which fields to fix. Of the ten book tests, only create_invalid noticed — that one line in the controller is exactly what it exists to protect.

Put @Valid back and run the tests again: all green.

If it doesn't behave

No qualifying bean of type 'com.example.library.book.BookService'? The @MockitoBean field is missing, has a different type, or is annotated @Mock instead. The slice doesn't load @Service beans, so every constructor parameter of the controller needs a mock.
Unable to find a @SpringBootConfiguration? The test class is in a package outside com.example.library. @WebMvcTest searches upwards from the test's package for LibraryApplication; keep test packages the same as the class under test.
A 500 where you expected 200 or 201, and a NullPointerException in the log? A stub didn't match the call, so the mock returned null. Stub with any() and check the arguments afterwards, with a captor or verify, as in Steps 3 and 4.
The Mockito "self-attaching" warning? The same harmless warning as in Lesson 10.

Check yourself

Answer from memory before revealing.

Which beans does @WebMvcTest(BookController.class) load?

Why does BookControllerTest use @MockitoBean, not @Mock?

Why do the 400 tests end with verifyNoInteractions(books)?

What does isStrictlyEqualTo check that isLenientlyEqualTo doesn't?

Why does byId_missing list "instance" in the expected body?

Why does delete_missing use doThrow(...).when(books).delete(id)?

Read this next

Primary source: the Spring Framework reference on MockMvc's AssertJ integration — setting up MockMvcTester, performing requests, and every kind of assertion, including the JSON support used here. Then Spring Boot's Auto-configured Spring MVC Tests for exactly what @WebMvcTest loads and how to adjust it.

Glossary: the terms this lesson introduces are in the Glossary, under Lesson 11 — your quick-reference for every term we use.

Architecture decisions: the 5 choices this lesson makes, each with its reason, are in Architecture Decisions, under Lesson 11.

Code: the project at the end of this lesson · what changed in this lesson, exercises included.

💬 Discuss

Testing the Web Layer

What the service tests can't see

Step 1 — The test class and a first request

@Mock or @MockitoBean?

The whole body, compared strictly

Step 2 — Errors are part of the contract

Step 3 — The list endpoint: page shape and the Pageable

Step 4 — Creating a book: 201, Location, and what reaches the service

Step 5 — Validation: a 400 that names each field

Step 6 — Replace and delete

Step 7 — The author controller, and its 409

Step 8 — Run them

Watch one fail

Check yourself

Read this next

`@Mock` or `@MockitoBean`?

Step 3 — The list endpoint: page shape and the `Pageable`

Step 4 — Creating a book: `201`, `Location`, and what reaches the service

Step 5 — Validation: a `400` that names each field

Step 7 — The author controller, and its `409`