[](https://travis-ci.org/ory/dockertest?branch=master) [](https://coveralls.io/github/ory/dockertest?branch=v3) Use Docker to run your Go language integration tests against third party services on **Microsoft Windows, Mac OSX and Linux**! **Table of Contents** - [Why should I use Dockertest?](#why-should-i-use-dockertest) - [Installing and using Dockertest](#installing-and-using-dockertest) - [Using Dockertest](#using-dockertest) - [Examples](#examples) - [Setting up Travis-CI](#setting-up-travis-ci) - [Troubleshoot & FAQ](#troubleshoot-&-faq) - [Out of disk space](#out-of-disk-space) - [Removing old containers](#removing-old-containers) ## Why should I use Dockertest? When developing applications, it is often necessary to use services that talk to a database system. Unit Testing these services can be cumbersome because mocking database/DBAL is strenuous. Making slight changes to the schema implies rewriting at least some, if not all of the mocks. The same goes for API changes in the DBAL. To avoid this, it is smarter to test these specific services against a real database that is destroyed after testing. Docker is the perfect system for running unit tests as you can spin up containers in a few seconds and kill them when the test completes. The Dockertest library provides easy to use commands for spinning up Docker containers and using them for your tests. ## Installing and using Dockertest Using Dockertest is straightforward and simple. Check the [releases tab](https://github.com/ory/dockertest/releases) for available releases. To install dockertest, run ``` dep ensure -add github.com/ory/dockertest@v3.x.y ``` ### Using Dockertest ```go package dockertest_test import ( "testing" "log" "github.com/ory/dockertest" _ "github.com/go-sql-driver/mysql" "database/sql" "fmt" "os" ) var db *sql.DB func TestMain(m *testing.M) { // uses a sensible default on windows (tcp/http) and linux/osx (socket) pool, err := dockertest.NewPool("") if err != nil { log.Fatalf("Could not connect to docker: %s", err) } // pulls an image, creates a container based on it and runs it resource, err := pool.Run("mysql", "5.7", []string{"MYSQL_ROOT_PASSWORD=secret"}) if err != 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 yet if err := pool.Retry(func() error { var err error db, err = sql.Open("mysql", fmt.Sprintf("root:secret@(localhost:%s)/mysql", resource.GetPort("3306/tcp"))) if err != nil { return err } return db.Ping() }); err != nil { log.Fatalf("Could not connect to docker: %s", err) } code := m.Run() // You can't defer this because os.Exit doesn't care for defer if err := pool.Purge(resource); err != nil { log.Fatalf("Could not purge resource: %s", err) } os.Exit(code) } func TestSomething(t *testing.T) { // db.Query() } ``` ### Examples We provide code examples for well known services in the [examples](examples/) directory, check them out! ### Setting up Travis-CI You can run the Docker integration on Travis easily: ```yml # Sudo is required for docker sudo: required # Enable docker services: - docker ``` ## Troubleshoot & FAQ ### Out of disk space Try cleaning up the images with [docker-cleanup-volumes](https://github.com/chadoe/docker-cleanup-volumes). ### Removing old containers Sometimes container clean up fails. Check out [this stackoverflow question](http://stackoverflow.com/questions/21398087/how-to-delete-dockers-images) on how to fix this. You may also set an absolute lifetime on containers: ```go resource.Expire(60) // Tell docker to hard kill the container in 60 seconds ```