dockertest

README

Dockertest

Use Docker to run your Go language integration tests against persistent data storage services like MySQL, Postgres or MongoDB on Microsoft Windows, Mac OSX and Linux! Dockertest uses docker-machine (aka Docker Toolbox) to spin up images on Windows and Mac OSX as well.

A suite for testing with Docker. Based on docker.go from camlistore. This fork detects automatically, if Docker Toolbox is installed. If it is, Docker integration on Windows and Mac OSX can be used without any additional work. To avoid port collisions when using docker-machine, Dockertest chooses a random port to bind the requested image.

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.

Using Dockertest

Using Dockertest is straightforward and simple. At present, Dockertest supports MongoDB, Postgres and MySQL containers out of the box. Feel free to extend this list by contributing to this project.

Note: When using the Docker Toolbox (Windows / OSX), make sure that the VM is started by running docker-machine start default.

MongoDB Container

import "github.com/ory-am/dockertest"
import "gopkg.in/mgo.v2"
import "time"

func Foobar() {
  // Start MongoDB Docker container. Wait 1 second for the image to load.
  containerID, ip, port, err := dockertest.SetupMongoContainer()

  if err != nil {
    return err
  }

  // kill the container on deference
  defer containerID.KillRemove()

  url := fmt.Sprintf("%s:%d", ip, port)
  sess, err := mgo.Dial(url)
  if err != nil {
    return err
  }

  defer sess.Close()
  // ...
}

MySQL Container

import "github.com/ory-am/dockertest"
import "github.com/go-sql-driver/mysql"
import "database/sql"
import "time"

func Foobar() {
    // Wait 10 seconds for the image to load.
    c, ip, port, err := dockertest.SetupMySQLContainer()
    if err != nil {
        return
    }
    defer c.KillRemove()

    url := fmt.Sprintf("mysql://%s:%s@%s:%d/", dockertest.MySQLUsername, dockertest.MySQLPassword, ip, port)
    db, err := sql.Open("mysql", url)
    if err != nil {
        return
    }

    defer db.Close()
    // ...
}

Postgres Container

import "github.com/ory-am/dockertest"
import "github.com/lib/pq"
import "database/sql"
import "time"

func Foobar() {
    // Wait 10 seconds for the image to load.
    c, ip, port, err := dockertest.SetupPostgreSQLContainer()
    if err != nil {
        return
    }
    defer c.KillRemove()

    url := fmt.Sprintf("postgres://%s:%s@%s:%d/", dockertest.PostgresUsername, dockertest.PostgresPassword, ip, port)
    db, err := sql.Open("postgres", url)
    if err != nil {
        return
    }

    defer db.Close()
    // ...
}

Usage in tests

It is a good idea to start up the container only once when running tests. To achieve this for example:

import (
	"fmt"
	"testing"
    "log"
	"os"

	"database/sql"
	_ "github.com/lib/pq"
	"github.com/ory-am/dockertest"
)

var db *sql.DB

func TestMain(m *testing.M) {
	c, ip, port, err := dockertest.SetupPostgreSQLContainer()
	if err != nil {
		log.Fatalf("Could not set up PostgreSQL container: %v", err)
	}
	defer c.KillRemove()

	url := fmt.Sprintf("postgres://%s:%s@%s:%d/postgres?sslmode=disable", dockertest.PostgresUsername, dockertest.PostgresPassword, ip, port)
	db, err = sql.Open("postgres", url)
	if err != nil {
		log.Fatalf("Could not set up PostgreSQL container: %v", err)
	}

	if err = db.Ping(); err != nil {
		log.Fatalf("Could not ping database: %v", err)
	}

	os.Exit(m.Run())
}

func TestFunction(t *testing.T) {
    // ...
}

Setting up Travis-CI

You can run the Docker integration on Travis easily:

# Sudo is required for docker
sudo: required

# Enable docker
services:
  - docker

# In Travis, we need to bind to 127.0.0.1 in order to get a working connection. This environment variable
# tells dockertest to do that.
env:
  - DOCKER_BIND_LOCALHOST=true

Thanks to our sponsors: Ory GmbH & Imarum GmbH

Documentation

Overview

Package dockertest contains helper functions for setting up and tearing down docker containers to aid in testing.

Index

• Constants
• Variables
• func IP(containerID string) (string, error)
• func KillContainer(container string) error
• func Pull(image string) error
• type ContainerID
  • func OpenMongoDBContainerConnection(tries int, delay time.Duration) (c ContainerID, db *mgo.Session, err error)
  • func OpenMySQLContainerConnection(tries int, delay time.Duration) (c ContainerID, db *sql.DB, err error)
  • func OpenPostgreSQLContainerConnection(tries int, delay time.Duration) (c ContainerID, db *sql.DB, err error)
  • func SetupMongoContainer() (c ContainerID, ip string, port int, err error)
  • func SetupMySQLContainer() (c ContainerID, ip string, port int, err error)
  • func SetupPostgreSQLContainer() (c ContainerID, ip string, port int, err error)
  • func (c ContainerID) IP() (string, error)
  • func (c ContainerID) Kill() error
  • func (c ContainerID) KillRemove() error
  • func (c ContainerID) Remove() error

Constants

const (
	MySQLUsername = "root"
	MySQLPassword = "root"

	PostgresUsername = "postgres" // set up by the dockerfile of postgresImage
	PostgresPassword = "docker"   // set up by the dockerfile of postgresImage
)

Variables

var Debug bool

Debug, if set, prevents any container from being removed.

var DockerMachineAvailable bool

DockerMachineAvailable, if true, uses docker-machine to run docker commands (for running tests on Windows and Mac OS)

var DockerMachineName string = "default"

DockerMachineName is the machine's name. You might want to use a dedicated machine for running your tests.

Functions

func IP

func IP(containerID string) (string, error)

IP returns the IP address of the container.

func KillContainer

func KillContainer(container string) error

func Pull

func Pull(image string) error

Pull retrieves the docker image with 'docker pull'.

Types

type ContainerID

type ContainerID string

func OpenMongoDBContainerConnection

func OpenMongoDBContainerConnection(tries int, delay time.Duration) (c ContainerID, db *mgo.Session, err error)

func OpenMySQLContainerConnection

func OpenMySQLContainerConnection(tries int, delay time.Duration) (c ContainerID, db *sql.DB, err error)

func OpenPostgreSQLContainerConnection

func OpenPostgreSQLContainerConnection(tries int, delay time.Duration) (c ContainerID, db *sql.DB, err error)

func SetupMongoContainer

func SetupMongoContainer() (c ContainerID, ip string, port int, err error)

SetupMongoContainer sets up a real MongoDB instance for testing purposes, using a Docker container. It returns the container ID and its IP address, or makes the test fail on error.

func SetupMySQLContainer

func SetupMySQLContainer() (c ContainerID, ip string, port int, err error)

SetupMySQLContainer sets up a real MySQL instance for testing purposes, using a Docker container. It returns the container ID and its IP address, or makes the test fail on error. Currently using https://index.docker.io/u/orchardup/mysql/

func SetupPostgreSQLContainer

func SetupPostgreSQLContainer() (c ContainerID, ip string, port int, err error)

SetupPostgreSQLContainer sets up a real PostgreSQL instance for testing purposes, using a Docker container. It returns the container ID and its IP address, or makes the test fail on error. Currently using https://index.docker.io/u/nornagon/postgres

func (ContainerID) IP

func (c ContainerID) IP() (string, error)

func (ContainerID) Kill

func (c ContainerID) Kill() error

func (ContainerID) KillRemove

func (c ContainerID) KillRemove() error

KillRemove calls Kill on the container, and then Remove if there was no error.

func (ContainerID) Remove

func (c ContainerID) Remove() error

Remove runs "docker rm" on the container