testingdock

package module
v0.3.1 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Feb 14, 2018 License: MIT Imports: 21 Imported by: 0

README

testingdock GoDoc Build Status codecov.io Code Climate Go Report Card

Simple helper library for integration testing with docker in a programmatical way.

Example

See the Container test suite.

Notes

This library will create networks and containers under the label owner=testingdock. Containers and networks with this label will be considered to have been started by this library and may be subject to aggressive manipulation and cleanup.

Documentation

Overview

Package testingdock simplifies integration testing with docker.

Note: this library spawns containers and networks under the label 'owner=testingdock', which may be subject to aggressive manipulation and cleanup.

Testingdock also makes use of the 'flag' package to set global variables. Run `flag.Parse()` in your test suite main function. Possible flags are:

-testingdock.sequential (spawn containers sequentially instead of parallel)
-testingdock.verbose (verbose logging)

Index

Constants

This section is empty.

Variables

View Source
var SpawnSequential bool

SpawnSequential controls whether to spawn child containers in parallel or sequentially. This doesn't spawn all containers in parallel, only the ones that are on the same hierarchy level, e.g.:

// c1 and c2 are started in parallel after the network
network.After(c1)
network.After(c2)
// c3 and c4 are started in parallel after c1
c1.After(c3)
c1.After(c4)
View Source
var Verbose bool

Verbose logging

Functions

func RandomPort

func RandomPort(t testing.TB) string

RandomPort returns a random available port as a string.

func UnregisterAll

func UnregisterAll()

UnregisterAll unregisters all suites by closing the networks.

Types

type Container

type Container struct {
	ID, Name, Image string
	// contains filtered or unexported fields
}

Container is a docker container configuration, not necessarily a running or created container. This should usually be created via the NewContainer function.

func (*Container) After

func (c *Container) After(cc *Container)

After adds a child container (dependency, sort of) to the current container configuration in the same network.

type ContainerOpts

type ContainerOpts struct {
	ForcePull bool
	// AutoRemove is always set to true
	Config     *container.Config
	HostConfig *container.HostConfig
	Name       string
	// Function called on start and reset to check whether the container
	// is 'really' up, it will block until it returns nil. The zero
	// value is a function, which just checks the docker container
	// has started.
	HealthCheck HealthCheckFunc
	// default is 30s
	HealthCheckTimeout time.Duration
	// Function called when the containers are reset. The zero value is
	// a function, which will restart the container completely.
	Reset ResetFunc
}

ContainerOpts is an option struct for creating a docker container configuration.

type HealthCheckFunc

type HealthCheckFunc func(ctx context.Context) error

HealthCheckFunc is the type of a health checking function, which is supposed to return nil on success, indicating that a container is not only "up", but "accessible" in the specified way.

If the function returns an error, it will be called until it doesn't (blocking).

func HealthCheckCustom

func HealthCheckCustom(fn func() error) HealthCheckFunc

HealthCheckCustom is just a convenience wrapper to set a HealthCheckFunc without any arguments.

func HealthCheckHTTP

func HealthCheckHTTP(url string) HealthCheckFunc

HealthCheckHTTP is a pre-implemented HealthCheckFunc which checks if the given url returns http.StatusOk.

type Network

type Network struct {
	// contains filtered or unexported fields
}

Network is a struct representing a docker network configuration. This should usually not be created directly but via the NewNetwork function or in the Suite.

func (*Network) After

func (n *Network) After(c *Container)

After adds a child container to the current network configuration. These containers then kind of "depend" on the network and will be closed when the network closes.

type NetworkOpts

type NetworkOpts struct {
	Name string
}

NetworkOpts is used when creating a new network.

type ResetFunc

type ResetFunc func(ctx context.Context, c *Container) error

ResetFunc is the type of the container reset function, which is called on c.Reset().

func ResetCustom

func ResetCustom(fn func() error) ResetFunc

ResetCustom is just a convenience wrapper to set a ResetFunc.

type Suite

type Suite struct {
	// contains filtered or unexported fields
}

Suite represents a testing suite with a docker setup.

func GetOrCreateSuite

func GetOrCreateSuite(t testing.TB, name string, opts SuiteOpts) (*Suite, bool)

GetOrCreateSuite returns a suite with the given name. If such suite is not registered yet it creates it. Returns true if the suite was already there, otherwise false.

func (*Suite) Close

func (s *Suite) Close() error

Close stops the suites. This stops all networks in the suite and the underlying containers.

func (*Suite) Container

func (s *Suite) Container(opts ContainerOpts) *Container

Container creates a new docker container configuration with the given options.

func (*Suite) Network

func (s *Suite) Network(opts NetworkOpts) *Network

Network creates a new docker network configuration with the given options.

func (*Suite) Reset

func (s *Suite) Reset(ctx context.Context)

Reset "resets" the underlying docker containers in the network. This calls the ResetFunc and HealthCheckFunc for each of them. These can be passed in ContainerOpts when creating a container.

The context is passed explicitly to ResetFunc, where it can be used and implicitly to HealthCheckFunc where it may cancel the blocking health check loop.

func (*Suite) Start

func (s *Suite) Start(ctx context.Context)

Start starts the suite. This starts all networks in the suite and the underlying containers, as well as the daemon logger, if Verbosity is enabled.

type SuiteOpts

type SuiteOpts struct {
	// optional docker client, if one already exists
	Client *client.Client
	// whether to fail on instantiation errors
	Skip bool
}

SuiteOpts is an option struct for getting or creating a suite in GetOrCreateSuite.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL