README

ORY Dockertest

Build Status Coverage Status

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?

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
Expand ▾ Collapse ▴

Documentation

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

This section is empty.

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) 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.Run(&RunOptions{Repository: "mongo", Cmd: []string{"mongod", "--smallfiles"}}) pool.Run(&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

                                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.

                                      Source Files

                                      Directories

                                      Path Synopsis
                                      Package docker provides a client for the Docker remote API.
                                      Package docker provides a client for the Docker remote API.
                                      pkg/pools
                                      Package pools provides a collection of pools which provide various data types with buffers.
                                      Package pools provides a collection of pools which provide various data types with buffers.
                                      pkg/term
                                      Package term provides structures and helper functions to work with terminal (state, sizes).
                                      Package term provides structures and helper functions to work with terminal (state, sizes).
                                      types
                                      Package types is used for API stability in the types and response to the consumers of the API stats endpoint.
                                      Package types is used for API stability in the types and response to the consumers of the API stats endpoint.
                                      types/filters
                                      Package filters provides tools for encoding a mapping of keys to a set of multiple values.
                                      Package filters provides tools for encoding a mapping of keys to a set of multiple values.
                                      types/versions/v1p19
                                      Package v1p19 provides specific API types for the API version 1, patch 19.
                                      Package v1p19 provides specific API types for the API version 1, patch 19.
                                      types/versions/v1p20
                                      Package v1p20 provides specific API types for the API version 1, patch 20.
                                      Package v1p20 provides specific API types for the API version 1, patch 20.