package testcontainers

const (
	TestcontainerLabel          = "org.testcontainers.golang"
	TestcontainerLabelSessionID = TestcontainerLabel + ".sessionId"
	TestcontainerLabelIsReaper  = TestcontainerLabel + ".reaper"
	ReaperDefaultImage          = "quay.io/testcontainers/ryuk:0.2.2"
)

TestcontainerLabel is used as a base for docker labels

Functions ¶

Types ¶

type Container ¶

type Container interface {
	GetContainerID() string                                         // get the container id from the provider
	Endpoint(context.Context, string) (string, error)               // get proto://ip:port string for the first exposed port
	PortEndpoint(context.Context, nat.Port, string) (string, error) // get proto://ip:port string for the given exposed port
	Host(context.Context) (string, error)                           // get host where the container port is exposed
	MappedPort(context.Context, nat.Port) (nat.Port, error)         // get externally mapped port for a container port
	Ports(context.Context) (nat.PortMap, error)                     // get all exposed ports
	SessionID() string                                              // get session id
	Start(context.Context) error                                    // start the container
	Terminate(context.Context) error                                // terminate the container
	Logs(context.Context) (io.ReadCloser, error)                    // Get logs of the container
	Name(context.Context) (string, error)                           // get container name
	Networks(context.Context) ([]string, error)                     // get container networks
	NetworkAliases(context.Context) (map[string][]string, error)    // get container network aliases for a network
}

Container allows getting info about and controlling a single container instance

func GenericContainer ¶

func GenericContainer(ctx context.Context, req GenericContainerRequest) (Container, error)

GenericContainer creates a generic container with parameters

type ContainerProvider ¶

type ContainerProvider interface {
	CreateContainer(context.Context, ContainerRequest) (Container, error) // create a container without starting it
	RunContainer(context.Context, ContainerRequest) (Container, error)    // create a container and start it
}

ContainerProvider allows the creation of containers on an arbitrary system

type ContainerRequest ¶

type ContainerRequest struct {
	FromDockerfile
	Image          string
	Env            map[string]string
	ExposedPorts   []string // allow specifying protocol info
	Cmd            []string
	Labels         map[string]string
	BindMounts     map[string]string
	RegistryCred   string
	WaitingFor     wait.Strategy
	Name           string              // for specifying container name
	Privileged     bool                // for starting privileged container
	Networks       []string            // for specifying network names
	NetworkAliases map[string][]string // for specifying network aliases
	SkipReaper     bool                // indicates whether we skip setting up a reaper for this
}

ContainerRequest represents the parameters used to get a running container

func (*ContainerRequest) GetContext ¶

func (c *ContainerRequest) GetContext() string

GetContext retrieve the build context for the request

func (*ContainerRequest) GetDockerfile ¶

func (c *ContainerRequest) GetDockerfile() string

GetDockerfile returns the Dockerfile from the ContainerRequest, defaults to "Dockerfile"

func (*ContainerRequest) Validate ¶

func (c *ContainerRequest) Validate() error

Validate ensures that the ContainerRequest does not have invalid paramters configured to it ex. make sure you are not specifying both an image as well as a context

type DeprecatedContainer ¶

type DeprecatedContainer interface {
	GetHostEndpoint(ctx context.Context, port string) (string, string, error)
	GetIPAddress(ctx context.Context) (string, error)
	LivenessCheckPorts(ctx context.Context) (nat.PortSet, error)
	Terminate(ctx context.Context) error
}

DeprecatedContainer shows methods that were supported before, but are now deprecated Deprecated: Use Container

type DockerCompose ¶

type DockerCompose interface {
	Down() ExecError
	Invoke() ExecError
	WithCommand([]string) DockerCompose
	WithEnv(map[string]string) DockerCompose
}

DockerCompose defines the contract for running Docker Compose

type DockerContainer ¶

type DockerContainer struct {
	// Container ID from Docker
	ID         string
	WaitingFor wait.Strategy
	// contains filtered or unexported fields
}

DockerContainer represents a container started using Docker

func (*DockerContainer) Endpoint ¶

func (c *DockerContainer) Endpoint(ctx context.Context, proto string) (string, error)

Endpoint gets proto://host:port string for the first exposed port Will returns just host:port if proto is ""

func (*DockerContainer) GetContainerID ¶

func (c *DockerContainer) GetContainerID() string

func (*DockerContainer) Host ¶

func (c *DockerContainer) Host(ctx context.Context) (string, error)

Host gets host (ip or name) of the docker daemon where the container port is exposed Warning: this is based on your Docker host setting. Will fail if using an SSH tunnel You can use the "TC_HOST" env variable to set this yourself

func (*DockerContainer) Logs ¶

func (c *DockerContainer) Logs(ctx context.Context) (io.ReadCloser, error)

Logs will fetch both STDOUT and STDERR from the current container. Returns a ReadCloser and leaves it up to the caller to extract what it wants.

func (*DockerContainer) MappedPort ¶

func (c *DockerContainer) MappedPort(ctx context.Context, port nat.Port) (nat.Port, error)

MappedPort gets externally mapped port for a container port

func (*DockerContainer) Name ¶

func (c *DockerContainer) Name(ctx context.Context) (string, error)

Name gets the name of the container.

func (*DockerContainer) NetworkAliases ¶

func (c *DockerContainer) NetworkAliases(ctx context.Context) (map[string][]string, error)

NetworkAliases gets the aliases of the container for the networks it is attached to.

func (*DockerContainer) Networks ¶

func (c *DockerContainer) Networks(ctx context.Context) ([]string, error)

Networks gets the names of the networks the container is attached to.

func (*DockerContainer) PortEndpoint ¶

func (c *DockerContainer) PortEndpoint(ctx context.Context, port nat.Port, proto string) (string, error)

PortEndpoint gets proto://host:port string for the given exposed port Will returns just host:port if proto is ""

func (*DockerContainer) Ports ¶

func (c *DockerContainer) Ports(ctx context.Context) (nat.PortMap, error)

Ports gets the exposed ports for the container.

func (*DockerContainer) SessionID ¶

func (c *DockerContainer) SessionID() string

SessionID gets the current session id

func (*DockerContainer) Start ¶

func (c *DockerContainer) Start(ctx context.Context) error

Start will start an already created container

func (*DockerContainer) Terminate ¶

func (c *DockerContainer) Terminate(ctx context.Context) error

Terminate is used to kill the container. It is usally triggered by as defer function.

type DockerNetwork ¶

type DockerNetwork struct {
	ID     string // Network ID from Docker
	Driver string
	Name   string
	// contains filtered or unexported fields
}

DockerNetwork represents a network started using Docker

func (*DockerNetwork) Remove ¶

func (n *DockerNetwork) Remove(_ context.Context) error

Remove is used to remove the network. It is usually triggered by as defer function.

type DockerProvider ¶

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

DockerProvider implements the ContainerProvider interface

func NewDockerProvider ¶

func NewDockerProvider() (*DockerProvider, error)

NewDockerProvider creates a Docker provider with the EnvClient

func (*DockerProvider) BuildImage ¶

func (p *DockerProvider) BuildImage(ctx context.Context, img ImageBuildInfo) (string, error)

BuildImage will build and image from context and Dockerfile, then return the tag

func (*DockerProvider) CreateContainer ¶

func (p *DockerProvider) CreateContainer(ctx context.Context, req ContainerRequest) (Container, error)

CreateContainer fulfills a request for a container without starting it

func (*DockerProvider) CreateNetwork ¶

func (p *DockerProvider) CreateNetwork(ctx context.Context, req NetworkRequest) (Network, error)

CreateNetwork returns the object representing a new network identified by its name

func (*DockerProvider) GetNetwork ¶

func (p *DockerProvider) GetNetwork(ctx context.Context, req NetworkRequest) (types.NetworkResource, error)

GetNetwork returns the object representing the network identified by its name

func (*DockerProvider) RunContainer ¶

func (p *DockerProvider) RunContainer(ctx context.Context, req ContainerRequest) (Container, error)

RunContainer takes a RequestContainer as input and it runs a container via the docker sdk

type ExecError ¶

type ExecError struct {
	Error  error
	Stdout error
	Stderr error
}

ExecError is super struct that holds any information about an execution error, so the client code can handle the result

type FromDockerfile ¶

type FromDockerfile struct {
	Context    string // the path to the context of of the docker build
	Dockerfile string // the path from the context to the Dockerfile for the image, defaults to "Dockerfile"
}

FromDockerfile represents the parameters needed to build an image from a Dockerfile rather than using a pre-built one

type GenericContainerRequest ¶

type GenericContainerRequest struct {
	ContainerRequest              // embedded request for provider
	Started          bool         // whether to auto-start the container
	ProviderType     ProviderType // which provider to use, Docker if empty
}

GenericContainerRequest represents parameters to a generic container

type GenericProvider ¶

type GenericProvider interface {
	ContainerProvider
	NetworkProvider
}

GenericProvider represents an abstraction for container and network providers

type ImageBuildInfo ¶

type ImageBuildInfo interface {
	GetContext() string    // the path to the build context
	GetDockerfile() string // the relative path to the Dockerfile, including the fileitself
}

ImageBuildInfo defines what is needed to build an image

type LocalDockerCompose ¶

type LocalDockerCompose struct {
	Executable       string
	ComposeFilePaths []string

	Identifier string
	Cmd        []string
	Env        map[string]string
	// contains filtered or unexported fields
}

LocalDockerCompose represents a Docker Compose execution using local binary docker-compose or docker-compose.exe, depending on the underlying platform

func NewLocalDockerCompose ¶

func NewLocalDockerCompose(filePaths []string, identifier string) *LocalDockerCompose

NewLocalDockerCompose returns an instance of the local Docker Compose

func (*LocalDockerCompose) Down ¶

func (dc *LocalDockerCompose) Down() ExecError

Down executes docker-compose down

func (*LocalDockerCompose) Invoke ¶

func (dc *LocalDockerCompose) Invoke() ExecError

Invoke invokes the docker compose

func (*LocalDockerCompose) WithCommand ¶

func (dc *LocalDockerCompose) WithCommand(cmd []string) DockerCompose

WithCommand assigns the command

func (*LocalDockerCompose) WithEnv ¶

func (dc *LocalDockerCompose) WithEnv(env map[string]string) DockerCompose

WithEnv assigns the environment

type Network ¶

type Network interface {
	Remove(context.Context) error // removes the network
}

Network allows getting info about a single network instance

type NetworkProvider ¶

type NetworkProvider interface {
	CreateNetwork(context.Context, NetworkRequest) (Network, error)            // create a network
	GetNetwork(context.Context, NetworkRequest) (types.NetworkResource, error) // get a network
}

NetworkProvider allows the creation of networks on an arbitrary system

type NetworkRequest ¶

type NetworkRequest struct {
	Driver         string
	CheckDuplicate bool
	Internal       bool
	EnableIPv6     bool
	Name           string
	Labels         map[string]string
	Attachable     bool

	SkipReaper bool // indicates whether we skip setting up a reaper for this
}

NetworkRequest represents the parameters used to get a network

type ProviderType ¶

type ProviderType int

ProviderType is an enum for the possible providers

const (
	ProviderDocker ProviderType = iota // Docker is default = 0
)

possible provider types

func (ProviderType) GetProvider ¶

func (t ProviderType) GetProvider() (GenericProvider, error)

GetProvider provides the provider implementation for a certain type

type Reaper ¶

type Reaper struct {
	Provider  ReaperProvider
	SessionID string
	Endpoint  string
}

Reaper is used to start a sidecar container that cleans up resources

func NewReaper ¶

func NewReaper(ctx context.Context, sessionID string, provider ReaperProvider) (*Reaper, error)

NewReaper creates a Reaper with a sessionID to identify containers and a provider to use

func (*Reaper) Connect ¶

func (r *Reaper) Connect() (chan bool, error)

Connect runs a goroutine which can be terminated by sending true into the returned channel

func (*Reaper) Labels ¶

func (r *Reaper) Labels() map[string]string

Labels returns the container labels to use so that this Reaper cleans them up

type ReaperProvider ¶

type ReaperProvider interface {
	RunContainer(ctx context.Context, req ContainerRequest) (Container, error)
}

ReaperProvider represents a provider for the reaper to run itself with The ContainerProvider interface should usually satisfy this as well, so it is pluggable

Source Files ¶

compose.go container.go docker.go generic.go network.go reaper.go utility.go

Directories ¶

Path	Synopsis
wait

Version: v0.0.9-compose-1
Published: Oct 29, 2019
Platform: js/wasm
Imports: 26 packages
Last checked: now –

Tools for package owners.

?	: This menu
/	: Search site
f	: Jump to identifier
g then g	: Go to top of page
g then b	: Go to end of page
G	: Go to end of page
g then i	: Go to index
g then e	: Go to examples