Getting started with Testcontainers for Java

Testcontainers is a testing library that provides easy and lightweight APIs for bootstrapping integration tests with real services wrapped in Docker containers. Using Testcontainers, you can write tests talking to the same type of services you use in production without mocks or in-memory services.
Let us look at how we can use Testcontainers for testing a Java application using a Postgres database.
Create a Java project with Maven build tool support from your favorite IDE. We are using Maven in this article, but you can use Gradle if you prefer. Once the project is created, add the following dependencies to the pom.xml.
We have added a Postgres JDBC driver for talking to the Postgres database, logback-classic for logging and junit-jupiter for testing with JUnit 5. Also, we have used the latest version of maven-surefire-plugin to support JUnit 5 tests.
We are going to create CustomerService class to manage customer details.
First let us create a Customer class as follows:
Create DBConnectionProvider.java class to hold JDBC connection parameters and create a method to get database Connection as follows:
Create CustomerService.java class and add the following code:
Let us understand what is going on in CustomerService class.
We are calling connectionProvider.getConnection() method to get a database Connection using JDBC API
We have the createCustomersTableIfNotExists() method that creates the customers table if it does not already exist.
We have createCustomer() method that inserts a new customer record into the database.
We have the getAllCustomers() method that fetches all rows from customers table, populates data into Customer objects and returns a list of Customer objects.
Now let us see how we can test CustomerService logic using Testcontainers.
Before writing Testcontainers based tests let’s add Testcontainers dependencies in pom.xml as follows:
As we are using a Postgres database for our application, we added the Testcontainers Postgres module as a test dependency.
Create CustomerServiceTest.java under src/test/java with the following code:
Let us understand the code in our CustomerServiceTest.
We declared PostgreSQLContainer by passing the Docker image name postgres:16-alpine.
The Postgres container is started using JUnit 5 @BeforeAll callback, which gets executed before running any test methods.
In @BeforeEach callback method, which gets executed before running every test method, we have created a DBConnectionProvider instance by passing the JDBC connection parameters obtained from the Postgres container and also created a CustomerService instance. In the CustomerService constructor, we are creating the customers table if it does not already exist.
We have a shouldGetCustomers() test where we are inserting 2 customer records into the database, fetching all the existing customers and asserting the number of customers.
Finally, we are stopping the postgres container in @AfterAll callback method, which gets executed after all the test methods in that class are executed.
If you run the CustomerServiceTest you can see in the logs that Testcontainers pulled the Postgres Docker image from DockerHub if not already available locally, started the container and executed the test.
Voila!!! You have your first Testcontainers-based test running.
We have explored how to use Testcontainers for Java library for testing a Java application using a Postgres database.
We have seen how writing an integration test using Testcontainers is very similar to writing a unit test which you can run from your IDE. Also, any of your teammates can clone the project and run tests without installing Postgres on their computers.
In addition to Postgres, Testcontainers provides dedicated modules to many commonly used SQL databases, NoSQL databases, messaging queues, etc. You can use Testcontainers to run any containerized dependency for your tests!
You can explore more about Testcontainers at https://www.testcontainers.com/.
Testcontainers container lifecycle management using JUnit 5
The simplest way to replace H2 with a real database for testing
Getting started with Testcontainers in a Java Spring Boot Project
We hope that you find Testcontainers reliable and intuitive to use. However sometimes things don't go the way we'd expect and we'd like to try and help out if we can.