dockertest

package module
v3.0.9+incompatible Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Jul 29, 2017 License: Apache-2.0 Imports: 8 Imported by: 0

README

ory.am/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

go get gopkg.in/ory-am/dockertest.v3
Using Dockertest
package dockertest_test

import (
	"testing"
	"log"
	"gopkg.in/ory-am/dockertest.v3"
	_ "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 directory, check them out!

Setting up Travis-CI

You can run the Docker integration on Travis easily:

# 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.

Removing old containers

Sometimes container clean up fails. Check out this stackoverflow question on how to fix this.

Documentation

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

This section is empty.

Types

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_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.

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) Purge

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

Purge removes a container and linked volumes from docker.

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) (*Resource, error)

RunWithOptions starts a docker container.

pool.Run(&RunOptions{Repository: "mongo", Cmd: []string{"mongod", "--smallfiles"}})

type Resource

type Resource struct {
	Container *dc.Container
}

Resource represents a docker container.

func (*Resource) GetBoundIP

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

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 {
	Repository   string
	Tag          string
	Env          []string
	Entrypoint   []string
	Cmd          []string
	Mounts       []string
	Links        []string
	ExposedPorts []string
	Auth         dc.AuthConfiguration
}

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

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL