Skip to content

dhui/dktest

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

dktest

GitHub Workflow Status (branch) Coverage Status GoDoc Go Report Card GitHub Release Supported Go versions

dktest is short for dockertest.

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 (
    "context"
    "testing"
)

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

func pgReady(ctx context.Context, c dktest.ContainerInfo) bool {
    ip, port, err := c.FirstPort()
    if err != nil {
        return false
    }
    connStr := fmt.Sprintf("host=%s port=%s user=postgres dbname=postgres sslmode=disable", ip, port)
    db, err := sql.Open("postgres", connStr)
    if err != nil {
        return false
    }
    defer db.Close()
    return db.PingContext(ctx) == nil
}

func Test(t *testing.T) {
    dktest.Run(t, "postgres:alpine", dktest.Options{PortRequired: true, ReadyFunc: pgReady},
        func(t *testing.T, c dktest.ContainerInfo) {
        ip, port, err := c.FirstPort()
        if err != nil {
            t.Fatal(err)
        }
        connStr := fmt.Sprintf("host=%s port=%s user=postgres dbname=postgres sslmode=disable", ip, port)
        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.

Debugging tests

Running go test with the -v option will display the container lifecycle log statements along with the container ID.

Short lived tests/containers

Run go test with the -v option and specify the LogStdout and/or LogStderr Options to see the container's logs.

Interactive tests/containers

Run go test with the -v option to get the container ID and check the container's logs with docker logs -f $CONTAINER_ID.

Cleaning up dangling containers

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

# list dangling containers
$ docker ps -a --filter label=dktest
# stop dangling containers
$ docker ps --filter label=dktest | awk '{print $1}' | grep -v CONTAINER | xargs docker stop
# remove dangling containers
$ docker container prune --filter label=dktest

Roadmap

  • Support multiple ports in ContainerInfo
  • Use non-default network
  • Add more Options
    • Volume mounts
    • Network config
  • Support testing against multiple containers. It can be faked for now by nested/recursive Run() calls but that serializes the containers' startup time.

Comparisons

Last updated: 2020/01/03

Why dktest is better

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

TBD