Categorygithub.com/opalmer/dockertest
modulepackage
0.3.11
Repository: https://github.com/opalmer/dockertest.git
Documentation: pkg.go.dev

# README

Docker Test

Build Status codecov Go Report Card GoDoc

This project provides a small set of wrappers around docker. It is intended to be used to ease testing. Documentation is available via godoc: https://godoc.org/github.com/opalmer/dockertest

Examples

Create a container and retrieve an exposed port.

import (
	"context"
	"log"
	"github.com/opalmer/dockertest"
)

func main() {
	client, err := dockertest.NewClient()
	if err != nil {
		log.Fatal(err)
	}

	// Construct information about the container to start.
	input := dockertest.NewClientInput("nginx:mainline-alpine")
	input.Ports.Add(&dockertest.Port{
		Private:  80,
		Public:   dockertest.RandomPort,
		Protocol: dockertest.ProtocolTCP,
	})

	// Start the container
	container, err := client.RunContainer(context.Background(), input)
	if err != nil {
		log.Fatal(err)
	}

	// Extract information about the started container.
	port, err := container.Port(80)
	if err != nil {
		log.Fatal(err)
	}

	fmt.Println(port.Public, port.Address)

	if err := client.RemoveContainer(context.Background(), container.ID()); err != nil {
		log.Fatal(err)
	}
}

Create a container using the Service struct.

import (
	"context"
	"log"
	"github.com/opalmer/dockertest"
)

func main() {
	client, err := dockertest.NewClient()
	if err != nil {
		log.Fatal(err)
	}

	// Construct information about the container to start.
	input := dockertest.NewClientInput("nginx:mainline-alpine")
	input.Ports.Add(&dockertest.Port{
		Private:  80,
		Public:   dockertest.RandomPort,
		Protocol: dockertest.ProtocolTCP,
	})

	// Construct the service and tell it how to handle waiting
	// for the container to start.
	service := client.Service(input)
	service.Ping = func(input *dockertest.PingInput) error {
		port, err := input.Container.Port(80)
		if err != nil {
			return err // Will cause Run() to call Terminate()
		}

		for {
			_, err := net.Dial(string(port.Protocol), fmt.Sprintf("%s:%d", port.Address, port.Public))
			if err != nil {
				time.Sleep(time.Millisecond * 100)
				continue
			}
			break
		}

		return nil
	}

	// Starts the container, runs Ping() and waits for it to return. If Ping()
	// fails the container will be terminated and Run() will return an error.
	if err := service.Run(); err != nil {
		log.Fatal(err)
	}

	// Container has started, get information information
	// about the exposed port.
	port, err := service.Container.Port(80)
	if err != nil {
		log.Fatal(err)
	}
	fmt.Println(port.Public, port.Address)

	if err := service.Terminate(); err != nil {
		log.Fatal(err)
	}
}

# Functions

NewClient produces a new *DockerClient that can be used to interact with Docker.
NewClientInput produces a *ClientInput struct.
NewPorts will produces a new *Ports struct that's ready to be modified.

# Constants

ProtocolTCP represents a tcp Protocol.
ProtocolUDP represents a udp Protocol.
RandomPort may be passed to a function to indicate that a random port should be chosen.

# Variables

ErrContainerNotFound is returned by GetContainer if we were unable to find the requested c.
ErrContainerNotRunning is returned by Started() if the Container was never started.
ErrContainerNotStarted is returned by Terminate() if the container was never started.
ErrContainerStillRunning is returned by Finished() if the Container is still running.
ErrInputNotProvided is returned by Service.Run if the Input field is not provided.
ErrPortNotFound is returned by ContainerInfo.Port if we're unable to find a matching port on the c.

# Structs

ClientInput is used to provide inputs to the RunContainer function.
ContainerInfo provides a wrapper around information.
DockerClient provides a wrapper for the standard dc client.
PingInput is used to provide inputs to a Ping function.
Port represents a port spec that may be used by the *Ports struct to expose a port on a container.
Ports is when to convey port exposures to RunContainer().
Service is a struct used to run and manage a Container for a specific service.

# Type aliases

Ping is a function that's used to ping a service before returning from Service.Run.
Protocol is a string representing a protocol such as TCP or UDP.