Documentation
¶
Index ¶
- Constants
- Variables
- func NewDockerCompose(filePaths ...string) (*dockerCompose, error)
- func NewDockerComposeWith(opts ...ComposeStackOption) (*dockerCompose, error)
- func SkipIfProviderIsNotHealthy(t *testing.T)
- type BindMounter
- type ComposeStack
- type ComposeStackFiles
- type ComposeStackOption
- type ComposeVersion
- type Container
- type ContainerFile
- type ContainerMount
- type ContainerMountSource
- type ContainerMountTarget
- type ContainerMounts
- type ContainerProvider
- type ContainerRequest
- func (c *ContainerRequest) GetAuthConfigs() map[string]types.AuthConfig
- func (c *ContainerRequest) GetBuildArgs() map[string]*string
- func (c *ContainerRequest) GetContext() (io.Reader, error)
- func (c *ContainerRequest) GetDockerfile() string
- func (c *ContainerRequest) ShouldBuildImage() bool
- func (c *ContainerRequest) ShouldPrintBuildLog() bool
- func (c *ContainerRequest) Validate() error
- type DefaultNetwork
- type DeprecatedContainer
- type DockerBindMountSource
- type DockerCompose
- type DockerContainer
- func (c *DockerContainer) ContainerIP(ctx context.Context) (string, error)
- func (c *DockerContainer) ContainerIPs(ctx context.Context) ([]string, error)
- func (c *DockerContainer) CopyDirToContainer(ctx context.Context, hostDirPath string, containerParentPath string, ...) error
- func (c *DockerContainer) CopyFileFromContainer(ctx context.Context, filePath string) (io.ReadCloser, error)
- func (c *DockerContainer) CopyFileToContainer(ctx context.Context, hostFilePath string, containerFilePath string, ...) error
- func (c *DockerContainer) CopyToContainer(ctx context.Context, fileContent []byte, containerFilePath string, ...) error
- func (c *DockerContainer) Endpoint(ctx context.Context, proto string) (string, error)
- func (c *DockerContainer) Exec(ctx context.Context, cmd []string, options ...tcexec.ProcessOption) (int, io.Reader, error)
- func (c *DockerContainer) FollowOutput(consumer LogConsumer)
- func (c *DockerContainer) GetContainerID() string
- func (c *DockerContainer) Host(ctx context.Context) (string, error)
- func (c *DockerContainer) IsRunning() bool
- 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) StartLogProducer(ctx context.Context) error
- func (c *DockerContainer) State(ctx context.Context) (*types.ContainerState, error)
- func (c *DockerContainer) Stop(ctx context.Context, timeout *time.Duration) error
- func (c *DockerContainer) StopLogProducer() error
- func (c *DockerContainer) Terminate(ctx context.Context) error
- type DockerNetwork
- type DockerProvider
- func (p *DockerProvider) BuildImage(ctx context.Context, img ImageBuildInfo) (string, error)
- func (p *DockerProvider) Config() TestContainersConfig
- 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) GetGatewayIP(ctx context.Context) (string, error)
- func (p *DockerProvider) GetNetwork(ctx context.Context, req NetworkRequest) (types.NetworkResource, error)
- func (p *DockerProvider) Health(ctx context.Context) (err error)
- func (p *DockerProvider) ReuseOrCreateContainer(ctx context.Context, req ContainerRequest) (Container, error)
- func (p *DockerProvider) RunContainer(ctx context.Context, req ContainerRequest) (Container, error)
- type DockerProviderOption
- type DockerProviderOptionFunc
- type DockerProviderOptions
- type DockerTmpfsMountSource
- type DockerVolumeMountSource
- type ExecError
- type FileFromContainer
- type FromDockerfile
- type GenericBindMountSource
- type GenericContainerRequest
- type GenericNetworkRequest
- type GenericProvider
- type GenericProviderOption
- type GenericProviderOptionFunc
- type GenericProviderOptions
- type GenericTmpfsMountSource
- type GenericVolumeMountSource
- type IgnoreOrphans
- type ImageBuildInfo
- type LocalDockerCompose
- func (dc *LocalDockerCompose) Down() ExecError
- func (dc *LocalDockerCompose) Invoke() ExecError
- func (dc *LocalDockerCompose) WaitForService(service string, strategy wait.Strategy) DockerCompose
- func (dc *LocalDockerCompose) WithCommand(cmd []string) DockerCompose
- func (dc *LocalDockerCompose) WithEnv(env map[string]string) DockerCompose
- func (dc *LocalDockerCompose) WithExposedService(service string, port int, strategy wait.Strategy) DockerCompose
- type LocalDockerComposeOption
- type LocalDockerComposeOptions
- type LocalDockerComposeOptionsFunc
- type Log
- type LogConsumer
- type LoggerOption
- type Logging
- type MountType
- type Network
- type NetworkProvider
- type NetworkRequest
- type ParallelContainerRequest
- type ParallelContainersError
- type ParallelContainersOptions
- type ParallelContainersRequestError
- type ProviderType
- type Reaper
- type ReaperProvider
- type RemoveImages
- type RemoveOrphans
- type StackDownOption
- type StackIdentifier
- type StackUpOption
- type TestContainersConfig
- type TmpfsMounter
- type VolumeMounter
- type Wait
Examples ¶
Constants ¶
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 ErrNoStackConfigured = errors.New("no stack files configured")
var (
ErrReuseEmptyName = errors.New("with reuse option a container name mustn't be empty")
)
Functions ¶
func NewDockerCompose ¶ added in v0.16.0
func NewDockerComposeWith ¶ added in v0.16.0
func NewDockerComposeWith(opts ...ComposeStackOption) (*dockerCompose, error)
func SkipIfProviderIsNotHealthy ¶ added in v0.7.0
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 ¶
SkipIfProviderIsNotHealthy(&testing.T{})
Types ¶
type BindMounter ¶ added in v0.13.0
type BindMounter interface {
GetBindOptions() *mount.BindOptions
}
BindMounter can optionally be implemented by mount sources to support advanced scenarios based on mount.BindOptions
type ComposeStack ¶ added in v0.16.0
type ComposeStack interface {
Up(ctx context.Context, opts ...StackUpOption) error
Down(ctx context.Context, opts ...StackDownOption) error
Services() []string
WaitForService(s string, strategy wait.Strategy) ComposeStack
WithEnv(m map[string]string) ComposeStack
WithOsEnv() ComposeStack
ServiceContainer(ctx context.Context, svcName string) (*DockerContainer, error)
}
ComposeStack defines operations that can be applied to a parsed compose stack
type ComposeStackFiles ¶ added in v0.16.0
type ComposeStackFiles []string
type ComposeStackOption ¶ added in v0.16.0
type ComposeStackOption interface {
// contains filtered or unexported methods
}
func WithStackFiles ¶ added in v0.16.0
func WithStackFiles(filePaths ...string) ComposeStackOption
type ComposeVersion ¶ added in v0.14.0
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, options ...tcexec.ProcessOption) (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 ¶ added in v0.14.0
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 ¶ added in v0.14.0
type ContainerMount ¶ added in v0.13.0
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 ¶ added in v0.13.0
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 ¶ added in v0.13.0
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 ¶ added in v0.13.0
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 ¶ added in v0.13.0
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 ¶ added in v0.13.0
func (t ContainerMountTarget) Target() string
type ContainerMounts ¶ added in v0.13.0
type ContainerMounts []ContainerMount
ContainerMounts represents a collection of mounts for a container
func Mounts ¶ added in v0.13.0
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) GetAuthConfigs ¶ added in v0.16.0
func (c *ContainerRequest) GetAuthConfigs() map[string]types.AuthConfig
GetAuthConfigs returns the auth configs to be able to pull from an authenticated docker registry
func (*ContainerRequest) GetBuildArgs ¶ added in v0.11.0
func (c *ContainerRequest) GetBuildArgs() map[string]*string
GetBuildArgs returns the env args to be used when creating from Dockerfile
func (*ContainerRequest) GetContext ¶ added in v0.0.8
func (c *ContainerRequest) GetContext() (io.Reader, error)
GetContext retrieve the build context for the request
func (*ContainerRequest) GetDockerfile ¶ added in v0.0.8
func (c *ContainerRequest) GetDockerfile() string
GetDockerfile returns the Dockerfile from the ContainerRequest, defaults to "Dockerfile"
func (*ContainerRequest) ShouldBuildImage ¶ added in v0.0.9
func (c *ContainerRequest) ShouldBuildImage() bool
func (*ContainerRequest) ShouldPrintBuildLog ¶ added in v0.11.0
func (c *ContainerRequest) ShouldPrintBuildLog() bool
func (*ContainerRequest) Validate ¶ added in v0.0.8
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 ¶ added in v0.14.0
type DefaultNetwork string
func (DefaultNetwork) ApplyDockerTo ¶ added in v0.14.0
func (n DefaultNetwork) ApplyDockerTo(opts *DockerProviderOptions)
func (DefaultNetwork) ApplyGenericTo ¶ added in v0.14.0
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 ¶ added in v0.13.0
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 ¶ added in v0.13.0
func (s DockerBindMountSource) GetBindOptions() *mount.BindOptions
func (DockerBindMountSource) Source ¶ added in v0.13.0
func (s DockerBindMountSource) Source() string
func (DockerBindMountSource) Type ¶ added in v0.13.0
func (DockerBindMountSource) Type() MountType
type DockerCompose ¶ added in v0.5.1
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 Deprecated: DockerCompose is the old shell escape based API use ComposeStack instead
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 ¶ added in v0.5.0
func (c *DockerContainer) ContainerIP(ctx context.Context) (string, error)
ContainerIP gets the IP address of the primary network within the container.
func (*DockerContainer) ContainerIPs ¶ added in v0.15.0
func (c *DockerContainer) ContainerIPs(ctx context.Context) ([]string, error)
ContainerIPs gets the IP addresses of all the networks within the container.
func (*DockerContainer) CopyDirToContainer ¶ added in v0.14.0
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 ¶ added in v0.12.0
func (c *DockerContainer) CopyFileFromContainer(ctx context.Context, filePath string) (io.ReadCloser, error)
func (*DockerContainer) CopyFileToContainer ¶ added in v0.8.0
func (*DockerContainer) CopyToContainer ¶ added in v0.13.0
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 ¶
Endpoint gets proto://host:port string for the first exposed port Will returns just host:port if proto is ""
func (*DockerContainer) Exec ¶ added in v0.0.9
func (c *DockerContainer) Exec(ctx context.Context, cmd []string, options ...tcexec.ProcessOption) (int, io.Reader, error)
func (*DockerContainer) FollowOutput ¶ added in v0.3.0
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 ¶ added in v0.14.0
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 ¶
MappedPort gets externally mapped port for a container port
func (*DockerContainer) Name ¶ added in v0.0.5
func (c *DockerContainer) Name(ctx context.Context) (string, error)
Name gets the name of the container.
func (*DockerContainer) NetworkAliases ¶ added in v0.0.7
NetworkAliases gets the aliases of the container for the networks it is attached to.
func (*DockerContainer) Networks ¶ added in v0.0.7
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) 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 ¶ added in v0.3.0
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 ¶ added in v0.12.0
func (c *DockerContainer) State(ctx context.Context) (*types.ContainerState, error)
State returns container's running state
func (*DockerContainer) Stop ¶ added in v0.13.0
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 ¶ added in v0.3.0
func (c *DockerContainer) StopLogProducer() error
StopLogProducer will stop the concurrent process that is reading logs and sending them to each added LogConsumer
type DockerNetwork ¶ added in v0.0.7
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
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 ¶ added in v0.0.8
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 ¶ added in v0.14.0
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 ¶
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 func() {
if err := nginxC.Terminate(ctx); err != nil {
log.Fatalf("failed to terminate container: %s", err)
}
}()
func (*DockerProvider) CreateNetwork ¶ added in v0.0.7
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 ¶ added in v0.8.0
func (p *DockerProvider) GetGatewayIP(ctx context.Context) (string, error)
func (*DockerProvider) GetNetwork ¶ added in v0.0.7
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 ¶ added in v0.7.0
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 ¶ added in v0.14.0
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 ¶ added in v0.13.0
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 ¶ added in v0.13.0
func Generic2DockerOptions(opts ...GenericProviderOption) []DockerProviderOption
func WithDefaultBridgeNetwork ¶ added in v0.14.0
func WithDefaultBridgeNetwork(bridgeNetworkName string) DockerProviderOption
type DockerProviderOptionFunc ¶ added in v0.13.0
type DockerProviderOptionFunc func(opts *DockerProviderOptions)
DockerProviderOptionFunc is a shorthand to implement the DockerProviderOption interface
func (DockerProviderOptionFunc) ApplyDockerTo ¶ added in v0.13.0
func (f DockerProviderOptionFunc) ApplyDockerTo(opts *DockerProviderOptions)
type DockerProviderOptions ¶ added in v0.13.0
type DockerProviderOptions struct {
*GenericProviderOptions
// contains filtered or unexported fields
}
DockerProviderOptions defines options applicable to DockerProvider
type DockerTmpfsMountSource ¶ added in v0.13.0
type DockerTmpfsMountSource struct {
GenericTmpfsMountSource
*mount.TmpfsOptions
}
func (DockerTmpfsMountSource) GetTmpfsOptions ¶ added in v0.13.0
func (s DockerTmpfsMountSource) GetTmpfsOptions() *mount.TmpfsOptions
type DockerVolumeMountSource ¶ added in v0.13.0
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 ¶ added in v0.13.0
func (s DockerVolumeMountSource) GetVolumeOptions() *mount.VolumeOptions
func (DockerVolumeMountSource) Source ¶ added in v0.13.0
func (s DockerVolumeMountSource) Source() string
func (DockerVolumeMountSource) Type ¶ added in v0.13.0
func (DockerVolumeMountSource) Type() MountType
type ExecError ¶ added in v0.5.1
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 ¶ added in v0.12.0
type FileFromContainer struct {
// contains filtered or unexported fields
}
func (*FileFromContainer) Close ¶ added in v0.12.0
func (fc *FileFromContainer) Close() error
type FromDockerfile ¶ added in v0.0.8
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
AuthConfigs map[string]types.AuthConfig // enable auth configs to be able to pull from an authenticated docker registry
}
FromDockerfile represents the parameters needed to build an image from a Dockerfile rather than using a pre-built one
type GenericBindMountSource ¶ added in v0.13.0
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 ¶ added in v0.13.0
func (s GenericBindMountSource) Source() string
func (GenericBindMountSource) Type ¶ added in v0.13.0
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 ¶ added in v0.5.0
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 ¶ added in v0.0.7
type GenericProvider interface {
ContainerProvider
NetworkProvider
}
GenericProvider represents an abstraction for container and network providers
type GenericProviderOption ¶ added in v0.13.0
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 ¶ added in v0.13.0
type GenericProviderOptionFunc func(opts *GenericProviderOptions)
GenericProviderOptionFunc is a shorthand to implement the GenericProviderOption interface
func (GenericProviderOptionFunc) ApplyGenericTo ¶ added in v0.13.0
func (f GenericProviderOptionFunc) ApplyGenericTo(opts *GenericProviderOptions)
type GenericProviderOptions ¶ added in v0.13.0
GenericProviderOptions defines options applicable to all providers
type GenericTmpfsMountSource ¶ added in v0.13.0
type GenericTmpfsMountSource struct {
}
GenericTmpfsMountSource implements ContainerMountSource and represents a TmpFS mount Optionally mount.TmpfsOptions might be added for advanced scenarios
func (GenericTmpfsMountSource) Source ¶ added in v0.13.0
func (s GenericTmpfsMountSource) Source() string
func (GenericTmpfsMountSource) Type ¶ added in v0.13.0
func (GenericTmpfsMountSource) Type() MountType
type GenericVolumeMountSource ¶ added in v0.13.0
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 ¶ added in v0.13.0
func (s GenericVolumeMountSource) Source() string
func (GenericVolumeMountSource) Type ¶ added in v0.13.0
func (GenericVolumeMountSource) Type() MountType
type IgnoreOrphans ¶ added in v0.16.0
type IgnoreOrphans bool
IgnoreOrphans - Ignore legacy containers for services that are not defined in the project
type ImageBuildInfo ¶ added in v0.0.8
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
GetAuthConfigs() map[string]types.AuthConfig // return the auth configs to be able to pull from an authenticated docker registry
}
ImageBuildInfo defines what is needed to build an image
type LocalDockerCompose ¶ added in v0.5.1
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 ¶
_ = 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
deprecated
added in
v0.5.1
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.
Deprecated: NewLocalDockerCompose returns a DockerCompose compatible instance which is superseded by ComposeStack use NewDockerCompose instead to get a ComposeStack compatible instance
Example ¶
path := "/path/to/docker-compose.yml"
_ = NewLocalDockerCompose([]string{path}, "my_project")
func (*LocalDockerCompose) Down ¶ added in v0.5.1
func (dc *LocalDockerCompose) Down() ExecError
Down executes docker-compose down
Example ¶
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 ¶ added in v0.5.1
func (dc *LocalDockerCompose) Invoke() ExecError
Invoke invokes the docker compose
Example ¶
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 ¶ added in v0.12.0
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 ¶ added in v0.5.1
func (dc *LocalDockerCompose) WithCommand(cmd []string) DockerCompose
WithCommand assigns the command
Example ¶
path := "/path/to/docker-compose.yml"
compose := NewLocalDockerCompose([]string{path}, "my_project")
compose.WithCommand([]string{"up", "-d"})
func (*LocalDockerCompose) WithEnv ¶ added in v0.5.1
func (dc *LocalDockerCompose) WithEnv(env map[string]string) DockerCompose
WithEnv assigns the environment
Example ¶
path := "/path/to/docker-compose.yml"
compose := NewLocalDockerCompose([]string{path}, "my_project")
compose.WithEnv(map[string]string{
"FOO": "foo",
"BAR": "bar",
})
func (*LocalDockerCompose) WithExposedService ¶ added in v0.11.0
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 ¶ added in v0.13.0
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 ¶ added in v0.13.0
type LocalDockerComposeOptions struct {
Logger Logging
}
LocalDockerComposeOptions defines options applicable to LocalDockerCompose
type LocalDockerComposeOptionsFunc ¶ added in v0.13.0
type LocalDockerComposeOptionsFunc func(opts *LocalDockerComposeOptions)
LocalDockerComposeOptionsFunc is a shorthand to implement the LocalDockerComposeOption interface
func (LocalDockerComposeOptionsFunc) ApplyToLocalCompose ¶ added in v0.13.0
func (f LocalDockerComposeOptionsFunc) ApplyToLocalCompose(opts *LocalDockerComposeOptions)
type Log ¶ added in v0.3.0
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 ¶ added in v0.3.0
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 ¶ added in v0.13.0
type LoggerOption struct {
// contains filtered or unexported fields
}
func WithLogger ¶ added in v0.13.0
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 ¶ added in v0.13.0
func (o LoggerOption) ApplyDockerTo(opts *DockerProviderOptions)
func (LoggerOption) ApplyGenericTo ¶ added in v0.13.0
func (o LoggerOption) ApplyGenericTo(opts *GenericProviderOptions)
func (LoggerOption) ApplyToLocalCompose ¶ added in v0.13.0
func (o LoggerOption) ApplyToLocalCompose(opts *LocalDockerComposeOptions)
type Logging ¶ added in v0.13.0
type Logging interface {
Printf(format string, v ...interface{})
}
Logging defines the Logger interface
func TestLogger ¶ added in v0.13.0
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 Network ¶ added in v0.0.7
Network allows getting info about a single network instance
func GenericNetwork ¶ added in v0.5.0
func GenericNetwork(ctx context.Context, req GenericNetworkRequest) (Network, error)
GenericNetwork creates a generic network with parameters
type NetworkProvider ¶ added in v0.0.7
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 ¶ added in v0.0.7
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 ¶ added in v0.14.0
type ParallelContainerRequest []GenericContainerRequest
type ParallelContainersError ¶ added in v0.14.0
type ParallelContainersError struct {
Errors []ParallelContainersRequestError
}
func (ParallelContainersError) Error ¶ added in v0.14.0
func (gpe ParallelContainersError) Error() string
type ParallelContainersOptions ¶ added in v0.14.0
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 ¶ added in v0.14.0
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
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 RemoveImages ¶ added in v0.16.0
type RemoveImages uint8
RemoveImages used by services
const ( // RemoveImagesAll - remove all images used by the stack RemoveImagesAll RemoveImages = iota // RemoveImagesLocal - remove only images that don't have a tag RemoveImagesLocal )
type RemoveOrphans ¶ added in v0.16.0
type RemoveOrphans bool
RemoveOrphans will cleanup containers that are not declared on the compose model but own the same labels
type StackDownOption ¶ added in v0.16.0
type StackDownOption interface {
// contains filtered or unexported methods
}
type StackIdentifier ¶ added in v0.16.0
type StackIdentifier string
func (StackIdentifier) String ¶ added in v0.16.0
func (f StackIdentifier) String() string
type StackUpOption ¶ added in v0.16.0
type StackUpOption interface {
// contains filtered or unexported methods
}
func RunServices ¶ added in v0.16.0
func RunServices(serviceNames ...string) StackUpOption
RunServices is comparable to 'docker-compose run' as it only creates a subset of containers instead of all services defined by the project
type TestContainersConfig ¶ added in v0.12.0
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 ¶ added in v0.14.0
func NewDockerClient() (cli *client.Client, host string, tcConfig TestContainersConfig, err error)
type TmpfsMounter ¶ added in v0.13.0
type TmpfsMounter interface {
GetTmpfsOptions() *mount.TmpfsOptions
}
TmpfsMounter can optionally be implemented by mount sources to support advanced scenarios based on mount.TmpfsOptions
type VolumeMounter ¶ added in v0.13.0
type VolumeMounter interface {
GetVolumeOptions() *mount.VolumeOptions
}
VolumeMounter can optionally be implemented by mount sources to support advanced scenarios based on mount.VolumeOptions
Source Files
¶
Directories
¶
| Path | Synopsis |
|---|---|
|
examples
|
|
|
bigtable
module
|
|
|
cockroachdb
module
|
|
|
consul
module
|
|
|
datastore
module
|
|
|
firestore
module
|
|
|
mongodb
module
|
|
|
mysql
module
|
|
|
nats
module
|
|
|
nginx
module
|
|
|
postgres
module
|
|
|
pubsub
module
|
|
|
pulsar
module
|
|
|
redis
module
|
|
|
spanner
module
|
|
|
toxiproxy
module
|
|
|
modulegen
module
|
|
|
modules
|
|
|
aerospike
module
|
|
|
arangodb
module
|
|
|
artemis
module
|
|
|
azure
module
|
|
|
azurite
module
|
|
|
cassandra
module
|
|
|
chroma
module
|
|
|
clickhouse
module
|
|
|
cockroachdb
module
|
|
|
compose
module
|
|
|
consul
module
|
|
|
couchbase
module
|
|
|
databend
module
|
|
|
dind
module
|
|
|
dockermcpgateway
module
|
|
|
dockermodelrunner
module
|
|
|
dolt
module
|
|
|
dynamodb
module
|
|
|
elasticsearch
module
|
|
|
etcd
module
|
|
|
gcloud
module
|
|
|
grafana-lgtm
module
|
|
|
inbucket
module
|
|
|
influxdb
module
|
|
|
k3s
module
|
|
|
k6
module
|
|
|
kafka
module
|
|
|
localstack
module
|
|
|
mariadb
module
|
|
|
meilisearch
module
|
|
|
memcached
module
|
|
|
milvus
module
|
|
|
minio
module
|
|
|
mockserver
module
|
|
|
mongodb
module
|
|
|
mssql
module
|
|
|
mysql
module
|
|
|
nats
module
|
|
|
nebulagraph
module
|
|
|
neo4j
module
|
|
|
ollama
module
|
|
|
openfga
module
|
|
|
openldap
module
|
|
|
opensearch
module
|
|
|
pinecone
module
|
|
|
postgres
module
|
|
|
pulsar
module
|
|
|
qdrant
module
|
|
|
rabbitmq
module
|
|
|
redis
module
|
|
|
redpanda
module
|
|
|
registry
module
|
|
|
scylladb
module
|
|
|
socat
module
|
|
|
solace
module
|
|
|
surrealdb
module
|
|
|
toxiproxy
module
|
|
|
valkey
module
|
|
|
vault
module
|
|
|
vearch
module
|
|
|
weaviate
module
|
|
|
yugabytedb
module
|
|
|
usage-metrics
module
|
|