Write integration tests for Ballerina Service using TestContainers.

Ballerina container support [2] allows one to package Ballerina main programs or services into docker images that can be run inside containers.

Before moving into Ballerina docker stuff, make sure you have properly installed in docker engine in your machine as per given instructions [1] in official website.

Here [2] provides the complete guide on how you can create Ballerina program docker images. It’s very easy and to summarize the steps,

  1. Install docker environment in your machine as per. [1]
  2. Clone [2] and build source using mvn clean install.
  3. Add ballerina-container-support-0.xx.x-SNAPSHOT.jar to bre/lib/ directory of Ballerina runtime you downloaded from. [3]
  4. ‘docker’ command allows you to created images from from Ballerina source bal extension files or compiled balx extension files executed from the Ballerina runtime bin directory.
  5. Follow prompt instructions in order to run main/service programs inside docker containers.
ballerina-0.95.6/bin$ ./ballerina docker myTestProgram.bal

Then one may want to create set of Integration tests for Ballerina service that runs inside a Docker container / dockerized environment.

I found TestContainers [5] library to be pretty useful here, it provides the lightweight framework to automate the test environment locally, which is, spin up docker container which run the service need to be tested, synchronize with the service in order to determine exactly when to start the tests, ( This is required since we may need to know the exact time which service is up and running inside the container in order to start the test suits, otherwise tests may fail ) execute tests and once done we may need to stop execution of container. There are number of advantages automating tests using dockerized environment. Please see [6] and [7] blogs and official samples under [8] what this framework allows you to do.

Let’s move on Integration test sample [4] written to test Hello World Ballerina service. When writing integration tests for the service, it is required to synchronize the tests with Ballerina service startup, basically we need to wait until the Ballerina service is started inside the container, before start executing integration test suit. TestContainers[5] allows us to write custom waiting strategy to do this.

Please see custom waiting strategy which waits on Ballerina service startup.[9]

The code is very simple. Code basically read container logs and wait until Ballerina service startup log to be appeared within a timeout interval. These waiting strategy / timeouts allows us to write robust tests.

Please see the sample integration test for Hello World sample. [10]

Here we basically do is,

  1. Create docker image which packages Hello World service to Ballerina 0.95.6 runtime base image. We use container support dependency to create new child images from base Ballerina runtime images released on public docker hub. [11]
  2. Spin up container from created docker image in previous step.
  3. Wait on the Service to be started on the container.
  4. Send HTTP Get request to the service.
  5. Make assertions on the payload received.

That’s it.

[1] https://docs.docker.com/engine/installation/

[2] https://github.com/ballerinalang/container-support

[3] https://ballerinalang.org/downloads/

[4] https://github.com/djkevincr/TestBallerina

[5] https://www.testcontainers.org/

[6] https://zeroturnaround.com/rebellabs/java-integration-testing-with-testcontainers/

[7] https://rnorth.org/junit-integration-testing-with-docker-and-testcontainers

[8] https://github.com/testcontainers/testcontainers-java-examples

[9] https://github.com/djkevincr/TestBallerina/blob/master/src/test/java/org/ballerinalang/sample/ServiceStartupLogWaitStrategy.java

[10] https://github.com/djkevincr/TestBallerina/blob/master/src/test/java/org/ballerinalang/sample/BallerinaServiceTest.java

[11] https://hub.docker.com/r/ballerinalang/ballerina/tags/

Get the Medium app

A button that says 'Download on the App Store', and if clicked it will lead you to the iOS App store
A button that says 'Get it on, Google Play', and if clicked it will lead you to the Google Play store