Last updated: 2026-11-10

  1. Learn
  2. ›
  3. Spring Boot
  4. ›
  5. Integration Tests

Adding Integration Tests in Spring Boot with Testcontainers

Integration tests check our Spring Boot API together with a real database engine. We use a small REST endpoint backed by MySQL to set up Testcontainers, send HTTP requests with RESTAssured and reset the test data before each scenario.

Dependencies and test scope

An integration test is meant to test the interaction of multiple parts of the application. So in our Spring Boot context it would be great to examine the running app including the database (for example MySQL or PostgreSQL). An embedded database would not be optimal for this, as there can be significant differences to the actual database, and therefore certain features may not work or errors may be missed.

For this purpose, there is the Testcontainers library to start a Docker image of exactly the database that is used by the developer and later in production. To write an integration test for our application, we start by adding the required dependencies.

Adding dependencies to our build.gradle

This example targets Spring Boot 4 and Testcontainers 2. The MVC test starter provides the Spring test support, and spring-boot-testcontainers connects container services to the application. The MySQL module is now named testcontainers-mysql, with MySQLContainer in org.testcontainers.mysql. Let Spring Boot manage dependency versions. RESTAssured sends requests to the running server.

Starting the application context

To centralize the recurring logic of our test classes, we first create an abstract base class from which our IT classes will inherit later on. The first version of this class looks like this:

First version of BaseIT.java

By using the @SpringBootTest annotation, Spring Boot will load the full application context and thus enables us to make good integration tests. With @ActiveProfiles we define that the application is started with the profile "it". If needed we can use this profile to activate special settings in our code.

By setting the variable webEnvironment to RANDOM_PORT the application will be started under a random and available port, so during testing there shouldn't be any conflict. We set RESTAssured's port before each test, after Spring has injected the actual server port. This example assumes sequential execution because RESTAssured's default configuration is static.

Starting the database container

Now we want to configure a database that is exclusively available for our tests. For this we extend our BaseIT.java with the following code.

Testcontainers setup to provide MySQL as a container

The proper container from Testcontainers is initialized with the given image "mysql:26.10". Ideally this should exactly match the version that is also used in production.

Originally a special method annotated with @DynamicPropertySource was required to provide the connection credentials to the application context. With Spring Boot 3.1.0 that's not required anymore for most databases and simply adding @ServiceConnection will do exactly that.

The static container is shared by the test classes within this JVM. Cross-run reuse is a separate, experimental Testcontainers feature, enabled with withReuse(true) and a local opt-in. We leave it disabled here, especially for CI, so containers can be cleaned up after the test run.

Finally we are starting the container with a call to start(). This approach ensures that all extending classes will reuse the same container. Depending on how we initialize our database schema - for example with Flyway or Liquibase - this will be automatically applied to our test database within the container during context startup.

Running the tests

With this preparation, we can write our first test class. Let's assume that the following @RestController already exists. The referenced service returns all entries that exist in the "Test" table.

Example endpoint in our Spring Boot app

We can now create a class TestControllerIT that extends our abstract base class. The test method sends a GET request to the existing endpoint using RestAssured. We're asserting that the HTTP status and the response JSON are matching our expectations.

TestControllerIT of our Spring Boot app

Even though our database schema is already initialized, we still lack explicit test data that we need for our test. For this we use the Spring annotation @Sql(...), which executes two scripts and thus puts our database into a known state. In our case, there is now exactly one entry in the Test table that we expect as a result.

Wiping out all data with src/test/resources/data/clearAll.sql

Create a single table entry with testData.sql

Docker must be available and running when the test is executed. When we run the test for the first time we have to wait a bit for our container to be available. It may be useful to already cache the image beforehand using docker pull mysql:26.10 to avoid issues with the download. Our test should now go through without errors.

Conclusion

With the setup described, we have created a way to check the behavior of our application including the database from a high level. With this we have a very useful addition to our unit tests. Testcontainers also offers support for other services such as RabbitMQ, so we can flexibly add such containers to BaseIT as needed.

In the Professional plan, Bootify offers the option to activate Testcontainers. This initializes the Spring Boot application including the described setup, depending on the selected database. It also generates the IT classes and scripts according to the tables and REST controllers created.

See Pricing
or read quickstart

Further readings

Testcontainers for Java
Spring Boot Testcontainers support
Docker Hub for finding images
@Sql and @SqlMergeMode explanation
Where to look for the .testcontainers.properties