dockertest

README

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?
• Installing and using Dockertest
  • Using Dockertest
  • Examples
• Troubleshoot & FAQ
  • Out of disk space
  • 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 for available releases.

To install dockertest, run

dep ensure -add github.com/ory/dockertest@v3.x.y

Using Dockertest

package dockertest_test

import (
	"database/sql"
	"fmt"
	"log"
	"os"
	"testing"

	_ "github.com/go-sql-driver/mysql"
	"github.com/ory/dockertest"
)

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 directory, check them out!

Troubleshoot & FAQ

Out of disk space

Try cleaning up the images with docker-cleanup-volumes.

Removing old containers

Sometimes container clean up fails. Check out this stackoverflow question on 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

Documentation

Index

• type BuildOptions
• type Pool
  • func NewPool(endpoint string) (*Pool, error)
  • func NewTLSPool(endpoint, certpath string) (*Pool, error)
  • func (d *Pool) BuildAndRun(name, dockerfilePath string, env []string) (*Resource, error)
  • func (d *Pool) BuildAndRunWithBuildOptions(buildOpts *BuildOptions, runOpts *RunOptions, hcOpts ...func(*dc.HostConfig)) (*Resource, error)
  • func (d *Pool) BuildAndRunWithOptions(dockerfilePath string, opts *RunOptions, hcOpts ...func(*dc.HostConfig)) (*Resource, error)
  • func (d *Pool) ContainerByName(containerName string) (*Resource, bool)
  • func (d *Pool) Purge(r *Resource) error
  • func (d *Pool) RemoveContainerByName(containerName string) error
  • func (d *Pool) Retry(op func() error) error
  • func (d *Pool) Run(repository, tag string, env []string) (*Resource, error)
  • func (d *Pool) RunWithOptions(opts *RunOptions, hcOpts ...func(*dc.HostConfig)) (*Resource, error)
• type Resource
  • func (r *Resource) Close() error
  • func (r *Resource) Expire(seconds uint) error
  • func (r *Resource) GetBoundIP(id string) string
  • func (r *Resource) GetHostPort(portID string) string
  • func (r *Resource) GetPort(id string) string
• type RunOptions

Types

type BuildOptions

type BuildOptions struct {
	Dockerfile string
	ContextDir string
}

BuildOptions is used to pass in optional parameters when building a container

type Pool

type Pool struct {
	Client  *dc.Client
	MaxWait time.Duration
}

Pool represents a connection to the docker API and is used to create and remove docker images.

func NewPool

func NewPool(endpoint string) (*Pool, error)

NewPool creates a new pool. You can pass an empty string to use the default, which is taken from the environment variable DOCKER_HOST and DOCKER_URL, or from docker-machine if the environment variable DOCKER_MACHINE_NAME is set, or if neither is defined a sensible default for the operating system you are on. TLS pools are automatically configured if the DOCKER_CERT_PATH environment variable exists.

func NewTLSPool

func NewTLSPool(endpoint, certpath string) (*Pool, error)

NewTLSPool creates a new pool given an endpoint and the certificate path. This is required for endpoints that require TLS communication.

func (*Pool) BuildAndRun

func (d *Pool) BuildAndRun(name, dockerfilePath string, env []string) (*Resource, error)

BuildAndRun builds and starts a docker container

func (*Pool) BuildAndRunWithBuildOptions

func (d *Pool) BuildAndRunWithBuildOptions(buildOpts *BuildOptions, runOpts *RunOptions, hcOpts ...func(*dc.HostConfig)) (*Resource, error)

BuildAndRunWithBuildOptions builds and starts a docker container. Optional modifier functions can be passed in order to change the hostconfig values not covered in RunOptions

func (*Pool) BuildAndRunWithOptions

func (d *Pool) BuildAndRunWithOptions(dockerfilePath string, opts *RunOptions, hcOpts ...func(*dc.HostConfig)) (*Resource, error)

BuildAndRunWithOptions builds and starts a docker container. Optional modifier functions can be passed in order to change the hostconfig values not covered in RunOptions

func (*Pool) ContainerByName

func (d *Pool) ContainerByName(containerName string) (*Resource, bool)

ContainerByName finds a container with the given name and returns it if present

func (*Pool) Purge

func (d *Pool) Purge(r *Resource) error

Purge removes a container and linked volumes from docker.

func (*Pool) RemoveContainerByName

func (d *Pool) RemoveContainerByName(containerName string) error

RemoveContainerByName find a container with the given name and removes it if present

func (*Pool) Retry

func (d *Pool) Retry(op func() error) error

Retry is an exponential backoff retry helper. You can use it to wait for e.g. mysql to boot up.

func (*Pool) Run

func (d *Pool) Run(repository, tag string, env []string) (*Resource, error)

Run starts a docker container.

pool.Run("mysql", "5.3", []string{"FOO=BAR", "BAR=BAZ"})

func (*Pool) RunWithOptions

func (d *Pool) RunWithOptions(opts *RunOptions, hcOpts ...func(*dc.HostConfig)) (*Resource, error)

RunWithOptions starts a docker container. Optional modifier functions can be passed in order to change the hostconfig values not covered in RunOptions

 pool.RunWithOptions(&RunOptions{Repository: "mongo", Cmd: []string{"mongod", "--smallfiles"}})
 pool.RunWithOptions(&RunOptions{Repository: "mongo", Cmd: []string{"mongod", "--smallfiles"}}, func(hostConfig *dc.HostConfig) {
			hostConfig.ShmSize = shmemsize
		})

type Resource

type Resource struct {
	Container *dc.Container
	// contains filtered or unexported fields
}

Resource represents a docker container.

func (*Resource) Close

func (r *Resource) Close() error

Close removes a container and linked volumes from docker by calling pool.Purge.

func (*Resource) Expire

func (r *Resource) Expire(seconds uint) error

Expire sets a resource's associated container to terminate after a period has passed

func (*Resource) GetBoundIP

func (r *Resource) GetBoundIP(id string) string

GetBoundIP returns a resource's published IP address.

func (*Resource) GetHostPort

func (r *Resource) GetHostPort(portID string) string

GetHostPort returns a resource's published port with an address.

func (*Resource) GetPort

func (r *Resource) GetPort(id string) string

GetPort returns a resource's published port. You can use it to connect to the service via localhost, e.g. tcp://localhost:1231/

type RunOptions

type RunOptions struct {
	Hostname     string
	Name         string
	Repository   string
	Tag          string
	Env          []string
	Entrypoint   []string
	Cmd          []string
	Mounts       []string
	Links        []string
	ExposedPorts []string
	ExtraHosts   []string
	CapAdd       []string
	SecurityOpt  []string
	DNS          []string
	WorkingDir   string
	NetworkID    string
	Labels       map[string]string
	Auth         dc.AuthConfiguration
	PortBindings map[dc.Port][]dc.PortBinding
	Privileged   bool
}

RunOptions is used to pass in optional parameters when running a container.