Running Testcontainers Tests Using GitHub Actions and Testcontainers Cloud

Testcontainers is the preferred choice for writing integration tests using real dependencies as Docker containers. In this article, we will explore:

• How to run Testcontainers-based tests on GitHub Actions CI.
• How to configure GitHub Actions to use Testcontainers Cloud.
• Testcontainers usage patterns on Testcontainers Cloud dashboard.

Let’s see how we can run Testcontainers-based integration tests in a Spring Boot application using GitHub Actions. For this article, we’ll use the testcontainers-showcase application to demonstrate how to run tests using GitHub Actions.

If you have Docker installed on your local machine, then you can clone the repository and run tests locally as follows:

git clone https://github.com/testcontainers/testcontainers-showcase.git
cd testcontainers-showcase
./mvnw verify

Configuring GitHub Actions CI

Let’s add the GitHub Actions configuration file .github/workflows/ci.yml with the following configuration:

name: CI Build
on:
 push:
   branches:
     - '**'
jobs:
 build:
   name: Maven Build
   runs-on: ubuntu-latest
   steps:
     - uses: actions/checkout@v3
     - name: Setup Java 17
       uses: actions/setup-java@v3
       with:
         java-version: 17
         distribution: 'temurin'
         cache: 'maven'
     - name: Build with Maven

Testcontainers libraries require a valid Docker environment to run the tests. Because GitHub Actions provides a Docker environment by default, we don’t have to configure anything specifically to provide a valid Docker environment.

If you now add the .github/workflows/ci.yml file and commit and push the changes, then the GitHub Actions CI Pipeline will be triggered automatically, and your tests should run successfully.

Configuring GitHub Actions to use Testcontainers Cloud

Although you are able to run Testcontainers-based tests on GitHub Actions using the default Docker environment, you can speed up the execution of tests by offloading the burden of running the containers required for your tests to Testcontainers Cloud.

Go to Testcontainers Cloud and get a free account if you don’t have one already. 

Once you’re logged into Testcontainers Cloud, you can follow the installation instructions in the web app to create a Service Token. Then, configure the token as a GitHub Secret with the name TC_CLOUD_TOKEN.

Now, let’s update the .github/workflows/ci.yml file to configure the Testcontainers Cloud Agent as follows:

name: CI Build
on:
 push:
   branches:
     - '**'
jobs:
 build:
   name: Maven Build
   runs-on: ubuntu-latest
   steps:
     - uses: actions/checkout@v3
     - name: Setup Java 17
       uses: actions/setup-java@v3
       with:
         java-version: 17
         distribution: 'temurin'
         cache: 'maven'
     - name: Setup Testcontainers Cloud Client
       uses: atomicjar/testcontainers-cloud-setup-action@v1
       with:
         token: ${{ secrets.TC_CLOUD_TOKEN }}
     - name: Build with Maven
       run: ./mvnw verify

We’ve added a step to start the Testcontainers Cloud agent by using atomicjar/testcontainers-cloud-setup-action@v1. We’ve also passed the token as an argument with the Service Account Token value fetched from GitHub Actions Secrets.

Now, if you commit and push the changes, you should notice the following log statements indicating the tests are running using Testcontainers Cloud. You should also see that the tests are executed quicker than with the default Docker environment.

[testcontainers-lifecycle-0] INFO org.testcontainers.DockerClientFactory - Connected to docker:
Server Version: 78+testcontainerscloud
API Version: 1.43
Operating System: Ubuntu 22.04.2 LTS
Total Memory: 15537 MB

Running Tests in parallel with Testcontainers Cloud Turbo mode

Testcontainers Cloud Turbo mode allows you to run tests in parallel so that each test process receives its own cloud environment making test parallelization scalable. You can find more information on Testcontainers Cloud Turbo mode in our knowledge base.

We can also turn on Turbo mode in CI by passing the TC_CLOUD_CONCURRENCY environment variable as follows:

- name: Setup Testcontainers Cloud Client
 uses: atomicjar/testcontainers-cloud-setup-action@v1
 with:
   token: ${{ secrets.TC_CLOUD_TOKEN }}
   env:
     TC_CLOUD_CONCURRENCY: 2

Once the Turbo mode is enabled, we can leverage our build tools test parallelization features to run tests in parallel. We can configure Maven Surefire Plugin to run tests using four forks as follows:

<plugin>
   <groupId>org.apache.maven.plugins</groupId>
   <artifactId>maven-surefire-plugin</artifactId>
   <version>3.1.2</version>
   <configuration>
         <parallel>classes</parallel>
         <forkCount>4</forkCount>
   </configuration>
</plugin>

With Turbo mode and test parallelization, you should notice that the tests are executed faster. Note that we’re still conveniently using the default GitHub action worker even when parallelizing the tests because the Testcontainers Cloud handles the container dependencies for our app. 

Testcontainers Cloud also provides a dashboard where you explore your test executions.

Test execution insights from Testcontainers Cloud

Once you log into Testcontainers Cloud, you’ll be redirected to the dashboard page where you can see the Testcontainers Activity and Top 10 images in the last 30 days as shown in Figure 1.

You can also select a specific user or service account and see the activity of that particular account as well.

We can see the Testcontainers Cloud test execution sessions as shown in Figure 2.

If you’re using a specific version of services like databases or message brokers, you might want to run your tests with the containers of the same versions. From the dashboard, you can get an overview of the containers running and can easily catch if the tests are running with unexpected versions (Figure 3).

In this screenshot, you can see the tests are running using different versions (15-alpine, 15.2-alpine, 15.3-alpine) of postgres containers, which is most likely not what you want. The dashboard can help you to catch these kinds of issues as well.

You can also see how long each container has been running (Figure 4).

With this view, you can easily evaluate whether you’d like to run multiple containers for separate test classes or if you want to leverage the singleton containers pattern to use the same set of containers for multiple test classes.

You can learn more about Testcontainers lifecycle management using JUnit 5 from this guide. You can also watch the video version of Testcontainers container lifecycle management using JUnit 5.

Conclusion

In this article, we learned how to configure GitHub Actions to run Testcontainers-based tests and how to leverage Testcontainers Cloud to scale up the container workloads. We also explored how to use Turbo mode and run the tests quickly using the test parallelization technique. Finally, we saw how to gain Testcontainers Cloud usage insights using the Testcontainers Cloud dashboard.

Want to experience the awesomeness of Testcontainers Cloud for yourself? Get started today by creating a free account.

Learn more

• Subscribe to the Docker Newsletter.
• Get started with Testcontainers Cloud by creating a free account.
• Connect on the Testcontainers Slack.
• Learn about Testcontainers best practices.
• Get started with the Testcontainers guide.