Documentation ¶
Overview ¶
Package dockertest is intended to help in executing tests in containers.
This might be simple as executing unit tests in isolation on a docker host. You might also want to execute more complex setups like functionally testing a microservice with it's dependencies. This is where dockertest supports you.
Basically this package consists of Builders to create a Network or Containers. But it also helps in orchestrating the tests and finally in cleaning up.
To get started take a look in the main.go file in the examples folder, it's self explanatory.
Index ¶
- Variables
- type Container
- type ContainerBuilder
- func (b *ContainerBuilder) AutoRemove(v bool) *ContainerBuilder
- func (b *ContainerBuilder) BindPort(containerPort, hostPort string) *ContainerBuilder
- func (b *ContainerBuilder) Build() (*Container, error)
- func (c ContainerBuilder) Cancel()
- func (b *ContainerBuilder) Cmd(cmd string) *ContainerBuilder
- func (b *ContainerBuilder) CmdArgs(args ...string) *ContainerBuilder
- func (b *ContainerBuilder) Connect(n *Network) *ContainerBuilder
- func (b *ContainerBuilder) Dns(dnsServerIP string) *ContainerBuilder
- func (b *ContainerBuilder) Env(name string, value string) *ContainerBuilder
- func (b *ContainerBuilder) ExposePort(port string) *ContainerBuilder
- func (b *ContainerBuilder) HealthCmd(cmd string) *ContainerBuilder
- func (b *ContainerBuilder) HealthDisable() *ContainerBuilder
- func (b *ContainerBuilder) HealthInterval(d time.Duration) *ContainerBuilder
- func (b *ContainerBuilder) HealthRetries(r int) *ContainerBuilder
- func (b *ContainerBuilder) HealthShellCmd(cmd string) *ContainerBuilder
- func (b *ContainerBuilder) HealthTimeout(t time.Duration) *ContainerBuilder
- func (b *ContainerBuilder) IPAddress(ipAddress string, n *Network) *ContainerBuilder
- func (b *ContainerBuilder) Image(image string) *ContainerBuilder
- func (b *ContainerBuilder) Link(container *Container, alias string, n *Network) *ContainerBuilder
- func (b *ContainerBuilder) Mount(localPath string, containerPath string) *ContainerBuilder
- func (b *ContainerBuilder) Name(s string) *ContainerBuilder
- func (b *ContainerBuilder) NewContainerBuilder() *ContainerBuilder
- func (b *ContainerBuilder) Port(containerPort, hostPort string) *ContainerBuilder
- func (b *ContainerBuilder) UseOriginalName() *ContainerBuilder
- func (b *ContainerBuilder) WorkingDir(wd string) *ContainerBuilder
- type Network
- type NetworkBuilder
- type Session
- func (c Session) Cancel()
- func (dt *Session) Cleanup()
- func (dt *Session) CleanupRemains()
- func (dt *Session) CreateBasicNetwork(networkName string) NetworkBuilder
- func (dt *Session) CreateSimpleNetwork(networkName, subNet, ipRange string) NetworkBuilder
- func (dt *Session) DumpContainerHealthCheckLogsToDir(container ...*Container)
- func (dt *Session) DumpContainerLogsToDir(container ...*Container)
- func (dt *Session) DumpInspect(container ...*Container)
- func (dt *Session) NewContainerBuilder() *ContainerBuilder
- func (dt *Session) NotifyContainerExit(container *Container, timeout time.Duration) chan bool
- func (dt *Session) NotifyContainerHealthy(container *Container, timeout time.Duration) chan error
- func (dt *Session) NotifyContainerLogContains(container *Container, timeout time.Duration, search string) chan error
- func (dt *Session) SetLabel(label string)
- func (dt *Session) SetLogDir(logDir string)
- func (dt *Session) StartContainer(container ...*Container) error
- func (dt *Session) WriteContainerLogs(w io.Writer, container ...*Container)
Constants ¶
This section is empty.
Variables ¶
var ErrClosedWithoutFinding = errors.New("log stream closed without finding")
var ErrContainerStartTimeout = errors.New("timeout - container is not healthy")
ErrContainerStartTimeout is returned from NotifyContainerHealthy when a container was detected to be not healthy due to timeout.
var ErrContainerStillRunning = errors.New("container is running, it has no exit code yet")
ErrContainerStillRunning is returned from a call to ExitCode() if the container is still running.
var ErrInspectingContainer = errors.New("error inspecting container")
ErrInspectingContainer is returned from a call to ExitCode() if the docker client returned an error on inspect.
var ErrReadingContainerLog = errors.New("error reading container log")
var ErrStateHealthNotSet = errors.New("inspectJSON.State.Health is nil")
var ErrStateNotSet = errors.New("inspectJSON.State is nil")
Functions ¶
This section is empty.
Types ¶
type Container ¶
type Container struct { Name string // contains filtered or unexported fields }
Container is a access wrapper for a docker container.
type ContainerBuilder ¶
type ContainerBuilder struct { ContainerConfig *container.Config HostConfig *container.HostConfig NetworkingConfig *dockerNetwork.NetworkingConfig ContainerName string // contains filtered or unexported fields }
ContainerBuilder helps to create customized containers. Note that calling functions have not affect to running or already created container. only when calling the "Build" method all configuration is applied to a new container.
func (*ContainerBuilder) AutoRemove ¶ added in v0.0.3
func (b *ContainerBuilder) AutoRemove(v bool) *ContainerBuilder
AutoRemove tells the docker daemon to remove the container after it exits.
func (*ContainerBuilder) BindPort ¶ added in v0.0.12
func (b *ContainerBuilder) BindPort(containerPort, hostPort string) *ContainerBuilder
BindPort bind a Host port to a container port.
func (*ContainerBuilder) Build ¶ added in v0.0.3
func (b *ContainerBuilder) Build() (*Container, error)
Build creates a container from the current builders state.
func (*ContainerBuilder) Cmd ¶ added in v0.0.3
func (b *ContainerBuilder) Cmd(cmd string) *ContainerBuilder
Cmd sets the command that is executed when the container starts.
func (*ContainerBuilder) CmdArgs ¶ added in v0.0.8
func (b *ContainerBuilder) CmdArgs(args ...string) *ContainerBuilder
CmdArgs sets the command that is executed when the container starts.
func (*ContainerBuilder) Connect ¶ added in v0.0.3
func (b *ContainerBuilder) Connect(n *Network) *ContainerBuilder
Connect connects the container to the given Network.
func (*ContainerBuilder) Dns ¶ added in v0.0.3
func (b *ContainerBuilder) Dns(dnsServerIP string) *ContainerBuilder
Dns adds a dns server to the container. nolint: golint, revive, stylecheck
func (*ContainerBuilder) Env ¶ added in v0.0.3
func (b *ContainerBuilder) Env(name string, value string) *ContainerBuilder
Env defines an environment variable that will be set in the container.
func (*ContainerBuilder) ExposePort ¶ added in v0.0.12
func (b *ContainerBuilder) ExposePort(port string) *ContainerBuilder
ExposePort exposes a containers port inside the docker network - for example "80/tcp".
func (*ContainerBuilder) HealthCmd ¶ added in v0.0.3
func (b *ContainerBuilder) HealthCmd(cmd string) *ContainerBuilder
HealthCmd sets a command that is executed directly.
func (*ContainerBuilder) HealthDisable ¶ added in v0.0.3
func (b *ContainerBuilder) HealthDisable() *ContainerBuilder
HealthDisable disabled the health check.
func (*ContainerBuilder) HealthInterval ¶ added in v0.0.3
func (b *ContainerBuilder) HealthInterval(d time.Duration) *ContainerBuilder
HealthInterval sets the time to wait between checks.
func (*ContainerBuilder) HealthRetries ¶ added in v0.0.3
func (b *ContainerBuilder) HealthRetries(r int) *ContainerBuilder
HealthRetries sets the number of consecutive failures needed to consider a container as unhealthy.
func (*ContainerBuilder) HealthShellCmd ¶ added in v0.0.3
func (b *ContainerBuilder) HealthShellCmd(cmd string) *ContainerBuilder
HealthShellCmd sets a command that is executed in the containers default shell to determine if the container is healthy.
func (*ContainerBuilder) HealthTimeout ¶ added in v0.0.3
func (b *ContainerBuilder) HealthTimeout(t time.Duration) *ContainerBuilder
HealthTimeout sets the timeout to wait before considering the check to have hung.
func (*ContainerBuilder) IPAddress ¶ added in v0.0.3
func (b *ContainerBuilder) IPAddress(ipAddress string, n *Network) *ContainerBuilder
IPAddress defines the IP address used by the container.
func (*ContainerBuilder) Image ¶ added in v0.0.3
func (b *ContainerBuilder) Image(image string) *ContainerBuilder
Image sets the docker image to start a container from.
func (*ContainerBuilder) Link ¶ added in v0.0.3
func (b *ContainerBuilder) Link(container *Container, alias string, n *Network) *ContainerBuilder
Link links a foreign container.
func (*ContainerBuilder) Mount ¶ added in v0.0.2
func (b *ContainerBuilder) Mount(localPath string, containerPath string) *ContainerBuilder
Mount creates a volume binding to mount a local directory into the container.
func (*ContainerBuilder) Name ¶ added in v0.0.3
func (b *ContainerBuilder) Name(s string) *ContainerBuilder
Name defines the container name.
func (*ContainerBuilder) NewContainerBuilder ¶ added in v0.0.3
func (b *ContainerBuilder) NewContainerBuilder() *ContainerBuilder
NewContainerBuilder returns a new *ContainerBuilder.
func (*ContainerBuilder) Port ¶ added in v0.0.7
func (b *ContainerBuilder) Port(containerPort, hostPort string) *ContainerBuilder
Port bind a Host port to a container port. Deprecated: use BindPort instead.
func (*ContainerBuilder) UseOriginalName ¶ added in v0.0.2
func (b *ContainerBuilder) UseOriginalName() *ContainerBuilder
UseOriginalName removes the unique session-identifier from the container name.
func (*ContainerBuilder) WorkingDir ¶ added in v0.0.3
func (b *ContainerBuilder) WorkingDir(wd string) *ContainerBuilder
WorkingDir defines the working directory for the container.
type NetworkBuilder ¶ added in v0.0.2
type NetworkBuilder struct { Name string Options types.NetworkCreate // contains filtered or unexported fields }
NetworkBuilder helps with the creation of a docker network.
func (NetworkBuilder) Create ¶ added in v0.0.2
func (n NetworkBuilder) Create() (*Network, error)
Create creates a new docker network.
type Session ¶ added in v0.0.3
type Session struct { ID string // contains filtered or unexported fields }
Session is the main object when starting a docker driven container test.
func NewSession ¶ added in v0.0.3
NewSession creates a new Test and returns a Session instance to work with.
func (*Session) Cleanup ¶ added in v0.0.3
func (dt *Session) Cleanup()
Cleanup removes all resources (like containers/networks) used for this session.
func (*Session) CleanupRemains ¶ added in v0.0.6
func (dt *Session) CleanupRemains()
CleanupRemains removes all resources (like containers/networks) this kind of test - identified by the Session Label.
func (*Session) CreateBasicNetwork ¶ added in v0.0.3
func (dt *Session) CreateBasicNetwork(networkName string) NetworkBuilder
CreateBasicNetwork creates a bridged Network with the given name, subnet mask and ip range.
func (*Session) CreateSimpleNetwork ¶ added in v0.0.3
func (dt *Session) CreateSimpleNetwork(networkName, subNet, ipRange string) NetworkBuilder
CreateSimpleNetwork creates a bridged Network with the given name, subnet mask and ip range.
func (*Session) DumpContainerHealthCheckLogsToDir ¶ added in v0.0.8
DumpContainerHealthCheckLogsToDir dumps the healthCheck logs of one or multiple containers to the log directory.
func (*Session) DumpContainerLogsToDir ¶ added in v0.0.7
DumpContainerLogsToDir dumps the log of one or multiple containers to the log directory.
func (*Session) DumpInspect ¶ added in v0.0.3
DumpInspect dumps an json file with the content of "docker inspect" into the log directory.
func (*Session) NewContainerBuilder ¶ added in v0.0.3
func (dt *Session) NewContainerBuilder() *ContainerBuilder
NewContainerBuilder returns a new *ContainerBuilder.
func (*Session) NotifyContainerExit ¶ added in v0.0.6
NotifyContainerExit returns a channel that blocks until the container has exited. If the operation times out, it will try to kill the container.
func (*Session) NotifyContainerHealthy ¶ added in v0.0.6
NotifyContainerHealthy returns a channel that blocks until the given container reaches healthy state or timeout occurrs.
func (*Session) NotifyContainerLogContains ¶ added in v0.0.9
func (dt *Session) NotifyContainerLogContains(container *Container, timeout time.Duration, search string) chan error
NotifyContainerLogContains returns a channel that blocks until the given search string was found in the containers log output.
func (*Session) SetLabel ¶ added in v0.0.6
SetLabel sets the label all components of this session are assigned to. it must be set before any further creation calls to take effect.
func (*Session) SetLogDir ¶ added in v0.0.3
SetLogDir sets the directory for log files creating during test execution. When calling it will directly ensure the path.
func (*Session) StartContainer ¶ added in v0.0.3
StartContainer starts one or multiple given containers. If some containers return error while starting the last error will be returned.