Getting started with Testcontainers for Go

In this guide, you will learn how to
Create a Go application with modules support.
Implement a Repository to manage customers data in PostgreSQL database using pgx driver.
Test the database interactions using testcontainers-go.
Your favorite IDE(VS Code, GoLand)
A Docker environment supported by Testcontainers https://golang.testcontainers.org/system_requirements/
We are going to create a Go project and implement a Repository to save and retrieve the customer details from a PostgreSQL database. Then we will test this repository using the testcontainers-go postgres module.
Let’s start with creating a Go project.
We are going to use the jackc/pgx PostgreSQL Driver to interact with the Postgres database and the testcontainers-go postgres module to spin up a Postgres docker instance for testing. Also, we are going to use testify for running multiple tests as a suite and for writing assertions.
Let’s install these dependencies.
After installing these dependencies, your go.mod file should look like this:
First, let us start with creating a types.go file in customer package and define the Customer struct to model the customer details as follows:
Next, create customer/repo.go file, define the Repository struct and then add methods to create a new customer and get a customer by email as follows:
Let’s understand what is going on here:
We have defined a Repository struct with a field of type *pgc.Conn which will be used for performing database operations.
We have defined a helper function NewRepository(connStr) that takes a database connection string and initializes Repository.
Then we have implemented CreateCustomer() and GetCustomerByEmail() methods on the Repository receiver.
We have our Repository implementation ready, but for testing we need a PostgreSQL database. We can use testcontainers-go to spin up a Postgres database in a Docker container and run our tests connecting to that database.
In real applications we might use some database migration tool, but for this guide let us use a simple script to initialize our database.
Create a testdata/init-db.sql file to create CUSTOMERS table and insert the sample data as follows:
The testcontainers-go library provides the generic Container abstraction that can be used to run any containerised service. To further simplify, testcontainers-go provides technology specific modules that will reduce the boilerplate and also provides a functional options pattern to easily construct the container instance.
For example, PostgresContainer provides WithImage(), WithDatabase(), WithUsername(), WithPassword() etc functions to set various properties of Postgres containers easily.
Now, let’s create the customer/repo_test.go file and implement the test as follows:
Let’s understand what is going on here:
We have created an instance of PostgresContainer by specifying the Docker image postgres:15.3-alpine, from which the container needs to be created.
We have configured the initialization scripts using WithInitScripts(…​) so that after the database starts, the CUSTOMERS table will be created and sample data will be inserted.
Next, we have specified the username, password and database name for the Postgres container.
We have configured the WaitStrategy that will help to determine whether the Postgres container is fully ready to use or not.
Then, we have defined the test cleanup function using t.Cleanup(…​) so that at the end of the test the Postgres container will be removed.
Next, we obtained the database ConnectionString from PostgresContainer and initialized Repository.
Then, we have created a new customer with the email henry@gmail.com and verified that a customer with the email henry@gmail.com exists in our database.
In the previous section, we saw how to spin up a Postgres Docker container for a single test. But usually we might have multiple tests in a single file, and we may want to reuse the same Postgres Docker container for all the tests in that file.
We can use testify suite package to implement common test setup and teardown actions.
First, let us extract PostgresContainer creation logic into a separate file called testhelpers/containers.go.
In containers.go, we have defined PostgresContainer struct which extends testcontainers-go PostgresContainer struct to provide easy access to ConnectionString and created CreatePostgresContainer() function to instantiate PostgresContainer.
Now, let’s create customer/repo_suite_test.go file and implement tests for creating a new customer and getting customer by email by using testify suite package as follows:
Let’s understand what is going on here:
We have created CustomerRepoTestSuite by extending suite.Suite struct and added fields which will be used across multiple tests in that suite.
In the SetupSuite() function which will be executed only once before executing the tests, we have created PostgresContainer and initialized Repository.
In TearDownSuite() function which will be executed only once after all the tests in that suite are executed, we are terminating the container which will destroy the Postgres Docker container.