package testcontainers

import "github.com/testcontainers/testcontainers-go"

Index ¶

• Constants
• type Container
• func GenericContainer(ctx context.Context, req GenericContainerRequest) (Container, error)
• type ContainerProvider
• type ContainerRequest
• type DeprecatedContainer
• type DockerContainer
• func (c *DockerContainer) Endpoint(ctx context.Context, proto string) (string, error)
• func (c *DockerContainer) GetContainerID() string
• func (c *DockerContainer) Host(ctx context.Context) (string, error)
• func (c *DockerContainer) Logs(ctx context.Context) (io.ReadCloser, error)
• func (c *DockerContainer) MappedPort(ctx context.Context, port nat.Port) (nat.Port, error)
• func (c *DockerContainer) Name(ctx context.Context) (string, error)
• func (c *DockerContainer) NetworkAliases(ctx context.Context) (map[string][]string, error)
• func (c *DockerContainer) Networks(ctx context.Context) ([]string, error)
• func (c *DockerContainer) PortEndpoint(ctx context.Context, port nat.Port, proto string) (string, error)
• func (c *DockerContainer) Ports(ctx context.Context) (nat.PortMap, error)
• func (c *DockerContainer) SessionID() string
• func (c *DockerContainer) Start(ctx context.Context) error
• func (c *DockerContainer) Terminate(ctx context.Context) error
• type DockerNetwork
• func (n *DockerNetwork) Remove(_ context.Context) error
• type DockerProvider
• func NewDockerProvider() (*DockerProvider, error)
• func (p *DockerProvider) CreateContainer(ctx context.Context, req ContainerRequest) (Container, error)
• func (p *DockerProvider) CreateNetwork(ctx context.Context, req NetworkRequest) (Network, error)
• func (p *DockerProvider) GetNetwork(ctx context.Context, req NetworkRequest) (types.NetworkResource, error)
• func (p *DockerProvider) RunContainer(ctx context.Context, req ContainerRequest) (Container, error)
• type GenericContainerRequest
• type GenericProvider
• type Network
• type NetworkProvider
• type NetworkRequest
• type ProviderType
• func (t ProviderType) GetProvider() (GenericProvider, error)
• type Reaper
• func NewReaper(ctx context.Context, sessionID string, provider ReaperProvider) (*Reaper, error)
• func (r *Reaper) Connect() (chan bool, error)
• func (r *Reaper) Labels() map[string]string
• type ReaperProvider

Constants ¶

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

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 {
	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

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 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) 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 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 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 ¶

container.go docker.go generic.go network.go reaper.go

Directories ¶