# README
Testcontainers
Testcontainers for Go is a Go package that makes it simple to create and clean up container-based dependencies for automated integration/smoke tests. The clean, easy-to-use API enables developers to programmatically define containers that should be run as part of a test and clean up those resources when the test is done.
You can find more information about Testcontainers for Go at golang.testcontainers.org, which is rendered from the ./docs directory.
Using Testcontainers for Go
Please visit the quickstart guide to understand how to add the dependency to your Go project.
# Functions
AddGenericLabels adds the generic labels to target.
Deprecated: use Files or HostConfigModifier in the ContainerRequest, or copy files container APIs to make containers portable across Docker environments BindMount returns a new ContainerMount with a GenericBindMountSource as source This is a convenience method to cover typical use cases.
CleanupContainer is a helper function that schedules the container to be stopped / terminated when the test ends.
CleanupNetwork is a helper function that schedules the network to be removed when the test ends.
CustomizeRequest returns a function that can be used to merge the passed container request with the one that is used by the container.
DockerImageAuth returns the auth config for the given Docker image, extracting first its Docker registry.
Deprecated: use MustExtractDockerHost instead.
No description provided by the author
GenericContainer creates a generic container with parameters.
GenericLabels returns a map of labels that can be used to identify resources created by this library.
Deprecated: use network.New instead GenericNetwork creates a generic network with parameters.
Deprecated: this function will be removed in a future release LogDockerServerInfo logs the docker server info using the provided logger and Docker client.
Mounts returns a ContainerMounts to support a more fluent API.
MustExtractDockerSocket Extracts the docker socket from the different alternatives, removing the socket schema.
NewCustomHubSubstitutor creates a new CustomHubSubstitutor.
Deprecated: Use NewDockerClientWithOpts instead.
No description provided by the author
NewDockerProvider creates a Docker provider with the EnvClient.
No description provided by the author
NewReaper creates a Reaper with a sessionID to identify containers and a provider to use Deprecated: it's not possible to create a reaper any more.
NewTerminateOptions returns a fully initialised TerminateOptions.
ParallelContainers creates a generic containers with parameters and run it in parallel mode.
ReadConfig reads from testcontainers properties file, storing the result in a singleton instance of the TestcontainersConfig struct.
RemoveVolumes returns a TerminateOption that sets additional volumes to remove.
RequireContainerExec is a helper function that executes a command in a container It insures that there is no error during the execution Finally returns the output of its execution.
SessionID returns a unique session ID for the current test session.
SkipIfDockerDesktop is a utility function capable of skipping tests if tests are run using Docker Desktop.
SkipIfProviderIsNotHealthy is a utility function capable of skipping tests if the provider is not healthy, or running at all.
StopContext returns a TerminateOption that sets the context.
StopTimeout returns a TerminateOption that sets the timeout.
TerminateContainer calls [Container.Terminate] on the container if it is not nil.
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.
VolumeMount returns a new ContainerMount with a GenericVolumeMountSource as source This is a convenience method to cover typical use cases.
WithAfterReadyCommand will execute the command representation of each Executable into the container.
WithConfigModifier allows to override the default container config.
No description provided by the author
WithEndpointSettingsModifier allows to override the default endpoint settings.
WithEnv sets the environment variables for a container.
WithHostConfigModifier allows to override the default host config.
WithHostPortAccess allows to expose the host ports to the container.
Deprecated: the modules API forces passing the image as part of the signature of the Run function.
Deprecated: it will be removed in the next major release WithImageName sets the reaper image name.
WithImageSubstitutors sets the image substitutors for a container.
WithLogConsumers sets the log consumers for a container.
WithLogger returns a generic option that sets the logger to be used.
WithLogProductionTimeout is a functional option that sets the timeout for the log production.
Deprecated: Testcontainers will detect registry credentials automatically, and it will be removed in the next major release WithRegistryCredentials sets the reaper registry credentials.
WithStartupCommand will execute the command representation of each Executable into the container.
WithWaitStrategy sets the wait strategy for a container, using 60 seconds as deadline.
WithWaitStrategyAndDeadline sets the wait strategy for a container, including deadline.
# Constants
Bridge network name (as well as driver).
HostInternal is the internal hostname used to reach the host from the container, using the SSHD container as a bridge.
Deprecated: Use MountTypeVolume instead.
No description provided by the author
No description provided by the author
No description provided by the author
No description provided by the author
default will auto-detect provider from DOCKER_HOST environment variable.
possible provider types.
possible provider types.
Default network name when bridge is not available.
StderrLog is the log type for STDERR.
StdoutLog is the log type for STDOUT.
Deprecated: it has been replaced by the internal core.LabelLang.
Deprecated: it has been replaced by the internal core.LabelReaper.
Deprecated: it has been replaced by the internal core.LabelSessionID.
# Variables
DefaultLoggingHook is a hook that will log the container lifecycle events.
No description provided by the author
No description provided by the author
No description provided by the author
Logger is the default log instance.
Deprecated: it has been replaced by an internal value.
# Structs
No description provided by the author
ContainerLifecycleHooks is a struct that contains all the hooks that can be used to modify the container lifecycle.
ContainerMount models a mount into a container.
ContainerRequest represents the parameters used to get a running container.
CustomHubSubstitutor represents a way to substitute the hub of an image with a custom one, using provided value with respect to the HubImageNamePrefix configuration value.
Deprecated: use Files or HostConfigModifier in the ContainerRequest, or copy files container APIs to make containers portable across Docker environments.
DockerClient is a wrapper around the docker client that is used by testcontainers-go.
DockerContainer represents a container started using Docker.
DockerNetwork represents a network started using Docker.
DockerProvider implements the ContainerProvider interface.
No description provided by the author
No description provided by the author
No description provided by the author
ExecOptions is a struct that provides a default implementation for the Options method of the Executable interface.
No description provided by the author
FromDockerfile represents the parameters needed to build an image from a Dockerfile rather than using a pre-built one.
Deprecated: use Files or HostConfigModifier in the ContainerRequest, or copy files container APIs to make containers portable across Docker environments GenericBindMountSource implements ContainerMountSource and represents a bind mount Optionally mount.BindOptions might be added for advanced scenarios.
GenericContainerRequest represents parameters to a generic container.
Deprecated: will be removed in the future.
No description provided by the author
GenericTmpfsMountSource implements ContainerMountSource and represents a TmpFS mount Optionally mount.TmpfsOptions might be added for advanced scenarios.
GenericVolumeMountSource implements ContainerMountSource and represents a volume mount.
ImageInfo represents a summary information of an image.
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.
LogConsumerConfig is a configuration object for the producer/consumer pattern.
LoggerOption is a generic option that sets the logger to be used.
Deprecated: will be removed in the future NetworkRequest represents the parameters used to get a network.
No description provided by the author
ParallelContainersOptions represents additional options for parallel running.
ParallelContainersRequestError represents error from parallel request.
RawCommand is a type that implements Executable and represents a command to be sent to a container.
Reaper is used to start a sidecar container that cleans up resources.
StdoutLogConsumer is a LogConsumer that prints the log to stdout.
TerminateOptions is a type that holds the options for terminating a container.
TestcontainersConfig represents the configuration for Testcontainers.
# Interfaces
Deprecated: use Files or HostConfigModifier in the ContainerRequest, or copy files container APIs to make containers portable across Docker environments BindMounter can optionally be implemented by mount sources to support advanced scenarios based on mount.BindOptions.
Container allows getting info about and controlling a single container instance.
ContainerCustomizer is an interface that can be used to configure the Testcontainers container request.
ContainerMountSource is the base for all mount sources.
ContainerProvider allows the creation of containers on an arbitrary system.
DeprecatedContainer shows methods that were supported before, but are now deprecated Deprecated: Use Container.
No description provided by the author
Executable represents an executable command to be sent to a container, including options, as part of the different lifecycle hooks.
GenericProvider represents an abstraction for container and network providers.
No description provided by the author
ImageBuildInfo defines what is needed to build an image.
ImageProvider allows manipulating images.
ImageSubstitutor represents a way to substitute container image names.
LogConsumer represents any object that can handle a Log, it is up to the LogConsumer instance what to do with the log.
Logging defines the Logger interface.
Deprecated: will be removed in the future Network allows getting info about a single network instance.
NetworkProvider allows the creation of networks on an arbitrary system.
ReaperProvider represents a provider for the reaper to run itself with The ContainerProvider interface should usually satisfy this as well, so it is pluggable.
TmpfsMounter can optionally be implemented by mount sources to support advanced scenarios based on mount.TmpfsOptions.
VolumeMounter can optionally be implemented by mount sources to support advanced scenarios based on mount.VolumeOptions.
# Type aliases
ContainerHook is a hook that will be called after a container is created It can be used to modify the state of the container after it is created, using the different lifecycle hooks that are available: - Created - Starting - Started - Readied - Stopping - Stopped - Terminating - Terminated For that, it will receive a Container, modify it and return an error if needed.
No description provided by the author
ContainerMountTarget represents the target path within a container where the mount will be available Note that mount targets must be unique.
Deprecated: it will be removed in the next major release functional option for setting the reaper image.
ContainerRequestHook is a hook that will be called before a container is created.
CustomizeRequestOption is a type that can be used to configure the Testcontainers container request.
Deprecated: will be removed in the future.
No description provided by the author
No description provided by the author
No description provided by the author
No description provided by the author
No description provided by the author
No description provided by the author
TerminateOption is a type that represents an option for terminating a container.