dockertest

package module
v1.0.0-...-6a98b71 Latest Latest
Warning

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

 Go to latest Published: Jan 13, 2016 License: Apache-2.0 Imports: 21 Imported by: 0

README

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! Dockertest uses docker-machine (aka Docker Toolbox) to spin up images on Windows and Mac OSX as well.

Supports:

  • PostgreSQL
  • MySQL
  • MongoDB
  • NSQ
  • Redis
  • Elastic Search

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.

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.

Using Dockertest

Using Dockertest is straightforward and simple.

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

Start a container
package main

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

func main() {
	c, err := ConnectToMongoDB(15, time.Millisecond*500, func(url string) bool {
		db, err := mgo.Dial(url)
		if err != nil {
			return false
		}
		defer db.Close()
		return true
	})
	require.Nil(t, err)
	defer c.KillRemove()
}

You can start PostgreSQL and MySQL in a similar fashion with

Write awesome tests

It is a good idea to start up the container only once when running tests.


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) {
	if c, err := dockertest.ConnectToPostgreSQL(15, time.Second, func(url string) bool {
		var err error
		db, err = sql.Open("postgres", url)
		if err != nil {
			return false
		}
		return db.Ping() == nil
	}); err != nil {
		log.Fatalf("Could not connect to database: %s", err)
	}
	defer c.KillRemove()
	os.Exit(m.Run())
}

func TestFunction(t *testing.T) {
    // db.Exec(...
}
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:
  - DOCKERTEST_BIND_LOCALHOST=true

Troubleshoot

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.

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. dockertest supports spinning up MySQL, PostgreSQL and MongoDB out of the box.

Dockertest provides two environment variables

Index

Constants

View Source 
const (

	// MySQLUsername must be passed as username when connecting to mysql
	MySQLUsername = "root"

	// MySQLPassword must be passed as password when connecting to mysql
	MySQLPassword = "root"

	// PostgresUsername must be passed as username when connecting to postgres
	PostgresUsername = "postgres"
	// PostgresPassword must be passed as password when connecting to postgres
	PostgresPassword = "docker"
)

Variables

View Source 
var (
	// Debug if set, prevents any container from being removed.
	Debug bool

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

	// DockerMachineName is the machine's name. You might want to use a dedicated machine for running your tests.
	// You can set this variable either directly or by defining a DOCKERTEST_IMAGE_NAME env variable.
	DockerMachineName = env.Getenv("DOCKERTEST_IMAGE_NAME", "default")

	// BindDockerToLocalhost if set, forces docker to bind the image to localhost. This for example is required when running tests on travis-ci.
	// You can set this variable either directly or by defining a DOCKERTEST_BIND_LOCALHOST env variable.
	// FIXME DOCKER_BIND_LOCALHOST remove legacy support
	BindDockerToLocalhost = env.Getenv("DOCKERTEST_BIND_LOCALHOST", env.Getenv("DOCKER_BIND_LOCALHOST", ""))
)

Functions

func IP 

func IP(containerID string) (string, error)

IP returns the IP address of the container.

func KillContainer 

func KillContainer(container string) error

KillContainer runs docker kill on a container.

func Pull 

func Pull(image string) error

Pull retrieves the docker image with 'docker pull'.

Types

type ContainerID 

type ContainerID string

ContainerID represents a container and offers methods like Kill or IP.

func ConnectToElasticSearch 

func ConnectToElasticSearch(tries int, delay time.Duration, connector func(url string) bool) (c ContainerID, err error)

ConnectToElasticSearch starts an ElasticSearch image and passes the database url to the connector callback function. The url will match the ip:port pattern (e.g. 123.123.123.123:4241)

func ConnectToMongoDB 

func ConnectToMongoDB(tries int, delay time.Duration, connector func(url string) bool) (c ContainerID, err error)

ConnectToMongoDB starts a MongoDB image and passes the database url to the connector callback. The url will match the ip:port pattern (e.g. 123.123.123.123:4241)

func ConnectToMySQL 

func ConnectToMySQL(tries int, delay time.Duration, connector func(url string) bool) (c ContainerID, err error)

ConnectToMySQL starts a MySQL image and passes the database url to the connector callback function. The url will match the username:password@tcp(ip:port) pattern (e.g. `root:root@tcp(123.123.123.123:3131)`)

func ConnectToNSQLookupd 

func ConnectToNSQLookupd(tries int, delay time.Duration, connector func(ip string, httpPort int, tcpPort int) bool) (c ContainerID, err error)

ConnectToNSQLookupd starts a NSQ image with `/nsqlookupd` running and passes the IP, HTTP port, and TCP port to the connector callback function. The url will match the ip pattern (e.g. 123.123.123.123).

func ConnectToNSQd 

func ConnectToNSQd(tries int, delay time.Duration, connector func(ip string, httpPort int, tcpPort int) bool) (c ContainerID, err error)

ConnectToNSQd starts a NSQ image with `/nsqd` running and passes the IP, HTTP port, and TCP port to the connector callback function. The url will match the ip pattern (e.g. 123.123.123.123).

func ConnectToPostgreSQL 

func ConnectToPostgreSQL(tries int, delay time.Duration, connector func(url string) bool) (c ContainerID, err error)

ConnectToPostgreSQL starts a PostgreSQL image and passes the database url to the connector callback.

func ConnectToRedis 

func ConnectToRedis(tries int, delay time.Duration, connector func(url string) bool) (c ContainerID, err error)

ConnectToRedis starts a Redis image and passes the database url to the connector callback function. The url will match the ip:port pattern (e.g. 123.123.123.123:6379)

func OpenElasticSearchContainerConnection 

func OpenElasticSearchContainerConnection(tries int, delay time.Duration) (c ContainerID, con *elastigo.Conn, err error)

OpenElasticSearchContainerConnection is supported for legacy reasons. Don't use it.

func OpenMongoDBContainerConnection 

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

OpenMongoDBContainerConnection is supported for legacy reasons. Don't use it.

func OpenMySQLContainerConnection 

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

OpenMySQLContainerConnection is supported for legacy reasons. Don't use it.

func OpenNSQLookupdContainerConnection 

func OpenNSQLookupdContainerConnection(tries int, delay time.Duration) (c ContainerID, ip string, tcpPort int, httpPort int, err error)

OpenNSQLookupdContainerConnection is supported for legacy reasons. Don't use it.

func OpenNSQdContainerConnection 

func OpenNSQdContainerConnection(tries int, delay time.Duration) (c ContainerID, ip string, tcpPort int, httpPort int, err error)

OpenNSQdContainerConnection is supported for legacy reasons. Don't use it.

func OpenPostgreSQLContainerConnection 

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

OpenPostgreSQLContainerConnection is supported for legacy reasons. Don't use it.

func OpenRedisContainerConnection 

func OpenRedisContainerConnection(tries int, delay time.Duration) (c ContainerID, client *redis.Client, err error)

OpenRedisContainerConnection is supported for legacy reasons. Don't use it.

func SetupElasticSearchContainer 

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

SetupElasticSearchContainer sets up a real ElasticSearch 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 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.

func SetupNSQLookupdContainer 

func SetupNSQLookupdContainer() (c ContainerID, ip string, tcpPort int, httpPort int, err error)

SetupNSQLookupdContainer sets up a real NSQ instance for testing purposes using a Docker container and executing `/nsqlookupd`. It returns the container ID and its IP address, or makes the test fail on error.

func SetupNSQdContainer 

func SetupNSQdContainer() (c ContainerID, ip string, tcpPort int, httpPort int, err error)

SetupNSQdContainer sets up a real NSQ instance for testing purposes using a Docker container and executing `/nsqd`. It returns the container ID and its IP address, or makes the test fail on error.

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.

func SetupRedisContainer 

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

SetupRedisContainer sets up a real Redis 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 (ContainerID) IP 

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

IP retrieves the container's IP address.

func (ContainerID) Kill 

func (c ContainerID) Kill() error

Kill runs "docker kill" on the container.

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

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.