package testcontainers

const (
	Bridge        = "bridge" // Bridge network name (as well as driver)
	Podman        = "podman"
	ReaperDefault = "reaper_default" // Default network name when bridge is not available

)

const (
	TestcontainerLabel          = "org.testcontainers.golang"
	TestcontainerLabelSessionID = TestcontainerLabel + ".sessionId"
	TestcontainerLabelIsReaper  = TestcontainerLabel + ".reaper"

	ReaperDefaultImage = "docker.io/testcontainers/ryuk:0.3.4"
)

const StderrLog = "STDERR"

StderrLog is the log type for STDERR

const StdoutLog = "STDOUT"

StdoutLog is the log type for STDOUT

Variables ¶

var (
	ErrDuplicateMountTarget = errors.New("duplicate mount target detected")
)

var (
	ErrReuseEmptyName = errors.New("with reuse option a container name mustn't be empty")
)

Functions ¶

func SkipIfProviderIsNotHealthy ¶

func SkipIfProviderIsNotHealthy(t *testing.T)

SkipIfProviderIsNotHealthy is a utility function capable of skipping tests if the provider is not healthy, or running at all. This is a function designed to be used in your test, when Docker is not mandatory for CI/CD. In this way tests that depend on Testcontainers won't run if the provider is provisioned correctly.

Example¶

Code:

{
	SkipIfProviderIsNotHealthy(&testing.T{})
}

Types ¶

type BindMounter ¶

type BindMounter interface {
	GetBindOptions() *mount.BindOptions
}

BindMounter can optionally be implemented by mount sources to support advanced scenarios based on mount.BindOptions

type ComposeVersion ¶

type ComposeVersion interface {
	Format(parts ...string) string
}

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
	IsRunning() bool
	Start(context.Context) error                 // start the container
	Stop(context.Context, *time.Duration) error  // stop the container
	Terminate(context.Context) error             // terminate the container
	Logs(context.Context) (io.ReadCloser, error) // Get logs of the container
	FollowOutput(LogConsumer)
	StartLogProducer(context.Context) error
	StopLogProducer() error
	Name(context.Context) (string, error)                        // get container name
	State(context.Context) (*types.ContainerState, error)        // returns container's running state
	Networks(context.Context) ([]string, error)                  // get container networks
	NetworkAliases(context.Context) (map[string][]string, error) // get container network aliases for a network
	Exec(ctx context.Context, cmd []string) (int, io.Reader, error)
	ContainerIP(context.Context) (string, error)    // get container ip
	ContainerIPs(context.Context) ([]string, error) // get all container IPs
	CopyToContainer(ctx context.Context, fileContent []byte, containerFilePath string, fileMode int64) error
	CopyDirToContainer(ctx context.Context, hostDirPath string, containerParentPath string, fileMode int64) error
	CopyFileToContainer(ctx context.Context, hostFilePath string, containerFilePath string, fileMode int64) error
	CopyFileFromContainer(ctx context.Context, filePath string) (io.ReadCloser, error)
}

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

func ParallelContainers ¶

func ParallelContainers(ctx context.Context, reqs ParallelContainerRequest, opt ParallelContainersOptions) ([]Container, error)

ParallelContainers creates a generic containers with parameters and run it in parallel mode

type ContainerFile ¶

type ContainerFile struct {
	HostFilePath      string
	ContainerFilePath string
	FileMode          int64
}

type ContainerMount ¶

type ContainerMount struct {
	// Source is typically either a GenericBindMountSource or a GenericVolumeMountSource
	Source ContainerMountSource
	// Target is the path where the mount should be mounted within the container
	Target ContainerMountTarget
	// ReadOnly determines if the mount should be read-only
	ReadOnly bool
}

ContainerMount models a mount into a container

func BindMount ¶

func BindMount(hostPath string, mountTarget ContainerMountTarget) ContainerMount

BindMount returns a new ContainerMount with a GenericBindMountSource as source This is a convenience method to cover typical use cases.

func VolumeMount ¶

func VolumeMount(volumeName string, mountTarget ContainerMountTarget) ContainerMount

VolumeMount returns a new ContainerMount with a GenericVolumeMountSource as source This is a convenience method to cover typical use cases.

type ContainerMountSource ¶

type ContainerMountSource interface {
	// Source will be used as Source field in the final mount
	// this might either be a volume name, a host path or might be empty e.g. for Tmpfs
	Source() string

	// Type determines the final mount type
	// possible options are limited by the Docker API
	Type() MountType
}

ContainerMountSource is the base for all mount sources

type ContainerMountTarget ¶

type ContainerMountTarget string

ContainerMountTarget represents the target path within a container where the mount will be available Note that mount targets must be unique. It's not supported to mount different sources to the same target.

func (ContainerMountTarget) Target ¶

func (t ContainerMountTarget) Target() string

type ContainerMounts ¶

type ContainerMounts []ContainerMount

ContainerMounts represents a collection of mounts for a container

func Mounts ¶

func Mounts(mounts ...ContainerMount) ContainerMounts

Mounts returns a ContainerMounts to support a more fluent API

type ContainerProvider ¶

type ContainerProvider interface {
	CreateContainer(context.Context, ContainerRequest) (Container, error)        // create a container without starting it
	ReuseOrCreateContainer(context.Context, ContainerRequest) (Container, error) // reuses a container if it exists or creates a container without starting
	RunContainer(context.Context, ContainerRequest) (Container, error)           // create a container and start it
	Health(context.Context) error
	Config() TestContainersConfig
}

ContainerProvider allows the creation of containers on an arbitrary system

type ContainerRequest ¶

type ContainerRequest struct {
	FromDockerfile
	Image           string
	Entrypoint      []string
	Env             map[string]string
	ExposedPorts    []string // allow specifying protocol info
	Cmd             []string
	Labels          map[string]string
	Mounts          ContainerMounts
	Tmpfs           map[string]string
	RegistryCred    string
	WaitingFor      wait.Strategy
	Name            string // for specifying container name
	Hostname        string
	ExtraHosts      []string
	Privileged      bool                // for starting privileged container
	Networks        []string            // for specifying network names
	NetworkAliases  map[string][]string // for specifying network aliases
	NetworkMode     container.NetworkMode
	Resources       container.Resources
	Files           []ContainerFile // files which will be copied when container starts
	User            string          // for specifying uid:gid
	SkipReaper      bool            // indicates whether we skip setting up a reaper for this
	ReaperImage     string          // alternative reaper image
	AutoRemove      bool            // if set to true, the container will be removed from the host when stopped
	AlwaysPullImage bool            // Always pull image
	ImagePlatform   string          // ImagePlatform describes the platform which the image runs on.
	Binds           []string
	ShmSize         int64    // Amount of memory shared with the host (in bytes)
	CapAdd          []string // Add Linux capabilities
	CapDrop         []string // Drop Linux capabilities
}

ContainerRequest represents the parameters used to get a running container

func (*ContainerRequest) GetBuildArgs ¶

func (c *ContainerRequest) GetBuildArgs() map[string]*string

GetBuildArgs returns the env args to be used when creating from Dockerfile

func (*ContainerRequest) GetContext ¶

func (c *ContainerRequest) GetContext() (io.Reader, error)

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

func (c *ContainerRequest) ShouldBuildImage() bool

func (*ContainerRequest) ShouldPrintBuildLog ¶

func (c *ContainerRequest) ShouldPrintBuildLog() bool

func (*ContainerRequest) Validate ¶

func (c *ContainerRequest) Validate() error

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

type DefaultNetwork ¶

type DefaultNetwork string

func (DefaultNetwork) ApplyDockerTo ¶

func (n DefaultNetwork) ApplyDockerTo(opts *DockerProviderOptions)

func (DefaultNetwork) ApplyGenericTo ¶

func (n DefaultNetwork) ApplyGenericTo(opts *GenericProviderOptions)

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

type DockerBindMountSource struct {
	*mount.BindOptions

	// HostPath is the path mounted into the container
	// the same host path might be mounted to multiple locations withing a single container
	HostPath string
}

func (DockerBindMountSource) GetBindOptions ¶

func (s DockerBindMountSource) GetBindOptions() *mount.BindOptions

func (DockerBindMountSource) Source ¶

func (s DockerBindMountSource) Source() string

func (DockerBindMountSource) Type ¶

func (DockerBindMountSource) Type() MountType

type DockerCompose ¶

type DockerCompose interface {
	Down() ExecError
	Invoke() ExecError
	WaitForService(string, wait.Strategy) DockerCompose
	WithCommand([]string) DockerCompose
	WithEnv(map[string]string) DockerCompose
	WithExposedService(string, int, wait.Strategy) DockerCompose
}

DockerCompose defines the contract for running Docker Compose

type DockerContainer ¶

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

DockerContainer represents a container started using Docker

func (*DockerContainer) ContainerIP ¶

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

ContainerIP gets the IP address of the primary network within the container.

func (*DockerContainer) ContainerIPs ¶

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

ContainerIPs gets the IP addresses of all the networks within the container.

func (*DockerContainer) CopyDirToContainer ¶

func (c *DockerContainer) CopyDirToContainer(ctx context.Context, hostDirPath string, containerParentPath string, fileMode int64) error

CopyDirToContainer copies the contents of a directory to a parent path in the container. This parent path must exist in the container first as we cannot create it

func (*DockerContainer) CopyFileFromContainer ¶

func (c *DockerContainer) CopyFileFromContainer(ctx context.Context, filePath string) (io.ReadCloser, error)

func (*DockerContainer) CopyFileToContainer ¶

func (c *DockerContainer) CopyFileToContainer(ctx context.Context, hostFilePath string, containerFilePath string, fileMode int64) error

func (*DockerContainer) CopyToContainer ¶

func (c *DockerContainer) CopyToContainer(ctx context.Context, fileContent []byte, containerFilePath string, fileMode int64) error

CopyToContainer copies fileContent data to a file in container

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

func (c *DockerContainer) Exec(ctx context.Context, cmd []string) (int, io.Reader, error)

func (*DockerContainer) FollowOutput ¶

func (c *DockerContainer) FollowOutput(consumer LogConsumer)

FollowOutput adds a LogConsumer to be sent logs from the container's STDOUT and STDERR

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

func (c *DockerContainer) IsRunning() bool

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

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

StartLogProducer will start a concurrent process that will continuously read logs from the container and will send them to each added LogConsumer

func (*DockerContainer) State ¶

func (c *DockerContainer) State(ctx context.Context) (*types.ContainerState, error)

State returns container's running state

func (*DockerContainer) Stop ¶

func (c *DockerContainer) Stop(ctx context.Context, timeout *time.Duration) error

Stop will stop an already started container

In case the container fails to stop gracefully within a time frame specified by the timeout argument, it is forcefully terminated (killed).

If the timeout is nil, the container's StopTimeout value is used, if set, otherwise the engine default. A negative timeout value can be specified, meaning no timeout, i.e. no forceful termination is performed.

func (*DockerContainer) StopLogProducer ¶

func (c *DockerContainer) StopLogProducer() error

StopLogProducer will stop the concurrent process that is reading logs and sending them to each added LogConsumer

func (*DockerContainer) Terminate ¶

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

Terminate is used to kill the container. It is usually 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(ctx context.Context) error

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

type DockerProvider ¶

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

DockerProvider implements the ContainerProvider interface

func NewDockerProvider ¶

func NewDockerProvider(provOpts ...DockerProviderOption) (*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) Config ¶

func (p *DockerProvider) Config() TestContainersConfig

Config provides the TestContainersConfig read from $HOME/.testcontainers.properties or the environment variables

func (*DockerProvider) CreateContainer ¶

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

CreateContainer fulfills a request for a container without starting it

Example¶

Code:

{
	ctx := context.Background()
	req := ContainerRequest{
		Image:        "docker.io/nginx:alpine",
		ExposedPorts: []string{"80/tcp"},
		WaitingFor:   wait.ForHTTP("/"),
	}
	nginxC, _ := GenericContainer(ctx, GenericContainerRequest{
		ContainerRequest: req,
		Started:          true,
	})
	defer nginxC.Terminate(ctx)
}

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

func (p *DockerProvider) GetGatewayIP(ctx context.Context) (string, error)

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

func (p *DockerProvider) Health(ctx context.Context) (err error)

Health measure the healthiness of the provider. Right now we leverage the docker-client ping endpoint to see if the daemon is reachable.

func (*DockerProvider) ReuseOrCreateContainer ¶

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

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

type DockerProviderOption interface {
	ApplyDockerTo(opts *DockerProviderOptions)
}

DockerProviderOption defines a common interface to modify DockerProviderOptions These can be passed to NewDockerProvider in a variadic way to customize the returned DockerProvider instance

func Generic2DockerOptions ¶

func Generic2DockerOptions(opts ...GenericProviderOption) []DockerProviderOption

func WithDefaultBridgeNetwork ¶

func WithDefaultBridgeNetwork(bridgeNetworkName string) DockerProviderOption

type DockerProviderOptionFunc ¶

type DockerProviderOptionFunc func(opts *DockerProviderOptions)

DockerProviderOptionFunc is a shorthand to implement the DockerProviderOption interface

func (DockerProviderOptionFunc) ApplyDockerTo ¶

func (f DockerProviderOptionFunc) ApplyDockerTo(opts *DockerProviderOptions)

type DockerProviderOptions ¶

type DockerProviderOptions struct {
	*GenericProviderOptions
	// contains filtered or unexported fields
}

DockerProviderOptions defines options applicable to DockerProvider

type DockerTmpfsMountSource ¶

type DockerTmpfsMountSource struct {
	GenericTmpfsMountSource
	*mount.TmpfsOptions
}

func (DockerTmpfsMountSource) GetTmpfsOptions ¶

func (s DockerTmpfsMountSource) GetTmpfsOptions() *mount.TmpfsOptions

type DockerVolumeMountSource ¶

type DockerVolumeMountSource struct {
	*mount.VolumeOptions

	// Name refers to the name of the volume to be mounted
	// the same volume might be mounted to multiple locations within a single container
	Name string
}

func (DockerVolumeMountSource) GetVolumeOptions ¶

func (s DockerVolumeMountSource) GetVolumeOptions() *mount.VolumeOptions

func (DockerVolumeMountSource) Source ¶

func (s DockerVolumeMountSource) Source() string

func (DockerVolumeMountSource) Type ¶

func (DockerVolumeMountSource) Type() MountType

type ExecError ¶

type ExecError struct {
	Command      []string
	StdoutOutput []byte
	StderrOutput []byte
	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 FileFromContainer ¶

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

func (*FileFromContainer) Close ¶

func (fc *FileFromContainer) Close() error

func (*FileFromContainer) Read ¶

func (fc *FileFromContainer) Read(b []byte) (int, error)

type FromDockerfile ¶

type FromDockerfile struct {
	Context        string             // the path to the context of of the docker build
	ContextArchive io.Reader          // the tar archive file to send to docker that contains the build context
	Dockerfile     string             // the path from the context to the Dockerfile for the image, defaults to "Dockerfile"
	BuildArgs      map[string]*string // enable user to pass build args to docker daemon
	PrintBuildLog  bool               // enable user to print build log
}

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

type GenericBindMountSource ¶

type GenericBindMountSource struct {
	// HostPath is the path mounted into the container
	// the same host path might be mounted to multiple locations withing a single container
	HostPath string
}

GenericBindMountSource implements ContainerMountSource and represents a bind mount Optionally mount.BindOptions might be added for advanced scenarios

func (GenericBindMountSource) Source ¶

func (s GenericBindMountSource) Source() string

func (GenericBindMountSource) Type ¶

func (GenericBindMountSource) Type() MountType

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
	Logger           Logging      // provide a container specific Logging - use default global logger if empty
	Reuse            bool         // reuse an existing container if it exists or create a new one. a container name mustn't be empty
}

GenericContainerRequest represents parameters to a generic container

type GenericNetworkRequest ¶

type GenericNetworkRequest struct {
	NetworkRequest              // embedded request for provider
	ProviderType   ProviderType // which provider to use, Docker if empty
}

GenericNetworkRequest represents parameters to a generic network

type GenericProvider ¶

type GenericProvider interface {
	ContainerProvider
	NetworkProvider
}

GenericProvider represents an abstraction for container and network providers

type GenericProviderOption ¶

type GenericProviderOption interface {
	ApplyGenericTo(opts *GenericProviderOptions)
}

GenericProviderOption defines a common interface to modify GenericProviderOptions These options can be passed to GetProvider in a variadic way to customize the returned GenericProvider instance

type GenericProviderOptionFunc ¶

type GenericProviderOptionFunc func(opts *GenericProviderOptions)

GenericProviderOptionFunc is a shorthand to implement the GenericProviderOption interface

func (GenericProviderOptionFunc) ApplyGenericTo ¶

func (f GenericProviderOptionFunc) ApplyGenericTo(opts *GenericProviderOptions)

type GenericProviderOptions ¶

type GenericProviderOptions struct {
	Logger         Logging
	DefaultNetwork string
}

GenericProviderOptions defines options applicable to all providers

type GenericTmpfsMountSource ¶

type GenericTmpfsMountSource struct {
}

GenericTmpfsMountSource implements ContainerMountSource and represents a TmpFS mount Optionally mount.TmpfsOptions might be added for advanced scenarios

func (GenericTmpfsMountSource) Source ¶

func (s GenericTmpfsMountSource) Source() string

func (GenericTmpfsMountSource) Type ¶

func (GenericTmpfsMountSource) Type() MountType

type GenericVolumeMountSource ¶

type GenericVolumeMountSource struct {
	// Name refers to the name of the volume to be mounted
	// the same volume might be mounted to multiple locations within a single container
	Name string
}

GenericVolumeMountSource implements ContainerMountSource and represents a volume mount

func (GenericVolumeMountSource) Source ¶

func (s GenericVolumeMountSource) Source() string

func (GenericVolumeMountSource) Type ¶

func (GenericVolumeMountSource) Type() MountType

type ImageBuildInfo ¶

type ImageBuildInfo interface {
	GetContext() (io.Reader, error)   // the path to the build context
	GetDockerfile() string            // the relative path to the Dockerfile, including the fileitself
	ShouldPrintBuildLog() bool        // allow build log to be printed to stdout
	ShouldBuildImage() bool           // return true if the image needs to be built
	GetBuildArgs() map[string]*string // return the environment args used to build the from Dockerfile
}

ImageBuildInfo defines what is needed to build an image

type LocalDockerCompose ¶

type LocalDockerCompose struct {
	ComposeVersion
	*LocalDockerComposeOptions
	Executable       string
	ComposeFilePaths []string

	Identifier string
	Cmd        []string
	Env        map[string]string
	Services   map[string]interface{}

	WaitStrategyMap map[waitService]wait.Strategy
	// 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

Example¶

Code:

{
	_ = LocalDockerCompose{
		Executable: "docker-compose",
		ComposeFilePaths: []string{
			"/path/to/docker-compose.yml",
			"/path/to/docker-compose-1.yml",
			"/path/to/docker-compose-2.yml",
			"/path/to/docker-compose-3.yml",
		},
		Identifier: "my_project",
		Cmd: []string{
			"up", "-d",
		},
		Env: map[string]string{
			"FOO": "foo",
			"BAR": "bar",
		},
	}
}

func NewLocalDockerCompose ¶

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

NewLocalDockerCompose returns an instance of the local Docker Compose, using an array of Docker Compose file paths and an identifier for the Compose execution.

It will iterate through the array adding '-f compose-file-path' flags to the local Docker Compose execution. The identifier represents the name of the execution, which will define the name of the underlying Docker network and the name of the running Compose services.

Example¶

Code:

{
	path := "/path/to/docker-compose.yml"

	_ = NewLocalDockerCompose([]string{path}, "my_project")
}

func (*LocalDockerCompose) Down ¶

func (dc *LocalDockerCompose) Down() ExecError

Down executes docker-compose down

Example¶

Code:

{
	path := "/path/to/docker-compose.yml"

	compose := NewLocalDockerCompose([]string{path}, "my_project")

	execError := compose.WithCommand([]string{"up", "-d"}).Invoke()
	if execError.Error != nil {
		_ = fmt.Errorf("Failed when running: %v", execError.Command)
	}

	execError = compose.Down()
	if execError.Error != nil {
		_ = fmt.Errorf("Failed when running: %v", execError.Command)
	}
}

func (*LocalDockerCompose) Invoke ¶

func (dc *LocalDockerCompose) Invoke() ExecError

Invoke invokes the docker compose

Example¶

Code:

{
	path := "/path/to/docker-compose.yml"

	compose := NewLocalDockerCompose([]string{path}, "my_project")

	execError := compose.
		WithCommand([]string{"up", "-d"}).
		WithEnv(map[string]string{
			"bar": "BAR",
		}).
		Invoke()
	if execError.Error != nil {
		_ = fmt.Errorf("Failed when running: %v", execError.Command)
	}
}

func (*LocalDockerCompose) WaitForService ¶

func (dc *LocalDockerCompose) WaitForService(service string, strategy wait.Strategy) DockerCompose

WaitForService sets the strategy for the service that is to be waited on

func (*LocalDockerCompose) WithCommand ¶

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

WithCommand assigns the command

Example¶

Code:

{
	path := "/path/to/docker-compose.yml"

	compose := NewLocalDockerCompose([]string{path}, "my_project")

	compose.WithCommand([]string{"up", "-d"})
}

func (*LocalDockerCompose) WithEnv ¶

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

WithEnv assigns the environment

Example¶

Code:

{
	path := "/path/to/docker-compose.yml"

	compose := NewLocalDockerCompose([]string{path}, "my_project")

	compose.WithEnv(map[string]string{
		"FOO": "foo",
		"BAR": "bar",
	})
}

func (*LocalDockerCompose) WithExposedService ¶

func (dc *LocalDockerCompose) WithExposedService(service string, port int, strategy wait.Strategy) DockerCompose

WithExposedService sets the strategy for the service that is to be waited on. If multiple strategies are given for a single service running on different ports, both strategies will be applied on the same container

type LocalDockerComposeOption ¶

type LocalDockerComposeOption interface {
	ApplyToLocalCompose(opts *LocalDockerComposeOptions)
}

LocalDockerComposeOption defines a common interface to modify LocalDockerComposeOptions These options can be passed to NewLocalDockerCompose in a variadic way to customize the returned LocalDockerCompose instance

type LocalDockerComposeOptions ¶

type LocalDockerComposeOptions struct {
	Logger Logging
}

LocalDockerComposeOptions defines options applicable to LocalDockerCompose

type LocalDockerComposeOptionsFunc ¶

type LocalDockerComposeOptionsFunc func(opts *LocalDockerComposeOptions)

LocalDockerComposeOptionsFunc is a shorthand to implement the LocalDockerComposeOption interface

func (LocalDockerComposeOptionsFunc) ApplyToLocalCompose ¶

func (f LocalDockerComposeOptionsFunc) ApplyToLocalCompose(opts *LocalDockerComposeOptions)

type Log ¶

type Log struct {
	LogType string
	Content []byte
}

Log represents a message that was created by a process, LogType is either "STDOUT" or "STDERR", Content is the byte contents of the message itself

type LogConsumer ¶

type LogConsumer interface {
	Accept(Log)
}

LogConsumer represents any object that can handle a Log, it is up to the LogConsumer instance what to do with the log

type LoggerOption ¶

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

func WithLogger ¶

func WithLogger(logger Logging) LoggerOption

WithLogger is a generic option that implements GenericProviderOption, DockerProviderOption and LocalDockerComposeOption It replaces the global Logging implementation with a user defined one e.g. to aggregate logs from testcontainers with the logs of specific test case

func (LoggerOption) ApplyDockerTo ¶

func (o LoggerOption) ApplyDockerTo(opts *DockerProviderOptions)

func (LoggerOption) ApplyGenericTo ¶

func (o LoggerOption) ApplyGenericTo(opts *GenericProviderOptions)

func (LoggerOption) ApplyToLocalCompose ¶

func (o LoggerOption) ApplyToLocalCompose(opts *LocalDockerComposeOptions)

type Logging ¶

type Logging interface {
	Printf(format string, v ...interface{})
}

Logging defines the Logger interface

var Logger Logging = log.New(os.Stderr, "", log.LstdFlags)

Logger is the default log instance

func TestLogger ¶

func TestLogger(tb testing.TB) Logging

TestLogger returns a Logging implementation for testing.TB This way logs from testcontainers are part of the test output of a test suite or test case

type MountType ¶

type MountType uint

const (
	MountTypeBind MountType = iota
	MountTypeVolume
	MountTypeTmpfs
	MountTypePipe
)

type Network ¶

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

Network allows getting info about a single network instance

func GenericNetwork ¶

func GenericNetwork(ctx context.Context, req GenericNetworkRequest) (Network, error)

GenericNetwork creates a generic network with parameters

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
	IPAM           *network.IPAM

	SkipReaper  bool   // indicates whether we skip setting up a reaper for this
	ReaperImage string //alternative reaper registry
}

NetworkRequest represents the parameters used to get a network

type ParallelContainerRequest ¶

type ParallelContainerRequest []GenericContainerRequest

type ParallelContainersError ¶

type ParallelContainersError struct {
	Errors []ParallelContainersRequestError
}

func (ParallelContainersError) Error ¶

func (gpe ParallelContainersError) Error() string

type ParallelContainersOptions ¶

type ParallelContainersOptions struct {
	WorkersCount int // count of parallel workers. If field empty(zero), default value will be 'defaultWorkersCount'
}

ParallelContainersOptions represents additional options for parallel running

type ParallelContainersRequestError ¶

type ParallelContainersRequestError struct {
	Request GenericContainerRequest
	Error   error
}

ParallelContainersRequestError represents error from parallel request

type ProviderType ¶

type ProviderType int

ProviderType is an enum for the possible providers

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

possible provider types

func (ProviderType) GetProvider ¶

func (t ProviderType) GetProvider(opts ...GenericProviderOption) (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, reaperImageName string) (*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)
	Config() TestContainersConfig
}

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

type TestContainersConfig ¶

type TestContainersConfig struct {
	Host           string `properties:"docker.host,default="`
	TLSVerify      int    `properties:"docker.tls.verify,default=0"`
	CertPath       string `properties:"docker.cert.path,default="`
	RyukPrivileged bool   `properties:"ryuk.container.privileged,default=false"`
}

or through Decode

func NewDockerClient ¶

func NewDockerClient() (cli *client.Client, host string, tcConfig TestContainersConfig, err error)

type TmpfsMounter ¶

type TmpfsMounter interface {
	GetTmpfsOptions() *mount.TmpfsOptions
}

TmpfsMounter can optionally be implemented by mount sources to support advanced scenarios based on mount.TmpfsOptions

type VolumeMounter ¶

type VolumeMounter interface {
	GetVolumeOptions() *mount.VolumeOptions
}

VolumeMounter can optionally be implemented by mount sources to support advanced scenarios based on mount.VolumeOptions

Source Files ¶

compose.go container.go docker.go docker_mounts.go file.go generic.go logconsumer.go logger.go mounts.go network.go parallel.go reaper.go session.go testing.go

Directories ¶

Path	Synopsis
testresources
wait

Version: v0.15.0
Published: Oct 24, 2022
Platform: js/wasm
Imports: 40 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