Integration-testing any app is a tricky business especially when your app has external dependencies. You need to make sure that all these external dependencies are available at the same place and always in the same state. But thanks to Testcontainers, a lot of these tricky things are taken care so you always have your external dependency available (of course, at the same place and in the same state you desire). In this article, we are going to create a simple test container which will help us understand how Testcontainers work while familiarising us with the basic Testcontainers API.
Setting up the scene
What we are going to create is (part of) a Weather Statistics app. This app makes use of an API (Weather Service API). A simple schematic of the dependency is shown below:
The Weather Service API makes an endpoint available where we can
GET the temperature forecast for the next 24 hours. A sample response looks like this:
In our Weather Statistics app, we have a class
WeatherStatsService which uses the above endpoint and makes some calculation to get maximum and minimum temperature (for the next 24 hours). Below code snippet explains this:
Note: Source code for this article is available at: https://github.com/balkrishnarawool/testcontainers-json-server
What we want to do here is write an integration test for WeatherStatsService which also has a connection to Weather Service API. We will achieve this by creating a custom container for our Weather Service API.
json-server requires that we store all our mock responses in a json file (usually named
db.json). So in your current directory create a file
db.json with this content:
Now, from the same directory, run this command to get a container with json-server up and running:
When the sever is running, you can go to a browser and check the reponse to this request: http://localhost:80/forecast24hours and you should see the json you put in the db.json file. This server now represents our Weather Service API. You can now terminate the server by using
C. We don’t need to have it running because that is what Testcontainers will do. We just did this to understand how json-server works. We are going to ask Testcontainers to make use of this docker image to create a container which we will use for our integration test.
Integration testing with Testcontainers
Now we can write our test class:
Let’s look at this class in detail. This is a simple
@SpringBootTest. We first create an instance of
clue/json-server as docker image. Then we set the resource mapping so that the container knows about our mock-responses file:
db.json. Make sure to put this file in
resources directory of your test module so SpringBoot can find it on the classpath.
Then we expose port 80. (This is container port. We don’t know yet which port it will be available on the host machine. Testcontainers uses a random available port and we can get which port it is once the container is started.) Then we set the wait-strategy. This is how Testcontainers knows that our container is up and available for use. For our case, we say having a HTTP status of 200 (OK) on the root (“/”) resource is a good enough indication that the server has started.
Then we have a method
setWeatherServiceApiConfig() which is annotated with
@DynamicPropertySource. This is an indication to Spring Boot that the environment properties can be changed in this method. This is needed because
WeatherStatsService connects to the Weather Service API by using the environment properties
weatherservice.port. These properties are set here by using the jsonServer container instance. At this point the server is started so we have the host and port information.
This is it. The rest of the code in the test class is a test method and SpringBoot configuration.
In our test method, we expect the max and min to be set using the data from our mock in the db.json file. So when we run the test method, a test container is created using the set docker image and with the given configuration, the host and port properties are set using this container instance,
WeatherStatsService uses these properties and connects to the container and gets the mock data, does its calculation and thus the test case passes.
As you can see, it is quite easy to write our integration tests using Testcontainers and we don’t have to worry about having consistent availability of external dependencies. This was a simple explanation of that and also an introduction to basic API of Testcontainers. Hope this was useful.
Source code is available here: https://github.com/balkrishnarawool/testcontainers-json-server