# README
Docker Test
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.