- Notifications
You must be signed in to change notification settings - Fork247
Write better integration tests! Dockertest helps you boot up ephermal docker images for your Go tests with minimal work.
License
ory/dockertest
Folders and files
| Name | Name | Last commit message | Last commit date | |
|---|---|---|---|---|
Repository files navigation
Use Docker to run your Golang integration tests against third party services onMicrosoft Windows, Mac OSX and Linux!
Table of Contents
When developing applications, it is often necessary to use services that talk toa database system. Unit Testing these services can be cumbersome because mockingdatabase/DBAL is strenuous. Making slight changes to the schema impliesrewriting at least some, if not all of the mocks. The same goes for API changesin the DBAL. To avoid this, it is smarter to test these specific servicesagainst a real database that is destroyed after testing. Docker is the perfectsystem for running unit tests as you can spin up containers in a few seconds andkill them when the test completes. The Dockertest library provides easy to usecommands for spinning up Docker containers and using them for your tests.
Using Dockertest is straightforward and simple. Check thereleases tab for availablereleases.
To install dockertest, run
go get -u github.com/ory/dockertest/v3package dockertest_testimport ("database/sql""fmt""log""os""testing"_"github.com/go-sql-driver/mysql""github.com/ory/dockertest/v3")vardb*sql.DBfuncTestMain(m*testing.M) {// uses a sensible default on windows (tcp/http) and linux/osx (socket)pool,err:=dockertest.NewPool("")iferr!=nil {log.Fatalf("Could not construct pool: %s",err)}// uses pool to try to connect to Dockererr=pool.Client.Ping()iferr!=nil {log.Fatalf("Could not connect to Docker: %s",err)}// pulls an image, creates a container based on it and runs itresource,err:=pool.Run("mysql","5.7", []string{"MYSQL_ROOT_PASSWORD=secret"})iferr!=nil {log.Fatalf("Could not start resource: %s",err)}// exponential backoff-retry, because the application in the container might not be ready to accept connections yetiferr:=pool.Retry(func()error {varerrerrordb,err=sql.Open("mysql",fmt.Sprintf("root:secret@(localhost:%s)/mysql",resource.GetPort("3306/tcp")))iferr!=nil {returnerr}returndb.Ping()});err!=nil {log.Fatalf("Could not connect to database: %s",err)}// as of go1.15 testing.M returns the exit code of m.Run(), so it is safe to use defer heredeferfunc() {iferr:=pool.Purge(resource);err!=nil {log.Fatalf("Could not purge resource: %s",err) } }()m.Run()}funcTestSomething(t*testing.T) {// db.Query()}
We provide code examples for well known services in theexamplesdirectory, check them out!
Try cleaning up the images withdocker-cleanup-volumes.
Sometimes container clean up fails. Check outthis stackoverflow questionon how to fix this. You may also set an absolute lifetime on containers:
resource.Expire(60)// Tell docker to hard kill the container in 60 seconds
To let stopped containers removed from file system automatically, usepool.RunWithOptions() instead ofpool.Run() withconfig.AutoRemove set totrue, e.g.:
postgres,err:=pool.RunWithOptions(&dockertest.RunOptions{Repository:"postgres",Tag:"11",Env: []string{"POSTGRES_USER=test","POSTGRES_PASSWORD=test","listen_addresses = '*'",},},func(config*docker.HostConfig) {// set AutoRemove to true so that stopped container goes away by itselfconfig.AutoRemove=trueconfig.RestartPolicy= docker.RestartPolicy{Name:"no",}})
You should add docker dind service to your job which starts in siblingcontainer. That means database will be available on hostdocker.
You app should be able to change db host through environment variable.
Here is the simple example ofgitlab-ci.yml:
stages: -testgo-test:stage:testimage:golang:1.15services: -docker:dindvariables:DOCKER_HOST:tcp://docker:2375DOCKER_DRIVER:overlay2YOUR_APP_DB_HOST:dockerscript: -go test ./...
Plus in thepool.Retry method that checks for connection readiness, you needto use$YOUR_APP_DB_HOST instead of localhost.
Gitlab runner can be run in docker executor mode to save compatibility withshared runners.
Here is the simple register command:
gitlab-runner register -n \ --url https://gitlab.com/ \ --registration-token$YOUR_TOKEN \ --executor docker \ --description"My Docker Runner" \ --docker-image"docker:19.03.12" \ --docker-privileged
You only need to instruct docker dind to start with disabled tls.
Add variableDOCKER_TLS_CERTDIR: "" togitlab-ci.yml above. It will telldocker daemon to start on 2375 port over http.
name:Test with Dockeron:[push]jobs:test:runs-on:ubuntu-latestservices:dind:image:docker:23.0-rc-dind-rootlessports: -2375:2375steps: -name:Checkout codeuses:actions/checkout@v2 -name:Set up Gouses:actions/setup-go@v4with:go-version:"1.21" -name:Test with Dockerrun:go test -v ./...
Use-case: locally installed docker CLI (client), docker daemon somewhereremotely, environment properly set (ie:DOCKER_HOST, etc..). For example,remote docker can be provisioned by docker-machine.
Currently, dockertest in case ofresource.GetHostPort() will return dockerhost binding address (commonly -localhost) instead of remote docker host.Universal solution is:
funcgetHostPort(resource*dockertest.Resource,idstring)string {dockerURL:=os.Getenv("DOCKER_HOST")ifdockerURL=="" {returnresource.GetHostPort(id)}u,err:=url.Parse(dockerURL)iferr!=nil {panic(err)}returnu.Hostname()+":"+resource.GetPort(id)}
It will return the remote docker host concatenated with the allocated port incaseDOCKER_HOST env is defined. Otherwise, it will fall back to the embeddedbehavior.
About
Write better integration tests! Dockertest helps you boot up ephermal docker images for your Go tests with minimal work.
