Spring Boot Course · Lesson 13

Integration Tests with @SpringBootTest

Three lessons of tests, and each one tested a layer on its own: Lesson 10 the services with fake repositories, Lesson 11 the controllers with fake services, Lesson 12 the repositories inside a test transaction. None of them has sent a request through the whole application the way a client does. This lesson does: it starts the Library API on a real server, against a real PostgreSQL, and calls it over HTTP — and it shows a bug that only such a test reports for what it is.

The win

LibraryApplicationTests running again after eight lessons switched off, and LibraryApiIntegrationTest: three integration tests that start the whole application on a random port and talk to it with RestTestClient. They create authors and books through the API, read them back, list them and hit a 409, every response compared in full. Along the way you'll break one annotation and watch three test classes give three different verdicts on the same change.

What no test has run yet

Follow one request, GET /api/books/{id}, through the running app. Tomcat hands it to a thread; Spring MVC calls BookController.byId; the controller calls BookService.getById, which calls BookRepository.findById. The repository's transaction starts and ends inside that call. Back in the controller, BookResponse.from(book) reads the book's authors, and Jackson writes the JSON.

That last part runs after the transaction is over. Lesson 9 turned Open Session in View off, so by the time the controller maps the book, the session is closed: whatever the repository didn't load is gone for good, and touching it throws LazyInitializationException. The @EntityGraph on findById is what keeps that from happening.

None of the tests so far runs that sequence:

Lesson 11's controller tests mock the service. The Book it returns was built in memory, with its authors in a plain Set; there is nothing lazy to load.
Lesson 12's repository tests run inside one transaction, so the session stays open and lazy loads quietly succeed. They count statements to notice a missing graph — but a count says "slower", not "broken".
Lesson 10's service tests run no Spring at all.

An integration test runs the parts together: the real configuration, the real beans, the real database and, here, a real HTTP server. It is slower than a slice and says less about where a failure is, so the course keeps a few of them on top of the slices, one per path through the whole stack that matters.

The integration tests start the whole application with @SpringBootTest on a random port and call it over real HTTP with RestTestClient, against the same Testcontainers PostgreSQL as Lesson 12. The request then runs on a server thread, the transactions open and close as they do in production, and the client sees exactly what a real client would.

Step 1 — Start the whole application in a test

The project has had an integration test since Lesson 1: Spring Initializr generated LibraryApplicationTests, with one empty test, contextLoads. Lesson 5 switched it off with @Disabled, because starting the application needs a database. TestcontainersConfiguration is that database now. Delete the @Disabled line and its import, and import the configuration instead:

1
package com.example.library;
2

3
import org.junit.jupiter.api.Test;
4
import org.springframework.boot.test.context.SpringBootTest;
5
import org.springframework.context.annotation.Import;      // new
6

7
@SpringBootTest
8
@Import(TestcontainersConfiguration.class)                 // new: the whole app needs a database
9
class LibraryApplicationTests {
10
    @Test void contextLoads() { }
11
}

@SpringBootTest builds the application's whole context, not a slice. It finds the configuration by searching up from the test's package for the @SpringBootApplication class ^[docs] — LibraryApplication — and loads everything it would load in production: every controller, service and repository, application.properties, Liquibase, and DataSeeder.
By default the web environment is a mock: the MVC setup is there, but no server is started ^[docs]. For contextLoads that's enough.
contextLoads has no body, and it doesn't need one. The test fails if the context can't start: a broken migration, an entity that doesn't match its table, a bean that can't be created, a seeder that throws.

Run it:

./mvnw test -Dtest=LibraryApplicationTests

[INFO] Running com.example.library.LibraryApplicationTests
…
12:46:05.271 [main] INFO org.springframework.boot.test.context.SpringBootTestContextBootstrapper -- Found @SpringBootConfiguration com.example.library.LibraryApplication for test class com.example.library.LibraryApplicationTests
…
2026-10-10T12:46:10.860Z  INFO 3203 --- [           main] tc.postgres:18                           : Container postgres:18 started in PT1.41021916S
2026-10-10T12:46:10.861Z  INFO 3203 --- [           main] tc.postgres:18                           : Container is started (JDBC URL: jdbc:postgresql://172.18.0.1:32778/test?loggerLevel=OFF)
…
2026-10-10T12:46:13.858Z  INFO 3203 --- [           main] liquibase.ui                             : Liquibase: Update has been successful. Rows affected: 0
…
2026-10-10T12:46:18.627Z  INFO 3203 --- [           main] c.e.library.LibraryApplicationTests      : Started LibraryApplicationTests in 13.074 seconds (process running for 14.771)
…
[INFO] Tests run: 1, Failures: 0, Errors: 0, Skipped: 0, Time elapsed: 15.13 s -- in com.example.library.LibraryApplicationTests
…
[INFO] BUILD SUCCESS

Found @SpringBootConfiguration com.example.library.LibraryApplication is the search from the test's package up to the application class. (@SpringBootApplication includes @SpringBootConfiguration, which is what the search looks for.)
The container and Liquibase are Lesson 12's: the same TestcontainersConfiguration, a fresh database, the whole changelog.
Started LibraryApplicationTests: every bean was created, ddl-auto=validate accepted the tables, and DataSeeder ran — the whole startup the app goes through, in a test. There is no Tomcat started line: in the mock environment no server is listening.

contextLoads checks something real: the application can start. What it doesn't check is whether the application works — no request has been sent.

Step 2 — A real server and a client for it

The integration tests go in a class of their own, next to LibraryApplicationTests in the base package: they cover both features, books and authors. The first test creates two authors and a book through the API, then follows the Location header the 201 came with and reads the book back:

1
package com.example.library;
2

3
import java.util.UUID;
4
import com.example.library.author.AuthorRepository;
5
import com.example.library.author.AuthorResponse;
6
import com.example.library.book.BookRepository;
7
import com.example.library.book.BookResponse;
8
import org.junit.jupiter.api.BeforeEach;
9
import org.junit.jupiter.api.DisplayName;
10
import org.junit.jupiter.api.Test;
11
import org.springframework.beans.factory.annotation.Autowired;
12
import org.springframework.boot.resttestclient.autoconfigure.AutoConfigureRestTestClient;
13
import org.springframework.boot.test.context.SpringBootTest;
14
import org.springframework.boot.test.context.SpringBootTest.WebEnvironment;
15
import org.springframework.context.annotation.Import;
16
import org.springframework.http.MediaType;
17
import org.springframework.test.json.JsonCompareMode;
18
import org.springframework.test.web.servlet.client.EntityExchangeResult;
19
import org.springframework.test.web.servlet.client.RestTestClient;
20

21
@SpringBootTest(webEnvironment = WebEnvironment.RANDOM_PORT)   // the whole app, on a real server and a free port
22
@AutoConfigureRestTestClient                                   // a RestTestClient pointed at that server
23
@Import(TestcontainersConfiguration.class)                     // ...and a real PostgreSQL
24
class LibraryApiIntegrationTest {
25

26
    @Autowired RestTestClient client;          // sends real HTTP requests to the running app
27
    @Autowired BookRepository books;           // used only to empty the tables
28
    @Autowired AuthorRepository authors;
29

30
    @BeforeEach
31
    void emptyTables() {
32
        books.deleteAll();                     // books first: their book_author rows point at the authors
33
        authors.deleteAll();
34
    }
35

36
    @Test
37
    @DisplayName("a book created with POST can be read back from its Location")
38
    void create_thenReadBack() {
39
        UUID hunt = createAuthor("Andrew Hunt");
40
        UUID thomas = createAuthor("David Thomas");
41

42
        EntityExchangeResult<BookResponse> created = client.post().uri("/api/books")
43
            .contentType(MediaType.APPLICATION_JSON)
44
            .body("""
45
                {
46
                  "title": "The Pragmatic Programmer",
47
                  "year": 1999,
48
                  "authorIds": ["%s", "%s"]
49
                }
50
                """.formatted(hunt, thomas))
51
            .exchange()
52
            .expectStatus().isCreated()
53
            .expectBody(BookResponse.class)
54
            .returnResult();
55
        UUID id = created.getResponseBody().id();
56

57
        client.get().uri(created.getResponseHeaders().getLocation())   // follow the Location header
58
            .exchange()
59
            .expectStatus().isOk()
60
            .expectHeader().contentType(MediaType.APPLICATION_JSON)
61
            .expectBody().json("""
62
                {
63
                  "id": "%s",
64
                  "title": "The Pragmatic Programmer",
65
                  "year": 1999,
66
                  "authors": [
67
                    { "id": "%s", "name": "Andrew Hunt" },
68
                    { "id": "%s", "name": "David Thomas" }
69
                  ]
70
                }
71
                """.formatted(id, hunt, thomas), JsonCompareMode.STRICT);
72
    }
73

74
    // POSTs an author and returns the id the API gave it.
75
    UUID createAuthor(String name) {
76
        return client.post().uri("/api/authors")
77
            .contentType(MediaType.APPLICATION_JSON)
78
            .body("""
79
                { "name": "%s" }
80
                """.formatted(name))
81
            .exchange()
82
            .expectStatus().isCreated()
83
            .expectBody(AuthorResponse.class)
84
            .returnResult()
85
            .getResponseBody()
86
            .id();
87
    }
88
}

The three annotations on the class:

webEnvironment = WebEnvironment.RANDOM_PORT starts the embedded Tomcat, as ./mvnw spring-boot:run does, but on a random free port ^[docs]. The tests never collide with an app you have running on 8080, or with another test run.
@AutoConfigureRestTestClient gives the test a RestTestClient already pointed at that port ^[docs]. RestTestClient is Spring's HTTP client for tests: build a request, exchange() it, then chain expectations on the response ^[docs]. Nothing to add to pom.xml: it comes with spring-boot-starter-webmvc-test, the test starter from Lesson 11.
@Import(TestcontainersConfiguration.class) is Lesson 12's database, as in Step 1.

And the test:

Request bodies are JSON text, as in Lesson 11: what a client sends, not a serialized record.
expectBody(BookResponse.class) and returnResult() leave the expectation chain with the response in hand. The test needs two things from it that it can't know in advance: the new book's id, read from the body, and its address, from the Location header. Reading the body into BookResponse is a convenience for getting the id; what the API sends is checked by the strict JSON below.
json(…, JsonCompareMode.STRICT) is RestTestClient's version of Lesson 11's isStrictlyEqualTo: every field, nothing extra, arrays in order.
createAuthor is a helper, not a test: it posts an author, expects a 201, and returns the id. The book test needs real authors in the database before it can post a book that points at them.

Why the tables are emptied first

Lesson 12's tests left nothing behind, because each ran in a transaction that was rolled back. That trick doesn't work here. The test and the server run on different threads, each with its own transactions, so a @Transactional test would roll back only its own: whatever the server committed stays committed ^[docs]. And Spring's test framework caches the application context, so every test in the class talks to the same server and the same database ^[docs]. Whatever one test creates is there for the next.

There is also data before the first test: DataSeeder is a bean of the application, so it ran when the context started and added its three books — Clean Code, Effective Java and Domain-Driven Design.

So every integration test starts from empty tables: @BeforeEach deletes all books, then all authors, through the repositories, and the test then creates through the API whatever it needs. The order is the one the foreign keys require: deleteAll on the books removes each book's book_author rows with it, and only then can the authors go. Each test can then assert on exact lists and totals, whatever ran before it.

Step 3 — Run it

./mvnw test -Dtest=LibraryApiIntegrationTest

[INFO] Running com.example.library.LibraryApiIntegrationTest
…
2026-10-10T12:46:41.198Z  INFO 3817 --- [           main] o.s.boot.tomcat.TomcatWebServer          : Tomcat initialized with port 0 (http)
…
2026-10-10T12:46:45.174Z  INFO 3817 --- [           main] tc.postgres:18                           : Container postgres:18 started in PT1.588048987S
…
2026-10-10T12:46:51.273Z  INFO 3817 --- [           main] o.s.boot.tomcat.TomcatWebServer          : Tomcat started on port 43479 (http) with context path '/'
2026-10-10T12:46:51.284Z  INFO 3817 --- [           main] c.e.library.LibraryApiIntegrationTest    : Started LibraryApiIntegrationTest in 12.474 seconds (process running for 14.126)
…
2026-10-10T12:46:52.805Z  INFO 3817 --- [o-auto-1-exec-1] o.a.c.c.C.[Tomcat].[localhost].[/]       : Initializing Spring DispatcherServlet 'dispatcherServlet'
…
[INFO] Tests run: 1, Failures: 0, Errors: 0, Skipped: 0, Time elapsed: 15.22 s -- in com.example.library.LibraryApiIntegrationTest
…
[INFO] BUILD SUCCESS

port 0, then port 43479. Port 0 asks the operating system for any free port; Tomcat got 43479 this time, and RestTestClient was pointed at it. Your number will differ on every run.
[o-auto-1-exec-1] is the thread name in the log. Everything before it ran on main, the test's thread; the first request arrived on one of Tomcat's worker threads, exactly as in the running app. That separation is why nothing a request writes can be rolled back by the test.
One test, green: two authors and a book created over HTTP, the Location followed, the JSON exactly as expected.

Step 4 — One change, three verdicts

Open BookRepository and delete the @EntityGraph line above findById, as Lesson 12 did for findAll:


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

3
import java.util.Optional;                               // new: findById's return type
4
import java.util.UUID;
5
import org.springframework.data.domain.Page;
6
import org.springframework.data.domain.Pageable;
7
import org.springframework.data.jpa.repository.EntityGraph;   // new
8
import org.springframework.data.jpa.repository.JpaRepository;
9

10
public interface BookRepository extends JpaRepository<Book, UUID> {
11

12
    @Override
13
    @EntityGraph(attributePaths = "authors")
14
    Page<Book> findAll(Pageable pageable);
15

16
    @Override
17
    Optional<Book> findById(UUID id);
18

19
    @EntityGraph(attributePaths = "authors")
20
    Page<Book> findByAuthorsId(UUID authorId, Pageable pageable);
21

22
    // Is any book still linked to this author? (Spring Data derives an EXISTS query.)
23
    boolean existsByAuthorsId(UUID authorId);
24
}

Run the book's controller tests, its repository tests and the new integration test together:

./mvnw test -Dtest='BookControllerTest,BookRepositoryTest,LibraryApiIntegrationTest'

[INFO] Running com.example.library.LibraryApiIntegrationTest
…
2026-10-10T12:47:33.092Z ERROR 4459 --- [o-auto-1-exec-4] c.e.library.error.ApiExceptionHandler    : Unhandled exception

org.hibernate.LazyInitializationException: Cannot lazily initialize collection of role 'com.example.library.book.Book.authors' with key '01a125da-b6c1-75b3-9577-162b6e2147c8' (no session)
  at org.hibernate.collection.spi.AbstractPersistentCollection.throwLazyInitializationException(AbstractPersistentCollection.java:664) ~[hibernate-core-7.4.5.Final.jar:7.4.5.Final]
…
2026-10-10T12:47:33.116Z ERROR 4459 --- [           main] o.s.t.web.servlet.client.ExchangeResult  : Request details for assertion failure:

> GET http://localhost:37989/api/books/01a125da-b6c1-75b3-9577-162b6e2147c8
> RestTestClient-Request-Id: [4]
> Content-Length: [0]

0 bytes of content (unknown content-type).

< 500 INTERNAL_SERVER_ERROR Internal Server Error
< connection: [close]
< content-type: [application/problem+json]
< date: [Sat, 10 Oct 2026 12:47:33 GMT]
< transfer-encoding: [chunked]

{"detail":"An unexpected error occurred.","instance":"/api/books/01a125da-b6c1-75b3-9577-162b6e2147c8","status":500,"title":"Internal Server Error"}

[ERROR] Tests run: 1, Failures: 1, Errors: 0, Skipped: 0, Time elapsed: 18.04 s <<< FAILURE! -- in com.example.library.LibraryApiIntegrationTest
[ERROR] com.example.library.LibraryApiIntegrationTest.create_thenReadBack -- Time elapsed: 1.278 s <<< FAILURE!
java.lang.AssertionError: Status expected:<200 OK> but was:<500 INTERNAL_SERVER_ERROR>
…
  at com.example.library.LibraryApiIntegrationTest.create_thenReadBack(LibraryApiIntegrationTest.java:59)

[INFO] Running com.example.library.book.BookControllerTest
…
[INFO] Tests run: 10, Failures: 0, Errors: 0, Skipped: 0, Time elapsed: 1.928 s -- in com.example.library.book.BookControllerTest
[INFO] Running com.example.library.book.BookRepositoryTest
…
[ERROR] Tests run: 9, Failures: 1, Errors: 0, Skipped: 0, Time elapsed: 3.727 s <<< FAILURE! -- in com.example.library.book.BookRepositoryTest
[ERROR] com.example.library.book.BookRepositoryTest.findById_oneStatement -- Time elapsed: 0.051 s <<< FAILURE!
org.opentest4j.AssertionFailedError:
[SQL statements]
expected: 1L
 but was: 2L
  at com.example.library.book.BookRepositoryTest.findById_oneStatement(BookRepositoryTest.java:94)
…
[ERROR] Tests run: 20, Failures: 2, Errors: 0, Skipped: 0
…
[INFO] BUILD FAILURE

The same one-line change, three verdicts:

BookControllerTest: all 10 green. The service is a mock, and the Book it returns holds its authors in a plain in-memory Set. Whatever the repository does is invisible here — as it should be for a web-layer test.
BookRepositoryTest: expected: 1L but was: 2L. Lesson 12's guard caught it: findById now costs a second statement to load the authors. Read on its own, that sounds like a performance regression, one extra query for one book. Someone in a hurry might even "fix" the test by changing the 1 to a 2.
LibraryApiIntegrationTest: a 500. In the real app, the extra statement never runs. BookService.getById returns, the repository's session is closed, and BookResponse.from in the controller touches book.getAuthors() — so Hibernate throws LazyInitializationException (no session), Lesson 7's catch-all logs it as Unhandled exception, and the client gets An unexpected error occurred. Every request for a single book fails.

That is what the integration test adds: not a different bug, but the true size of one. RestTestClient also prints the whole exchange when an expectation fails — the request, the status, the headers and the problem body — and the server's log with the cause is right above it, because the server runs in the same JVM as the test.

Put the @EntityGraph(attributePaths = "authors") line back above findById before you go on.

Why not @Transactional, with no server?

You will meet integration tests written the other way: @SpringBootTest in its default mock environment, with @Transactional on the class so every test is rolled back, like Lesson 12's. Without a server, the request runs on the test's own thread, inside the test's transaction — and that transaction keeps the session open through the controller, just as it did in Lesson 12. With findById's graph missing, BookResponse.from loads the authors lazily and the test passes, while the real app answers 500. The rollback is convenient, but it changes the code under test: the transactions the app relies on are no longer the ones that run.

Step 5 — The list

The second test fills the database with two books and lists them, the way Lesson 8 taught the API to: the first page, sorted by title, with the page metadata. Add it below the first, and a createBook helper below createAuthor:


19 collapsed lines
1
package com.example.library;
2

3
import java.util.UUID;
4
import com.example.library.author.AuthorRepository;
5
import com.example.library.author.AuthorResponse;
6
import com.example.library.book.BookRepository;
7
import com.example.library.book.BookResponse;
8
import org.junit.jupiter.api.BeforeEach;
9
import org.junit.jupiter.api.DisplayName;
10
import org.junit.jupiter.api.Test;
11
import org.springframework.beans.factory.annotation.Autowired;
12
import org.springframework.boot.resttestclient.autoconfigure.AutoConfigureRestTestClient;
13
import org.springframework.boot.test.context.SpringBootTest;
14
import org.springframework.boot.test.context.SpringBootTest.WebEnvironment;
15
import org.springframework.context.annotation.Import;
16
import org.springframework.http.MediaType;
17
import org.springframework.test.json.JsonCompareMode;
18
import org.springframework.test.web.servlet.client.EntityExchangeResult;
19
import org.springframework.test.web.servlet.client.RestTestClient;
20

53 collapsed lines
21
@SpringBootTest(webEnvironment = WebEnvironment.RANDOM_PORT)   // the whole app, on a real server and a free port
22
@AutoConfigureRestTestClient                                   // a RestTestClient pointed at that server
23
@Import(TestcontainersConfiguration.class)                     // ...and a real PostgreSQL
24
class LibraryApiIntegrationTest {
25

26
    @Autowired RestTestClient client;          // sends real HTTP requests to the running app
27
    @Autowired BookRepository books;           // used only to empty the tables
28
    @Autowired AuthorRepository authors;
29

30
    @BeforeEach
31
    void emptyTables() {
32
        books.deleteAll();                     // books first: their book_author rows point at the authors
33
        authors.deleteAll();
34
    }
35

36
    @Test
37
    @DisplayName("a book created with POST can be read back from its Location")
38
    void create_thenReadBack() {
39
        UUID hunt = createAuthor("Andrew Hunt");
40
        UUID thomas = createAuthor("David Thomas");
41

42
        EntityExchangeResult<BookResponse> created = client.post().uri("/api/books")
43
            .contentType(MediaType.APPLICATION_JSON)
44
            .body("""
45
                {
46
                  "title": "The Pragmatic Programmer",
47
                  "year": 1999,
48
                  "authorIds": ["%s", "%s"]
49
                }
50
                """.formatted(hunt, thomas))
51
            .exchange()
52
            .expectStatus().isCreated()
53
            .expectBody(BookResponse.class)
54
            .returnResult();
55
        UUID id = created.getResponseBody().id();
56

57
        client.get().uri(created.getResponseHeaders().getLocation())   // follow the Location header
58
            .exchange()
59
            .expectStatus().isOk()
60
            .expectHeader().contentType(MediaType.APPLICATION_JSON)
61
            .expectBody().json("""
62
                {
63
                  "id": "%s",
64
                  "title": "The Pragmatic Programmer",
65
                  "year": 1999,
66
                  "authors": [
67
                    { "id": "%s", "name": "Andrew Hunt" },
68
                    { "id": "%s", "name": "David Thomas" }
69
                  ]
70
                }
71
                """.formatted(id, hunt, thomas), JsonCompareMode.STRICT);
72
    }
73

74
    @Test
75
    @DisplayName("GET /api/books lists every book in title order, with the page metadata")
76
    void list_allBooksByTitle() {
77
        UUID hunt = createAuthor("Andrew Hunt");
78
        UUID thomas = createAuthor("David Thomas");
79
        UUID evans = createAuthor("Eric Evans");
80
        UUID pragmatic = createBook("""
81
            { "title": "The Pragmatic Programmer", "year": 1999, "authorIds": ["%s", "%s"] }
82
            """.formatted(hunt, thomas));
83
        UUID ddd = createBook("""
84
            { "title": "Domain-Driven Design", "year": 2003, "authorIds": ["%s"] }
85
            """.formatted(evans));
86

87
        client.get().uri("/api/books")
88
            .exchange()
89
            .expectStatus().isOk()
90
            .expectBody().json("""
91
                {
92
                  "content": [
93
                    {
94
                      "id": "%s",
95
                      "title": "Domain-Driven Design",
96
                      "year": 2003,
97
                      "authors": [
98
                        { "id": "%s", "name": "Eric Evans" }
99
                      ]
100
                    },
101
                    {
102
                      "id": "%s",
103
                      "title": "The Pragmatic Programmer",
104
                      "year": 1999,
105
                      "authors": [
106
                        { "id": "%s", "name": "Andrew Hunt" },
107
                        { "id": "%s", "name": "David Thomas" }
108
                      ]
109
                    }
110
                  ],
111
                  "page": { "size": 20, "number": 0, "totalElements": 2, "totalPages": 1 }
112
                }
113
                """.formatted(ddd, evans, pragmatic, hunt, thomas), JsonCompareMode.STRICT);
114
    }
115

15 collapsed lines
116
    // POSTs an author and returns the id the API gave it.
117
    UUID createAuthor(String name) {
118
        return client.post().uri("/api/authors")
119
            .contentType(MediaType.APPLICATION_JSON)
120
            .body("""
121
                { "name": "%s" }
122
                """.formatted(name))
123
            .exchange()
124
            .expectStatus().isCreated()
125
            .expectBody(AuthorResponse.class)
126
            .returnResult()
127
            .getResponseBody()
128
            .id();
129
    }
130

131
    // POSTs a book (the request body as JSON) and returns the id the API gave it.
132
    UUID createBook(String json) {
133
        return client.post().uri("/api/books")
134
            .contentType(MediaType.APPLICATION_JSON)
135
            .body(json)
136
            .exchange()
137
            .expectStatus().isCreated()
138
            .expectBody(BookResponse.class)
139
            .returnResult()
140
            .getResponseBody()
141
            .id();
142
    }
143
}

The books go in out of title order — The Pragmatic Programmer first — and the list must come back as Domain-Driven Design, then The Pragmatic Programmer: the controller's default sort from Lesson 8, not the insertion order.
The page block is Lesson 8's stable shape, which application.properties switches on. Lesson 11 checked it with a mocked page; here the numbers come from PostgreSQL.
totalElements: 2 holds only because the tables were emptied. Without emptyTables, the list would also hold DataSeeder's three books and the first test's book.

Step 6 — An error that crosses the layers

The last test takes one error path end to end. Lesson 7's 409 needs every layer to cooperate: the controller routes the DELETE, AuthorService asks BookRepository.existsByAuthorsId against real book_author rows, and ApiExceptionHandler turns the ConflictException into a problem response. Add it below the list test, with the HttpStatus import:


15 collapsed lines
1
package com.example.library;
2

3
import java.util.UUID;
4
import com.example.library.author.AuthorRepository;
5
import com.example.library.author.AuthorResponse;
6
import com.example.library.book.BookRepository;
7
import com.example.library.book.BookResponse;
8
import org.junit.jupiter.api.BeforeEach;
9
import org.junit.jupiter.api.DisplayName;
10
import org.junit.jupiter.api.Test;
11
import org.springframework.beans.factory.annotation.Autowired;
12
import org.springframework.boot.resttestclient.autoconfigure.AutoConfigureRestTestClient;
13
import org.springframework.boot.test.context.SpringBootTest;
14
import org.springframework.boot.test.context.SpringBootTest.WebEnvironment;
15
import org.springframework.context.annotation.Import;
16
import org.springframework.http.HttpStatus;
100 collapsed lines
17
import org.springframework.http.MediaType;
18
import org.springframework.test.json.JsonCompareMode;
19
import org.springframework.test.web.servlet.client.EntityExchangeResult;
20
import org.springframework.test.web.servlet.client.RestTestClient;
21

22
@SpringBootTest(webEnvironment = WebEnvironment.RANDOM_PORT)   // the whole app, on a real server and a free port
23
@AutoConfigureRestTestClient                                   // a RestTestClient pointed at that server
24
@Import(TestcontainersConfiguration.class)                     // ...and a real PostgreSQL
25
class LibraryApiIntegrationTest {
26

27
    @Autowired RestTestClient client;          // sends real HTTP requests to the running app
28
    @Autowired BookRepository books;           // used only to empty the tables
29
    @Autowired AuthorRepository authors;
30

31
    @BeforeEach
32
    void emptyTables() {
33
        books.deleteAll();                     // books first: their book_author rows point at the authors
34
        authors.deleteAll();
35
    }
36

37
    @Test
38
    @DisplayName("a book created with POST can be read back from its Location")
39
    void create_thenReadBack() {
40
        UUID hunt = createAuthor("Andrew Hunt");
41
        UUID thomas = createAuthor("David Thomas");
42

43
        EntityExchangeResult<BookResponse> created = client.post().uri("/api/books")
44
            .contentType(MediaType.APPLICATION_JSON)
45
            .body("""
46
                {
47
                  "title": "The Pragmatic Programmer",
48
                  "year": 1999,
49
                  "authorIds": ["%s", "%s"]
50
                }
51
                """.formatted(hunt, thomas))
52
            .exchange()
53
            .expectStatus().isCreated()
54
            .expectBody(BookResponse.class)
55
            .returnResult();
56
        UUID id = created.getResponseBody().id();
57

58
        client.get().uri(created.getResponseHeaders().getLocation())   // follow the Location header
59
            .exchange()
60
            .expectStatus().isOk()
61
            .expectHeader().contentType(MediaType.APPLICATION_JSON)
62
            .expectBody().json("""
63
                {
64
                  "id": "%s",
65
                  "title": "The Pragmatic Programmer",
66
                  "year": 1999,
67
                  "authors": [
68
                    { "id": "%s", "name": "Andrew Hunt" },
69
                    { "id": "%s", "name": "David Thomas" }
70
                  ]
71
                }
72
                """.formatted(id, hunt, thomas), JsonCompareMode.STRICT);
73
    }
74

75
    @Test
76
    @DisplayName("GET /api/books lists every book in title order, with the page metadata")
77
    void list_allBooksByTitle() {
78
        UUID hunt = createAuthor("Andrew Hunt");
79
        UUID thomas = createAuthor("David Thomas");
80
        UUID evans = createAuthor("Eric Evans");
81
        UUID pragmatic = createBook("""
82
            { "title": "The Pragmatic Programmer", "year": 1999, "authorIds": ["%s", "%s"] }
83
            """.formatted(hunt, thomas));
84
        UUID ddd = createBook("""
85
            { "title": "Domain-Driven Design", "year": 2003, "authorIds": ["%s"] }
86
            """.formatted(evans));
87

88
        client.get().uri("/api/books")
89
            .exchange()
90
            .expectStatus().isOk()
91
            .expectBody().json("""
92
                {
93
                  "content": [
94
                    {
95
                      "id": "%s",
96
                      "title": "Domain-Driven Design",
97
                      "year": 2003,
98
                      "authors": [
99
                        { "id": "%s", "name": "Eric Evans" }
100
                      ]
101
                    },
102
                    {
103
                      "id": "%s",
104
                      "title": "The Pragmatic Programmer",
105
                      "year": 1999,
106
                      "authors": [
107
                        { "id": "%s", "name": "Andrew Hunt" },
108
                        { "id": "%s", "name": "David Thomas" }
109
                      ]
110
                    }
111
                  ],
112
                  "page": { "size": 20, "number": 0, "totalElements": 2, "totalPages": 1 }
113
                }
114
                """.formatted(ddd, evans, pragmatic, hunt, thomas), JsonCompareMode.STRICT);
115
    }
116

117
    @Test
118
    @DisplayName("DELETE of an author who still has books is a 409, and the author stays")
119
    void deleteAuthor_withBooks_conflict() {
120
        UUID evans = createAuthor("Eric Evans");
121
        createBook("""
122
            { "title": "Domain-Driven Design", "year": 2003, "authorIds": ["%s"] }
123
            """.formatted(evans));
124

125
        client.delete().uri("/api/authors/{id}", evans)
126
            .exchange()
127
            .expectStatus().isEqualTo(HttpStatus.CONFLICT)
128
            .expectHeader().contentType(MediaType.APPLICATION_PROBLEM_JSON)
129
            .expectBody().json("""
130
                {
131
                  "status": 409,
132
                  "title": "Conflict",
133
                  "detail": "Author %s still has books; delete or re-author them first",
134
                  "instance": "/api/authors/%s"
135
                }
136
                """.formatted(evans, evans), JsonCompareMode.STRICT);
137

138
        client.get().uri("/api/authors/{id}", evans)   // the refused delete changed nothing
139
            .exchange()
140
            .expectStatus().isOk()
141
            .expectBody().json("""
142
                { "id": "%s", "name": "Eric Evans" }
143
                """.formatted(evans), JsonCompareMode.STRICT);
144
    }
145

27 collapsed lines
146
    // POSTs an author and returns the id the API gave it.
147
    UUID createAuthor(String name) {
148
        return client.post().uri("/api/authors")
149
            .contentType(MediaType.APPLICATION_JSON)
150
            .body("""
151
                { "name": "%s" }
152
                """.formatted(name))
153
            .exchange()
154
            .expectStatus().isCreated()
155
            .expectBody(AuthorResponse.class)
156
            .returnResult()
157
            .getResponseBody()
158
            .id();
159
    }
160

161
    // POSTs a book (the request body as JSON) and returns the id the API gave it.
162
    UUID createBook(String json) {
163
        return client.post().uri("/api/books")
164
            .contentType(MediaType.APPLICATION_JSON)
165
            .body(json)
166
            .exchange()
167
            .expectStatus().isCreated()
168
            .expectBody(BookResponse.class)
169
            .returnResult()
170
            .getResponseBody()
171
            .id();
172
    }
173
}

uri("/api/authors/{id}", evans) fills the {id} template variable, as MockMvcTester's uri did in Lesson 11.
The problem body is Lesson 7's, with the instance Spring fills in from the request path.
The second request checks what the 409 promises: the author was not deleted. A status alone can't show that; Lesson 10 checked it with verify(..., never()) on a mock, and here the author is simply still there to read.

Step 7 — Run it

Run the whole suite:

./mvnw test

[INFO] Running com.example.library.LibraryApiIntegrationTest
…
2026-10-10T12:48:31.891Z  INFO 5902 --- [           main] tc.postgres:18                           : Container postgres:18 started in PT1.395566085S
…
2026-10-10T12:48:38.947Z  INFO 5902 --- [           main] c.e.library.LibraryApiIntegrationTest    : Started LibraryApiIntegrationTest in 13.396 seconds (process running for 15.145)
…
[INFO] Tests run: 3, Failures: 0, Errors: 0, Skipped: 0, Time elapsed: 16.59 s -- in com.example.library.LibraryApiIntegrationTest
[INFO] Running com.example.library.author.AuthorControllerTest
…
[INFO] Tests run: 12, Failures: 0, Errors: 0, Skipped: 0, Time elapsed: 1.982 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.561 s -- in com.example.library.author.AuthorServiceTest
[INFO] Running com.example.library.book.BookControllerTest
…
[INFO] Tests run: 10, Failures: 0, Errors: 0, Skipped: 0, Time elapsed: 1.065 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.058 s -- in com.example.library.book.BookServiceTest
[INFO] Running com.example.library.book.BookRepositoryTest
…
2026-10-10T12:48:47.326Z  INFO 5902 --- [           main] tc.postgres:18                           : Container postgres:18 started in PT1.634578317S
…
2026-10-10T12:48:48.226Z  INFO 5902 --- [           main] c.e.library.book.BookRepositoryTest      : Started BookRepositoryTest in 2.944 seconds (process running for 24.425)
…
[INFO] Tests run: 9, Failures: 0, Errors: 0, Skipped: 0, Time elapsed: 3.683 s -- in com.example.library.book.BookRepositoryTest
[INFO] Running com.example.library.LibraryApplicationTests
…
2026-10-10T12:48:50.940Z  INFO 5902 --- [           main] tc.postgres:18                           : Container postgres:18 started in PT1.673564397S
…
2026-10-10T12:48:51.592Z  INFO 5902 --- [           main] c.e.library.LibraryApplicationTests      : Started LibraryApplicationTests in 2.767 seconds (process running for 27.79)
[INFO] Tests run: 1, Failures: 0, Errors: 0, Skipped: 0, Time elapsed: 2.843 s -- in com.example.library.LibraryApplicationTests
…
[INFO] Tests run: 55, Failures: 0, Errors: 0, Skipped: 0
…
[INFO] BUILD SUCCESS

55 tests, and for the first time since Lesson 5 none skipped. As before, the service-test counts include Lesson 10's exercises, so your total may be smaller.

Count the Container postgres:18 started lines: three. Spring's test framework keeps every application context it builds and hands it to the next test class with the same configuration — context caching. The cache key is the configuration itself: the annotations, the imported classes, the properties ^[docs]. Three of the test classes need a database, and all three are configured differently — a RANDOM_PORT context with a RestTestClient, a @DataJpaTest slice with statistics on, a mock-environment context — so each gets a context of its own, and each context its own container bean. A second class annotated exactly like LibraryApiIntegrationTest would reuse its context and its container, and skip the start-up altogether. That is a reason to keep the integration tests' annotations identical as their number grows.

The layers now each have their tests, and the stack as a whole has its own:

Service tests (Lesson 10) check the decisions in plain Java, in milliseconds.
Controller tests (Lesson 11) check routing, validation, JSON and problem responses, without a database.
Repository tests (Lesson 12) check the queries, the fetch plans and the writes on real PostgreSQL.
Integration tests check that the pieces work together, the way a client uses them. They are the slowest and the least precise about where a failure is, so there are three of them, one per path that crosses every layer, not one per endpoint.

If it doesn't behave

Could not find a valid Docker environment? As in Lesson 12: the integration tests need Docker running, because they start the same PostgreSQL container.
The Mockito "self-attaching" warning? The same harmless warning as in Lesson 10; spring-boot-starter-webmvc-test brings Mockito into every test run.

Check yourself

Answer from memory before revealing.

What does @SpringBootTest load that @WebMvcTest does not?

Why wouldn't @Transactional clean up after a RANDOM_PORT test?

Why does a missing graph on findById make the real API answer 500?

Why does every integration test start by emptying the tables?

When do two test classes share one application context and container?

Read this next

Primary source: Spring Boot's reference on Testing Spring Boot Applications, up to and including "Testing With a Running Server" — the web environments, how the configuration is found, and the clients for a running server. Then Spring Framework's page on Context Caching, for exactly what makes two test classes share a context.

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

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

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

💬 Discuss