dktest

dktest

dktest makes it stupidly easy to write integration tests in Go using Docker. Pulling images, starting containers, and cleaning up (even if your tests panic) is handled for you automatically!

API

Run() is the workhorse

type ContainerInfo struct {
    ID        string
    Name      string
    ImageName string
    IP        string
    Port      string
}

type Options struct {
    Timeout   time.Duration
    ReadyFunc func(ContainerInfo) bool
    Env       map[string]string
    // If you prefer to specify your port bindings as a string, use nat.ParsePortSpecs()
    PortBindings nat.PortMap
    PortRequired bool
}

func Run(t *testing.T, imgName string, opts Options, testFunc func(*testing.T, ContainerInfo))

Example Usage

import "testing"

import (
    "github.com/dhui/dktest"
    _ "github.com/lib/pq"
)

func pgReady(c dktest.ContainerInfo) bool {
    connStr := fmt.Sprintf("host=%s port=%s user=postgres password=%s", c.IP, c.Port, password)
    db, err := sql.Open("postgres", connStr)
    if err != nil {
        return false
    }
    defer db.Close()
    return db.Ping() == nil
}

func Test(t *testing.T) {
    dktest.Run(t, "postgres:alpine", dktest.Options{PortRequired: true, ReadyFunc: pgReady},
        func(t *testing.T, c dktest.ContainerInfo) {
        connStr := fmt.Sprintf("host=%s port=%s user=postgres password=%s", c.IP, c.Port, password)
        db, err := sql.Open("postgres", connStr)
        if err != nil {
            t.Fatal(err)
        }
        defer db.Close()
        if err := db.Ping(); err != nil {
            t.Fatal(err)
        }
        // Test using db
    })
}

For more examples, see the docs.

Cleaning up dangling containers

In the unlikely scenario where dktest leaves dangling containers, you can find and removing them by using the dktest label:

# find dangling containers
$ docker ps -a -f label=dktest
# remove dangling containers
$ docker container prune -f label=dktest

Roadmap

• Support multiple ports in ContainerInfo
• Use non-default network
• Add more Options
  • Volume mounts
  • Network config

Comparison to dockertest

Why dktest is better

• Uses the official Docker SDK
  • docker/docker (aka moby/moby) uses import path checking, so needs to be imported as github.com/docker/docker
• Designed to run in the Go testing environment
  • Smaller API surface
  • Running Docker containers are automatically cleaned up
• Has better test coverage
• Uses package management (Go modules) properly. e.g. not manually vendored

Why dockertest is better

• Has been around longer and API is more stable
• More options for configuring Docker containers
• Has more Github stars and contributors