Documentation
¶
Index ¶
- Constants
- func SkipIfProviderIsNotHealthy(t *testing.T)
- type Container
- type ContainerProvider
- type ContainerRequest
- type DeprecatedContainer
- type DockerCompose
- type DockerContainer
- func (c *DockerContainer) ContainerIP(ctx context.Context) (string, error)
- func (c *DockerContainer) Endpoint(ctx context.Context, proto string) (string, error)
- func (c *DockerContainer) Exec(ctx context.Context, cmd []string) (int, error)
- func (c *DockerContainer) FollowOutput(consumer LogConsumer)
- 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) StartLogProducer(ctx context.Context) 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) 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) Health(ctx context.Context) (err error)
- func (p *DockerProvider) RunContainer(ctx context.Context, req ContainerRequest) (Container, error)
- type ExecError
- type FromDockerfile
- type GenericContainerRequest
- type GenericNetworkRequest
- type GenericProvider
- type ImageBuildInfo
- type LocalDockerCompose
- type Log
- type LogConsumer
- type Network
- type NetworkProvider
- type NetworkRequest
- type ProviderType
- type Reaper
- type ReaperProvider
Examples ¶
Constants ¶
const ( TestcontainerLabel = "org.testcontainers.golang" TestcontainerLabelSessionID = TestcontainerLabel + ".sessionId" TestcontainerLabelIsReaper = TestcontainerLabel + ".reaper" ReaperDefaultImage = "quay.io/testcontainers/ryuk:0.2.3" )
const StderrLog = "STDERR"
StderrLog is the log type for STDERR
const StdoutLog = "STDOUT"
StdoutLog is the log type for STDOUT
Variables ¶
This section is empty.
Functions ¶
func SkipIfProviderIsNotHealthy ¶
SkipIfProviderIsNotHealthy is an utility function capable of skipping tests if the provider is not healthy, or runnig 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 depends on testcontainers won't run if the provider is provisioned correctly.
Example ¶
SkipIfProviderIsNotHealthy(&testing.T{})
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
FollowOutput(LogConsumer)
StartLogProducer(context.Context) error
StopLogProducer() error
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
Exec(ctx context.Context, cmd []string) (int, error)
ContainerIP(context.Context) (string, error) // get container ip
}
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
Health(context.Context) error
}
ContainerProvider allows the creation of containers on an arbitrary system
type ContainerRequest ¶
type ContainerRequest struct {
FromDockerfile
Image string
Env map[string]string
ExposedPorts []string // allow specifying protocol info
Cmd []string
Labels map[string]string
BindMounts map[string]string
VolumeMounts map[string]string
Tmpfs 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
ReaperImage string // alternative reaper image
AutoRemove bool // if set to true, the container will be removed from the host when stopped
NetworkMode container.NetworkMode
AlwaysPullImage bool // Always pull image
}
ContainerRequest represents the parameters used to get a running container
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) Validate ¶
func (c *ContainerRequest) Validate() error
Validate ensures that the ContainerRequest does not have invalid paramters configured to it ex. make sure you are not specifying both an image as well as a context
type DeprecatedContainer ¶
type DeprecatedContainer interface {
GetHostEndpoint(ctx context.Context, port string) (string, string, error)
GetIPAddress(ctx context.Context) (string, error)
LivenessCheckPorts(ctx context.Context) (nat.PortSet, error)
Terminate(ctx context.Context) error
}
DeprecatedContainer shows methods that were supported before, but are now deprecated Deprecated: Use Container
type DockerCompose ¶
type DockerCompose interface {
Down() ExecError
Invoke() ExecError
WithCommand([]string) DockerCompose
WithEnv(map[string]string) DockerCompose
}
DockerCompose defines the contract for running Docker Compose
type DockerContainer ¶
type DockerContainer struct {
// Container ID from Docker
ID string
WaitingFor wait.Strategy
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) Endpoint ¶
Endpoint gets proto://host:port string for the first exposed port Will returns just host:port if proto is ""
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) 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 ¶
func (c *DockerContainer) Name(ctx context.Context) (string, error)
Name gets the name of the container.
func (*DockerContainer) NetworkAliases ¶
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) 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) StopLogProducer ¶
func (c *DockerContainer) StopLogProducer() error
StopLogProducer will stop the concurrent process that is reading logs and sending them to each added LogConsumer
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
type DockerProvider ¶
type DockerProvider struct {
// contains filtered or unexported fields
}
DockerProvider implements the ContainerProvider interface
func NewDockerProvider ¶
func NewDockerProvider() (*DockerProvider, error)
NewDockerProvider creates a Docker provider with the EnvClient
func (*DockerProvider) BuildImage ¶
func (p *DockerProvider) BuildImage(ctx context.Context, img ImageBuildInfo) (string, error)
BuildImage will build and image from context and Dockerfile, then return the tag
func (*DockerProvider) CreateContainer ¶
func (p *DockerProvider) CreateContainer(ctx context.Context, req ContainerRequest) (Container, error)
CreateContainer fulfills a request for a container without starting it
Example ¶
ctx := context.Background()
req := ContainerRequest{
Image: "nginx",
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) 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)
Helth measure the healthiness of the provider. Right now we leverage the docker-client ping endpoint to see if the daemon is reachable.
func (*DockerProvider) RunContainer ¶
func (p *DockerProvider) RunContainer(ctx context.Context, req ContainerRequest) (Container, error)
RunContainer takes a RequestContainer as input and it runs a container via the docker sdk
type ExecError ¶
ExecError is super struct that holds any information about an execution error, so the client code can handle the result
type FromDockerfile ¶
type FromDockerfile struct {
Context string // the path to the context of of the docker build
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"
}
FromDockerfile represents the parameters needed to build an image from a Dockerfile rather than using a pre-built one
type GenericContainerRequest ¶
type GenericContainerRequest struct {
ContainerRequest // embedded request for provider
Started bool // whether to auto-start the container
ProviderType ProviderType // which provider to use, Docker if empty
}
GenericContainerRequest represents parameters to a generic container
type 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 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
ShouldBuildImage() bool // return true if the image needs to be built
}
ImageBuildInfo defines what is needed to build an image
type LocalDockerCompose ¶
type LocalDockerCompose struct {
Executable string
ComposeFilePaths []string
Identifier string
Cmd []string
Env map[string]string
Services map[string]interface{}
// 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 ¶
func NewLocalDockerCompose(filePaths []string, identifier string) *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 ¶
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 ¶
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 ¶
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) WithCommand ¶
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 ¶
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",
})
type Log ¶
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 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
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 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, 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)
}
ReaperProvider represents a provider for the reaper to run itself with The ContainerProvider interface should usually satisfy this as well, so it is pluggable