org.testcontainers.containers

Class GenericContainer<SELF extends GenericContainer<SELF>>

java.lang.Object

org.testcontainers.containers.FailureDetectingExternalResource

org.testcontainers.containers.GenericContainer<SELF>

All Implemented Interfaces:

java.lang.AutoCloseable, org.junit.rules.TestRule, Container<SELF>, ContainerState, LinkableContainer, WaitStrategyTarget, Startable

Direct Known Subclasses:

FixedHostPortGenericContainer, SocatContainer, VncRecordingContainer

public class GenericContainer<SELF extends GenericContainer<SELF>>
extends FailureDetectingExternalResource
implements Container<SELF>, java.lang.AutoCloseable, WaitStrategyTarget, Startable

Base class for that allows a container to be launched and controlled.

Nested Class Summary

Nested classes/interfaces inherited from interface org.testcontainers.containers.Container

Container.ExecResult

Field Summary

Fields

Modifier and Type	Field and Description
static int	CONTAINER_RUNNING_TIMEOUT_SEC
protected java.util.Set<Startable>	dependencies
protected com.github.dockerjava.api.DockerClient	dockerClient Unique instance of DockerClient for use by this container object.
static java.lang.String	INTERNAL_HOST_HOSTNAME
protected WaitStrategy	waitStrategy The approach to determine if the container is ready.

Fields inherited from interface org.testcontainers.containers.ContainerState

STATE_HEALTHY

Constructor Summary

Constructors

Constructor and Description
GenericContainer() Deprecated. use GenericContainer(DockerImageName) instead
GenericContainer(@NonNull DockerImageName dockerImageName)
GenericContainer(@NonNull java.util.concurrent.Future<java.lang.String> image)
GenericContainer(@NonNull RemoteDockerImage image)
GenericContainer(@NonNull java.lang.String dockerImageName)

Method Summary

Modifier and Type	Method and Description
void	addEnv(java.lang.String key, java.lang.String value) Add an environment variable to be passed to the container.
void	addExposedPort(java.lang.Integer port) Add an exposed port.
void	addExposedPorts(int... ports) Add exposed ports.
void	addFileSystemBind(java.lang.String hostPath, java.lang.String containerPath, BindMode mode, SelinuxContext selinuxContext) Adds a file system binding.
protected void	addFixedExposedPort(int hostPort, int containerPort) Add a TCP container port that should be bound to a fixed port on the docker host.
protected void	addFixedExposedPort(int hostPort, int containerPort, InternetProtocol protocol) Add a container port that should be bound to a fixed port on the docker host.
void	addLink(LinkableContainer otherContainer, java.lang.String alias) Deprecated. Links are deprecated (see #465). Please use Network features instead.
org.junit.runners.model.Statement	apply(org.junit.runners.model.Statement base, org.junit.runner.Description description) Deprecated.
protected boolean	canBeReused()
protected void	configure()
protected void	containerIsCreated(java.lang.String containerId)
protected void	containerIsStarted(com.github.dockerjava.api.command.InspectContainerResponse containerInfo)
protected void	containerIsStarted(com.github.dockerjava.api.command.InspectContainerResponse containerInfo, boolean reused)
protected void	containerIsStarting(com.github.dockerjava.api.command.InspectContainerResponse containerInfo)
protected void	containerIsStarting(com.github.dockerjava.api.command.InspectContainerResponse containerInfo, boolean reused)
protected void	containerIsStopped(com.github.dockerjava.api.command.InspectContainerResponse containerInfo) A hook that is executed after the container is stopped with stop().
protected void	containerIsStopping(com.github.dockerjava.api.command.InspectContainerResponse containerInfo) A hook that is executed before the container is stopped with stop().
void	copyFileFromContainer(java.lang.String containerPath, java.lang.String destinationPath) Copies a file which resides inside the container to user defined directory
protected java.nio.file.Path	createVolumeDirectory(boolean temporary) Creates a directory on the local filesystem which will be mounted as a volume for the container.
SELF	dependsOn(java.lang.Iterable<? extends Startable> startables) Delays this container's creation and start until provided Startables start first.
SELF	dependsOn(java.util.List<? extends Startable> startables)
SELF	dependsOn(Startable... startables)
protected void	doStart()
boolean	equals(java.lang.Object o)
protected void	failed(java.lang.Throwable e, org.junit.runner.Description description) Deprecated.
protected void	finished(org.junit.runner.Description description) Deprecated.
@NonNull java.util.List<com.github.dockerjava.api.model.Bind>	getBinds()
@NonNull java.lang.String[]	getCommandParts()
java.lang.String	getContainerId()
com.github.dockerjava.api.command.InspectContainerResponse	getContainerInfo()
java.lang.String	getContainerName()
java.util.Map<MountableFile,java.lang.String>	getCopyToFileContainerPathMap()
java.util.Set<java.util.function.Consumer<com.github.dockerjava.api.command.CreateContainerCmd>>	getCreateContainerCmdModifiers()
java.util.Set<Startable>	getDependencies()
com.github.dockerjava.api.DockerClient	getDockerClient() Unique instance of DockerClient for use by this container object.
@NonNull java.lang.String	getDockerImageName() Get image name.
java.util.List<java.lang.String>	getEnv()
java.util.Map<java.lang.String,java.lang.String>	getEnvMap()
java.util.List<java.lang.Integer>	getExposedPorts()
@NonNull java.util.List<java.lang.String>	getExtraHosts()
@NonNull RemoteDockerImage	getImage()
java.lang.String	getIpAddress() Deprecated. please use getContainerIpAddress() instead
@NonNull java.util.Map<java.lang.String,java.lang.String>	getLabels()
@NonNull java.util.Map<java.lang.String,LinkableContainer>	getLinkedContainers() Deprecated. Links are deprecated (see #465). Please use Network features instead.
protected java.lang.Integer	getLivenessCheckPort() Deprecated. see getLivenessCheckPorts() for replacement
java.util.Set<java.lang.Integer>	getLivenessCheckPortNumbers()
protected @NotNull @NonNull java.util.Set<java.lang.Integer>	getLivenessCheckPorts() Deprecated. use getLivenessCheckPortNumbers() instead
java.util.List<java.util.function.Consumer<OutputFrame>>	getLogConsumers()
@NonNull Network	getNetwork()
@NonNull java.util.List<java.lang.String>	getNetworkAliases()
@NonNull java.lang.String	getNetworkMode()
@NonNull java.util.List<java.lang.String>	getPortBindings()
@Nullable java.lang.Long	getShmSize() The shared memory size to use when starting the container.
int	getStartupAttempts()
StartupCheckStrategy	getStartupCheckStrategy()
java.lang.String	getTestHostIpAddress() Get the IP address that containers (e.g.
@Nullable java.util.Map<java.lang.String,java.lang.String>	getTmpFsMapping()
@NonNull java.util.List<com.github.dockerjava.api.model.VolumesFrom>	getVolumesFroms()
protected WaitStrategy	getWaitStrategy() The WaitStrategy to use to determine if the container is ready.
@Nullable java.lang.String	getWorkingDirectory()
int	hashCode()
boolean	isPrivilegedMode()
boolean	isShouldBeReused()
protected org.slf4j.Logger	logger() Provide a logger that references the docker image name.
void	setBinds(@NonNull java.util.List<com.github.dockerjava.api.model.Bind> binds)
void	setCommand(java.lang.String... commandParts) Set the command that should be run in the container.
void	setCommand(@NonNull java.lang.String command) Set the command that should be run in the container.
void	setCommandParts(@NonNull java.lang.String[] commandParts)
void	setCopyToFileContainerPathMap(java.util.Map<MountableFile,java.lang.String> copyToFileContainerPathMap)
void	setDockerImageName(@NonNull java.lang.String dockerImageName) Resolve Docker image and set it.
void	setEnv(java.util.List<java.lang.String> env)
void	setExposedPorts(java.util.List<java.lang.Integer> exposedPorts)
void	setExtraHosts(@NonNull java.util.List<java.lang.String> extraHosts)
void	setImage(java.util.concurrent.Future<java.lang.String> image)
void	setLabels(@NonNull java.util.Map<java.lang.String,java.lang.String> labels)
void	setLinkedContainers(@NonNull java.util.Map<java.lang.String,LinkableContainer> linkedContainers) Deprecated. Links are deprecated (see #465). Please use Network features instead.
void	setLogConsumers(java.util.List<java.util.function.Consumer<OutputFrame>> logConsumers)
void	setNetwork(@NonNull Network network)
void	setNetworkAliases(@NonNull java.util.List<java.lang.String> networkAliases)
void	setNetworkMode(@NonNull java.lang.String networkMode)
void	setPortBindings(@NonNull java.util.List<java.lang.String> portBindings)
void	setPrivilegedMode(boolean privilegedMode)
void	setShmSize(@Nullable java.lang.Long shmSize) The shared memory size to use when starting the container.
void	setStartupAttempts(int startupAttempts)
void	setStartupCheckStrategy(StartupCheckStrategy startupCheckStrategy)
void	setTmpFsMapping(@Nullable java.util.Map<java.lang.String,java.lang.String> tmpFsMapping)
void	setVolumesFroms(@NonNull java.util.List<com.github.dockerjava.api.model.VolumesFrom> volumesFroms)
void	setWaitStrategy(WaitStrategy waitStrategy)
void	setWorkingDirectory(@Nullable java.lang.String workingDirectory)
void	start() Starts the container using docker, pulling an image if necessary.
protected void	starting(org.junit.runner.Description description) Deprecated.
void	stop() Stops the container.
protected void	succeeded(org.junit.runner.Description description) Deprecated.
java.lang.String	toString()
SELF	waitingFor(WaitStrategy waitStrategy) Specify the WaitStrategy to use to determine if the container is ready.
protected void	waitUntilContainerStarted() Wait until the container has started.
SELF	withClasspathResourceMapping(java.lang.String resourcePath, java.lang.String containerPath, BindMode mode) Map a resource (file or directory) on the classpath to a path inside the container.
SELF	withClasspathResourceMapping(java.lang.String resourcePath, java.lang.String containerPath, BindMode mode, SelinuxContext selinuxContext) Map a resource (file or directory) on the classpath to a path inside the container.
SELF	withCommand(java.lang.String... commandParts) Set the command that should be run in the container
SELF	withCommand(java.lang.String cmd) Set the command that should be run in the container
SELF	withCopyFileToContainer(MountableFile mountableFile, java.lang.String containerPath) Set the file to be copied before starting a created container
SELF	withCreateContainerCmdModifier(java.util.function.Consumer<com.github.dockerjava.api.command.CreateContainerCmd> modifier) Allow low level modifications of CreateContainerCmd after it was pre-configured in tryStart(Instant).
SELF	withEnv(java.util.Map<java.lang.String,java.lang.String> env) Add environment variables to be passed to the container.
SELF	withEnv(java.lang.String key, java.lang.String value) Add an environment variable to be passed to the container.
SELF	withExposedPorts(java.lang.Integer... ports) Set the ports that this container listens on
SELF	withExtraHost(java.lang.String hostname, java.lang.String ipAddress) Add an extra host entry to be passed to the container
SELF	withFileSystemBind(java.lang.String hostPath, java.lang.String containerPath, BindMode mode) Adds a file system binding.
SELF	withImagePullPolicy(ImagePullPolicy imagePullPolicy) Set the image pull policy of the container
SELF	withLabel(java.lang.String key, java.lang.String value) Add a label to the container.
SELF	withLabels(java.util.Map<java.lang.String,java.lang.String> labels) Add labels to the container.
SELF	withLogConsumer(java.util.function.Consumer<OutputFrame> consumer) Attach an output consumer at container startup, enabling stdout and stderr to be followed, waited on, etc.
SELF	withMinimumRunningDuration(java.time.Duration minimumRunningDuration) Only consider a container to have successfully started if it has been running for this duration.
SELF	withNetwork(Network network) Set the network for this container, similar to the --network <name> option on the docker CLI.
SELF	withNetworkAliases(java.lang.String... aliases) Set the network aliases for this container, similar to the --network-alias <my-service> option on the docker CLI.
SELF	withNetworkMode(java.lang.String networkMode) Set the network mode for this container, similar to the --net <name> option on the docker CLI.
SELF	withPrivilegedMode(boolean mode) Set the privilegedMode mode for the container
SELF	withReuse(boolean reusable)
SELF	withSharedMemorySize(java.lang.Long bytes) Size of /dev/shm
SELF	withStartupAttempts(int attempts) Allow container startup to be attempted more than once if an error occurs.
SELF	withStartupCheckStrategy(StartupCheckStrategy strategy) Set the startup check strategy used for checking whether the container has started.
SELF	withStartupTimeout(java.time.Duration startupTimeout) Set the duration of waiting time until container treated as started.
SELF	withTmpFs(java.util.Map<java.lang.String,java.lang.String> mapping) First class support for configuring tmpfs
SELF	withVolumesFrom(Container container, BindMode mode) Adds container volumes.
SELF	withWorkingDirectory(java.lang.String workDir) Set the working directory that the container should use on startup.

Methods inherited from class java.lang.Object

clone, finalize, getClass, notify, notifyAll, wait, wait, wait

Methods inherited from interface org.testcontainers.containers.Container

addFileSystemBind, followOutput, followOutput, self, withEnv, withFileSystemBind

Methods inherited from interface org.testcontainers.containers.ContainerState

copyFileFromContainer, copyFileToContainer, copyFileToContainer, execInContainer, execInContainer, getBoundPortNumbers, getContainerIpAddress, getCurrentContainerInfo, getFirstMappedPort, getHost, getLogs, getLogs, getMappedPort, isCreated, isHealthy, isRunning

Methods inherited from interface org.testcontainers.lifecycle.Startable

close

Field Detail

CONTAINER_RUNNING_TIMEOUT_SEC

public static final int CONTAINER_RUNNING_TIMEOUT_SEC

See Also:

Constant Field Values

INTERNAL_HOST_HOSTNAME

public static final java.lang.String INTERNAL_HOST_HOSTNAME

See Also:

Constant Field Values

dependencies

protected final java.util.Set<Startable> dependencies

dockerClient

protected com.github.dockerjava.api.DockerClient dockerClient

Unique instance of DockerClient for use by this container object. We use DockerClientFactory.lazyClient() here to avoid eager client creation

waitStrategy

@NonNull
protected WaitStrategy waitStrategy

The approach to determine if the container is ready.

Constructor Detail

GenericContainer

public GenericContainer(@NonNull
                        @NonNull DockerImageName dockerImageName)

GenericContainer

public GenericContainer(@NonNull
                        @NonNull RemoteDockerImage image)

GenericContainer

@Deprecated
public GenericContainer()

Deprecated. use GenericContainer(DockerImageName) instead

GenericContainer

public GenericContainer(@NonNull
                        @NonNull java.lang.String dockerImageName)

GenericContainer

public GenericContainer(@NonNull
                        @NonNull java.util.concurrent.Future<java.lang.String> image)

Method Detail

setImage

public void setImage(java.util.concurrent.Future<java.lang.String> image)

Specified by:

setImage in interface Container<SELF extends GenericContainer<SELF>>

getExposedPorts

public java.util.List<java.lang.Integer> getExposedPorts()

Specified by:

getExposedPorts in interface ContainerState

Returns:

the exposed ports

setExposedPorts

public void setExposedPorts(java.util.List<java.lang.Integer> exposedPorts)

Specified by:

setExposedPorts in interface Container<SELF extends GenericContainer<SELF>>

dependsOn

public SELF dependsOn(Startable... startables)

See Also:

dependsOn(Iterable)

dependsOn

public SELF dependsOn(java.util.List<? extends Startable> startables)

See Also:

dependsOn(Iterable)

dependsOn

public SELF dependsOn(java.lang.Iterable<? extends Startable> startables)

Delays this container's creation and start until provided Startables start first. Note that the circular dependencies are not supported.

Parameters:

startables - a list of Startable to depend on

See Also:

Startables.deepStart(Iterable)

getContainerId

public java.lang.String getContainerId()

Specified by:

getContainerId in interface ContainerState

Returns:

the id of the container

start

public void start()

Starts the container using docker, pulling an image if necessary.

Specified by:

start in interface Startable

doStart

protected void doStart()

canBeReused

@UnstableAPI
protected boolean canBeReused()

stop

public void stop()

Stops the container.

Specified by:

stop in interface Startable

logger

protected org.slf4j.Logger logger()

Provide a logger that references the docker image name.

Returns:

a logger that references the docker image name

createVolumeDirectory

protected java.nio.file.Path createVolumeDirectory(boolean temporary)

Creates a directory on the local filesystem which will be mounted as a volume for the container.

Parameters:

temporary - is the volume directory temporary? If true, the directory will be deleted on JVM shutdown.

Returns:

path to the volume directory

configure

protected void configure()

containerIsCreated

protected void containerIsCreated(java.lang.String containerId)

containerIsStarting

protected void containerIsStarting(com.github.dockerjava.api.command.InspectContainerResponse containerInfo)

containerIsStarting

@UnstableAPI
protected void containerIsStarting(com.github.dockerjava.api.command.InspectContainerResponse containerInfo,
                                                boolean reused)

containerIsStarted

protected void containerIsStarted(com.github.dockerjava.api.command.InspectContainerResponse containerInfo)

containerIsStarted

@UnstableAPI
protected void containerIsStarted(com.github.dockerjava.api.command.InspectContainerResponse containerInfo,
                                               boolean reused)

containerIsStopping

protected void containerIsStopping(com.github.dockerjava.api.command.InspectContainerResponse containerInfo)

A hook that is executed before the container is stopped with stop(). Warning! This hook won't be executed if the container is terminated during the JVM's shutdown hook or by Ryuk.

containerIsStopped

protected void containerIsStopped(com.github.dockerjava.api.command.InspectContainerResponse containerInfo)

A hook that is executed after the container is stopped with stop(). Warning! This hook won't be executed if the container is terminated during the JVM's shutdown hook or by Ryuk.

getLivenessCheckPort

@Deprecated
protected java.lang.Integer getLivenessCheckPort()

Deprecated. see getLivenessCheckPorts() for replacement

Returns:

the port on which to check if the container is ready

getLivenessCheckPorts

@NotNull
 @NonNull
 @Deprecated
protected @NotNull @NonNull java.util.Set<java.lang.Integer> getLivenessCheckPorts()

Deprecated. use getLivenessCheckPortNumbers() instead

Returns:

the ports on which to check if the container is ready

getLivenessCheckPortNumbers

public java.util.Set<java.lang.Integer> getLivenessCheckPortNumbers()

Specified by:

getLivenessCheckPortNumbers in interface WaitStrategyTarget

Returns:

the ports on which to check if the container is ready

waitingFor

public SELF waitingFor(@NonNull
                       WaitStrategy waitStrategy)

Specify the WaitStrategy to use to determine if the container is ready.

Specified by:

waitingFor in interface Container<SELF extends GenericContainer<SELF>>

Parameters:

waitStrategy - the WaitStrategy to use

Returns:

this

See Also:

Wait.defaultWaitStrategy()

getWaitStrategy

protected WaitStrategy getWaitStrategy()

The WaitStrategy to use to determine if the container is ready. Defaults to Wait.defaultWaitStrategy().

Returns:

the WaitStrategy to use

setWaitStrategy

public void setWaitStrategy(WaitStrategy waitStrategy)

Specified by:

setWaitStrategy in interface Container<SELF extends GenericContainer<SELF>>

waitUntilContainerStarted

protected void waitUntilContainerStarted()

Wait until the container has started. The default implementation simply waits for a port to start listening; other implementations are available as implementations of WaitStrategy

See Also:

waitingFor(org.testcontainers.containers.wait.strategy.WaitStrategy)

setCommand

public void setCommand(@NonNull
                       @NonNull java.lang.String command)

Set the command that should be run in the container. Consider using Container.withCommand(String) for building a container in a fluent style.

Specified by:

setCommand in interface Container<SELF extends GenericContainer<SELF>>

Parameters:

command - a command in single string format (will automatically be split on spaces)

setCommand

public void setCommand(@NonNull
                       java.lang.String... commandParts)

Set the command that should be run in the container. Consider using Container.withCommand(String...) for building a container in a fluent style.

Specified by:

setCommand in interface Container<SELF extends GenericContainer<SELF>>

Parameters:

commandParts - a command as an array of string parts

getEnvMap

public java.util.Map<java.lang.String,java.lang.String> getEnvMap()

Specified by:

getEnvMap in interface Container<SELF extends GenericContainer<SELF>>

getEnv

public java.util.List<java.lang.String> getEnv()

Specified by:

getEnv in interface Container<SELF extends GenericContainer<SELF>>

setEnv

public void setEnv(java.util.List<java.lang.String> env)

Specified by:

setEnv in interface Container<SELF extends GenericContainer<SELF>>

addEnv

public void addEnv(java.lang.String key,
                   java.lang.String value)

Add an environment variable to be passed to the container. Consider using Container.withEnv(String, String) for building a container in a fluent style.

Specified by:

addEnv in interface Container<SELF extends GenericContainer<SELF>>

Parameters:

key - environment variable key

value - environment variable value

addFileSystemBind

public void addFileSystemBind(java.lang.String hostPath,
                              java.lang.String containerPath,
                              BindMode mode,
                              SelinuxContext selinuxContext)

Adds a file system binding. Consider using Container.withFileSystemBind(String, String, BindMode) for building a container in a fluent style.

Specified by:

addFileSystemBind in interface Container<SELF extends GenericContainer<SELF>>

Parameters:

hostPath - the file system path on the host

containerPath - the file system path inside the container

mode - the bind mode

selinuxContext - selinux context argument to use for this file

withFileSystemBind

public SELF withFileSystemBind(java.lang.String hostPath,
                               java.lang.String containerPath,
                               BindMode mode)

Adds a file system binding.

Specified by:

withFileSystemBind in interface Container<SELF extends GenericContainer<SELF>>

Parameters:

hostPath - the file system path on the host

containerPath - the file system path inside the container

mode - the bind mode

Returns:

this

withVolumesFrom

public SELF withVolumesFrom(Container container,
                            BindMode mode)

Adds container volumes.

Specified by:

withVolumesFrom in interface Container<SELF extends GenericContainer<SELF>>

Parameters:

container - the container to add volumes from

mode - the bind mode

Returns:

this

addLink

@Deprecated
public void addLink(LinkableContainer otherContainer,
                                java.lang.String alias)

Deprecated. Links are deprecated (see #465). Please use Network features instead.

Description copied from interface: Container

Add a link to another container.

Specified by:

addLink in interface Container<SELF extends GenericContainer<SELF>>

Parameters:

otherContainer - the other container object to link to

alias - the alias (for the other container) that this container should be able to use

addExposedPort

public void addExposedPort(java.lang.Integer port)

Description copied from interface: Container

Add an exposed port. Consider using Container.withExposedPorts(Integer...) for building a container in a fluent style.

Specified by:

addExposedPort in interface Container<SELF extends GenericContainer<SELF>>

Parameters:

port - a TCP port

addExposedPorts

public void addExposedPorts(int... ports)

Description copied from interface: Container

Add exposed ports. Consider using Container.withExposedPorts(Integer...) for building a container in a fluent style.

Specified by:

addExposedPorts in interface Container<SELF extends GenericContainer<SELF>>

Parameters:

ports - an array of TCP ports

apply

@Deprecated
public org.junit.runners.model.Statement apply(org.junit.runners.model.Statement base,
                                                           org.junit.runner.Description description)

Deprecated.

Specified by:

apply in interface org.junit.rules.TestRule

Overrides:

apply in class FailureDetectingExternalResource

starting

@Deprecated
protected void starting(org.junit.runner.Description description)

Deprecated.

Overrides:

starting in class FailureDetectingExternalResource

succeeded

@Deprecated
protected void succeeded(org.junit.runner.Description description)

Deprecated.

Overrides:

succeeded in class FailureDetectingExternalResource

failed

@Deprecated
protected void failed(java.lang.Throwable e,
                                  org.junit.runner.Description description)

Deprecated.

Overrides:

failed in class FailureDetectingExternalResource

finished

@Deprecated
protected void finished(org.junit.runner.Description description)

Deprecated.

Overrides:

finished in class FailureDetectingExternalResource

withExposedPorts

public SELF withExposedPorts(java.lang.Integer... ports)

Set the ports that this container listens on

Specified by:

withExposedPorts in interface Container<SELF extends GenericContainer<SELF>>

Parameters:

ports - an array of TCP ports

Returns:

this

addFixedExposedPort

protected void addFixedExposedPort(int hostPort,
                                   int containerPort)

Add a TCP container port that should be bound to a fixed port on the docker host.

Note that this method is protected scope to discourage use, as clashes or instability are more likely when using fixed port mappings. If you need to use this method from a test, please use FixedHostPortGenericContainer instead of GenericContainer.

Parameters:

hostPort -

containerPort -

addFixedExposedPort

protected void addFixedExposedPort(int hostPort,
                                   int containerPort,
                                   InternetProtocol protocol)

Add a container port that should be bound to a fixed port on the docker host.

Note that this method is protected scope to discourage use, as clashes or instability are more likely when using fixed port mappings. If you need to use this method from a test, please use FixedHostPortGenericContainer instead of GenericContainer.

Parameters:

hostPort -

containerPort -

protocol -

withEnv

public SELF withEnv(java.lang.String key,
                    java.lang.String value)

Add an environment variable to be passed to the container.

Specified by:

withEnv in interface Container<SELF extends GenericContainer<SELF>>

Parameters:

key - environment variable key

value - environment variable value

Returns:

this

withEnv

public SELF withEnv(java.util.Map<java.lang.String,java.lang.String> env)

Add environment variables to be passed to the container.

Specified by:

withEnv in interface Container<SELF extends GenericContainer<SELF>>

Parameters:

env - map of environment variables

Returns:

this

withLabel

public SELF withLabel(java.lang.String key,
                      java.lang.String value)

Add a label to the container.

Specified by:

withLabel in interface Container<SELF extends GenericContainer<SELF>>

Parameters:

key - label key

value - label value

Returns:

this

withLabels

public SELF withLabels(java.util.Map<java.lang.String,java.lang.String> labels)

Add labels to the container.

Specified by:

withLabels in interface Container<SELF extends GenericContainer<SELF>>

Parameters:

labels - map of labels

Returns:

this

withCommand

public SELF withCommand(java.lang.String cmd)

Set the command that should be run in the container

Specified by:

withCommand in interface Container<SELF extends GenericContainer<SELF>>

Parameters:

cmd - a command in single string format (will automatically be split on spaces)

Returns:

this

withCommand

public SELF withCommand(java.lang.String... commandParts)

Set the command that should be run in the container

Specified by:

withCommand in interface Container<SELF extends GenericContainer<SELF>>

Parameters:

commandParts - a command as an array of string parts

Returns:

this

withExtraHost

public SELF withExtraHost(java.lang.String hostname,
                          java.lang.String ipAddress)

Add an extra host entry to be passed to the container

Specified by:

withExtraHost in interface Container<SELF extends GenericContainer<SELF>>

Parameters:

hostname - hostname to use for this hosts file entry

ipAddress - IP address to use for this hosts file entry

Returns:

this

withNetworkMode

public SELF withNetworkMode(java.lang.String networkMode)

Description copied from interface: Container

Set the network mode for this container, similar to the --net <name> option on the docker CLI.

Specified by:

withNetworkMode in interface Container<SELF extends GenericContainer<SELF>>

Parameters:

networkMode - network mode, e.g. including 'host', 'bridge', 'none' or the name of an existing named network.

Returns:

this

withNetwork

public SELF withNetwork(Network network)

Description copied from interface: Container

Set the network for this container, similar to the --network <name> option on the docker CLI.

Specified by:

withNetwork in interface Container<SELF extends GenericContainer<SELF>>

Parameters:

network - the instance of Network

Returns:

this

withNetworkAliases

public SELF withNetworkAliases(java.lang.String... aliases)

Description copied from interface: Container

Set the network aliases for this container, similar to the --network-alias <my-service> option on the docker CLI.

Specified by:

withNetworkAliases in interface Container<SELF extends GenericContainer<SELF>>

Parameters:

aliases - the list of aliases

Returns:

this

withImagePullPolicy

public SELF withImagePullPolicy(ImagePullPolicy imagePullPolicy)

Description copied from interface: Container

Set the image pull policy of the container

Specified by:

withImagePullPolicy in interface Container<SELF extends GenericContainer<SELF>>

Returns:

withClasspathResourceMapping

public SELF withClasspathResourceMapping(java.lang.String resourcePath,
                                         java.lang.String containerPath,
                                         BindMode mode)

Map a resource (file or directory) on the classpath to a path inside the container. This will only work if you are running your tests outside a Docker container.

Specified by:

withClasspathResourceMapping in interface Container<SELF extends GenericContainer<SELF>>

Parameters:

resourcePath - path to the resource on the classpath (relative to the classpath root; should not start with a leading slash)

containerPath - path this should be mapped to inside the container

mode - access mode for the file

Returns:

this

withClasspathResourceMapping

public SELF withClasspathResourceMapping(java.lang.String resourcePath,
                                         java.lang.String containerPath,
                                         BindMode mode,
                                         SelinuxContext selinuxContext)

Map a resource (file or directory) on the classpath to a path inside the container. This will only work if you are running your tests outside a Docker container.

Specified by:

withClasspathResourceMapping in interface Container<SELF extends GenericContainer<SELF>>

Parameters:

resourcePath - path to the resource on the classpath (relative to the classpath root; should not start with a leading slash)

containerPath - path this should be mapped to inside the container

mode - access mode for the file

selinuxContext - selinux context argument to use for this file

Returns:

this

withStartupTimeout

public SELF withStartupTimeout(java.time.Duration startupTimeout)

Set the duration of waiting time until container treated as started.

Specified by:

withStartupTimeout in interface Container<SELF extends GenericContainer<SELF>>

Parameters:

startupTimeout - timeout

Returns:

this

See Also:

WaitStrategy.waitUntilReady(org.testcontainers.containers.wait.strategy.WaitStrategyTarget)

withPrivilegedMode

public SELF withPrivilegedMode(boolean mode)

Description copied from interface: Container

Set the privilegedMode mode for the container

Specified by:

withPrivilegedMode in interface Container<SELF extends GenericContainer<SELF>>

Parameters:

mode - boolean

Returns:

this

withMinimumRunningDuration

public SELF withMinimumRunningDuration(java.time.Duration minimumRunningDuration)

Only consider a container to have successfully started if it has been running for this duration. The default value is null; if that's the value, ignore this check.

Specified by:

withMinimumRunningDuration in interface Container<SELF extends GenericContainer<SELF>>

Parameters:

minimumRunningDuration - duration this container should run for if started successfully

Returns:

this

withStartupCheckStrategy

public SELF withStartupCheckStrategy(StartupCheckStrategy strategy)

Set the startup check strategy used for checking whether the container has started.

Specified by:

withStartupCheckStrategy in interface Container<SELF extends GenericContainer<SELF>>

Parameters:

strategy - startup check strategy

withWorkingDirectory

public SELF withWorkingDirectory(java.lang.String workDir)

Set the working directory that the container should use on startup.

Specified by:

withWorkingDirectory in interface Container<SELF extends GenericContainer<SELF>>

Parameters:

workDir - path to the working directory inside the container

withCopyFileToContainer

public SELF withCopyFileToContainer(MountableFile mountableFile,
                                    java.lang.String containerPath)

Set the file to be copied before starting a created container

Specified by:

withCopyFileToContainer in interface Container<SELF extends GenericContainer<SELF>>

Parameters:

mountableFile - a Mountable file with path of source file / folder on host machine

containerPath - a destination path on conatiner to which the files / folders to be copied

Returns:

this

getIpAddress

@Deprecated
public java.lang.String getIpAddress()

Deprecated. please use getContainerIpAddress() instead

Get the IP address that this container may be reached on (may not be the local machine).

Returns:

an IP address

setDockerImageName

public void setDockerImageName(@NonNull
                               @NonNull java.lang.String dockerImageName)

Resolve Docker image and set it.

Specified by:

setDockerImageName in interface Container<SELF extends GenericContainer<SELF>>

Parameters:

dockerImageName - image name

getDockerImageName

@NonNull
public @NonNull java.lang.String getDockerImageName()

Get image name.

Specified by:

getDockerImageName in interface Container<SELF extends GenericContainer<SELF>>

Returns:

image name

getTestHostIpAddress

public java.lang.String getTestHostIpAddress()

Get the IP address that containers (e.g. browsers) can use to reference a service running on the local machine, i.e. the machine on which this test is running.

For example, if a web server is running on port 8080 on this local machine, the containerized web driver needs to be pointed at "http://" + getTestHostIpAddress() + ":8080" in order to access it. Trying to hit localhost from inside the container is not going to work, since the container has its own IP address.

Specified by:

getTestHostIpAddress in interface Container<SELF extends GenericContainer<SELF>>

Returns:

the IP address of the host machine

withLogConsumer

public SELF withLogConsumer(java.util.function.Consumer<OutputFrame> consumer)

Attach an output consumer at container startup, enabling stdout and stderr to be followed, waited on, etc.

More than one consumer may be registered.

Specified by:

withLogConsumer in interface Container<SELF extends GenericContainer<SELF>>

Parameters:

consumer - consumer that output frames should be sent to

Returns:

this

copyFileFromContainer

public void copyFileFromContainer(java.lang.String containerPath,
                                  java.lang.String destinationPath)

Copies a file which resides inside the container to user defined directory

Specified by:

copyFileFromContainer in interface ContainerState

Parameters:

containerPath - path to file which is copied from container

destinationPath - destination path to which file is copied with file name

withStartupAttempts

public SELF withStartupAttempts(int attempts)

Allow container startup to be attempted more than once if an error occurs. To be used if containers are 'flaky' but this flakiness is not something that should affect test outcomes.

Parameters:

attempts - number of attempts

withCreateContainerCmdModifier

public SELF withCreateContainerCmdModifier(java.util.function.Consumer<com.github.dockerjava.api.command.CreateContainerCmd> modifier)

Allow low level modifications of CreateContainerCmd after it was pre-configured in tryStart(Instant). Invocation happens eagerly on a moment when container is created. Warning: this does expose the underlying docker-java API so might change outside of our control.

Parameters:

modifier - Consumer of CreateContainerCmd.

Returns:

this

withSharedMemorySize

public SELF withSharedMemorySize(java.lang.Long bytes)

Size of /dev/shm

Parameters:

bytes - The number of bytes to assign the shared memory. If null, it will apply the Docker default which is 64 MB.

Returns:

this

withTmpFs

public SELF withTmpFs(java.util.Map<java.lang.String,java.lang.String> mapping)

First class support for configuring tmpfs

Parameters:

mapping - path and params of tmpfs/mount flag for container

Returns:

this

withReuse

@UnstableAPI
public SELF withReuse(boolean reusable)

equals

public boolean equals(java.lang.Object o)

Overrides:

equals in class java.lang.Object

hashCode

public int hashCode()

Overrides:

hashCode in class java.lang.Object

getContainerName

public java.lang.String getContainerName()

Specified by:

getContainerName in interface LinkableContainer

getPortBindings

@NonNull
public @NonNull java.util.List<java.lang.String> getPortBindings()

Specified by:

getPortBindings in interface Container<SELF extends GenericContainer<SELF>>

Specified by:

getPortBindings in interface ContainerState

Returns:

the port bindings

getExtraHosts

@NonNull
public @NonNull java.util.List<java.lang.String> getExtraHosts()

Specified by:

getExtraHosts in interface Container<SELF extends GenericContainer<SELF>>

getNetworkMode

@NonNull
public @NonNull java.lang.String getNetworkMode()

getNetwork

@NonNull
public @NonNull Network getNetwork()

getNetworkAliases

@NonNull
public @NonNull java.util.List<java.lang.String> getNetworkAliases()

getImage

@NonNull
public @NonNull RemoteDockerImage getImage()

Specified by:

getImage in interface Container<SELF extends GenericContainer<SELF>>

getLabels

@NonNull
public @NonNull java.util.Map<java.lang.String,java.lang.String> getLabels()

getCommandParts

@NonNull
public @NonNull java.lang.String[] getCommandParts()

Specified by:

getCommandParts in interface Container<SELF extends GenericContainer<SELF>>

getBinds

@NonNull
public @NonNull java.util.List<com.github.dockerjava.api.model.Bind> getBinds()

Specified by:

getBinds in interface Container<SELF extends GenericContainer<SELF>>

isPrivilegedMode

public boolean isPrivilegedMode()

getVolumesFroms

@NonNull
public @NonNull java.util.List<com.github.dockerjava.api.model.VolumesFrom> getVolumesFroms()

getLinkedContainers

@Deprecated
 @NonNull
public @NonNull java.util.Map<java.lang.String,LinkableContainer> getLinkedContainers()

Deprecated. Links are deprecated (see #465). Please use Network features instead.

Specified by:

getLinkedContainers in interface Container<SELF extends GenericContainer<SELF>>

getStartupCheckStrategy

public StartupCheckStrategy getStartupCheckStrategy()

getStartupAttempts

public int getStartupAttempts()

getWorkingDirectory

@Nullable
public @Nullable java.lang.String getWorkingDirectory()

getShmSize

@Nullable
public @Nullable java.lang.Long getShmSize()

The shared memory size to use when starting the container. This value is in bytes.

getCopyToFileContainerPathMap

public java.util.Map<MountableFile,java.lang.String> getCopyToFileContainerPathMap()

getDependencies

public java.util.Set<Startable> getDependencies()

Specified by:

getDependencies in interface Startable

getDockerClient

public com.github.dockerjava.api.DockerClient getDockerClient()

Unique instance of DockerClient for use by this container object. We use DockerClientFactory.lazyClient() here to avoid eager client creation

Specified by:

getDockerClient in interface Container<SELF extends GenericContainer<SELF>>

getContainerInfo

public com.github.dockerjava.api.command.InspectContainerResponse getContainerInfo()

Specified by:

getContainerInfo in interface ContainerState

Returns:

the container info

getLogConsumers

public java.util.List<java.util.function.Consumer<OutputFrame>> getLogConsumers()

getCreateContainerCmdModifiers

public java.util.Set<java.util.function.Consumer<com.github.dockerjava.api.command.CreateContainerCmd>> getCreateContainerCmdModifiers()

getTmpFsMapping

@Nullable
public @Nullable java.util.Map<java.lang.String,java.lang.String> getTmpFsMapping()

isShouldBeReused

public boolean isShouldBeReused()

setPortBindings

public void setPortBindings(@NonNull
                            @NonNull java.util.List<java.lang.String> portBindings)

Specified by:

setPortBindings in interface Container<SELF extends GenericContainer<SELF>>

setExtraHosts

public void setExtraHosts(@NonNull
                          @NonNull java.util.List<java.lang.String> extraHosts)

Specified by:

setExtraHosts in interface Container<SELF extends GenericContainer<SELF>>

setNetworkMode

public void setNetworkMode(@NonNull
                           @NonNull java.lang.String networkMode)

setNetwork

public void setNetwork(@NonNull
                       @NonNull Network network)

setNetworkAliases

public void setNetworkAliases(@NonNull
                              @NonNull java.util.List<java.lang.String> networkAliases)

setLabels

public void setLabels(@NonNull
                      @NonNull java.util.Map<java.lang.String,java.lang.String> labels)

setCommandParts

public void setCommandParts(@NonNull
                            @NonNull java.lang.String[] commandParts)

Specified by:

setCommandParts in interface Container<SELF extends GenericContainer<SELF>>

setBinds

public void setBinds(@NonNull
                     @NonNull java.util.List<com.github.dockerjava.api.model.Bind> binds)

Specified by:

setBinds in interface Container<SELF extends GenericContainer<SELF>>

setPrivilegedMode

public void setPrivilegedMode(boolean privilegedMode)

setVolumesFroms

public void setVolumesFroms(@NonNull
                            @NonNull java.util.List<com.github.dockerjava.api.model.VolumesFrom> volumesFroms)

setLinkedContainers

@Deprecated
public void setLinkedContainers(@NonNull
                                            @NonNull java.util.Map<java.lang.String,LinkableContainer> linkedContainers)

Deprecated. Links are deprecated (see #465). Please use Network features instead.

Specified by:

setLinkedContainers in interface Container<SELF extends GenericContainer<SELF>>

setStartupCheckStrategy

public void setStartupCheckStrategy(StartupCheckStrategy startupCheckStrategy)

setStartupAttempts

public void setStartupAttempts(int startupAttempts)

setWorkingDirectory

public void setWorkingDirectory(@Nullable
                                @Nullable java.lang.String workingDirectory)

setShmSize

public void setShmSize(@Nullable
                       @Nullable java.lang.Long shmSize)

The shared memory size to use when starting the container. This value is in bytes.

setCopyToFileContainerPathMap

public void setCopyToFileContainerPathMap(java.util.Map<MountableFile,java.lang.String> copyToFileContainerPathMap)

setLogConsumers

public void setLogConsumers(java.util.List<java.util.function.Consumer<OutputFrame>> logConsumers)

setTmpFsMapping

public void setTmpFsMapping(@Nullable
                            @Nullable java.util.Map<java.lang.String,java.lang.String> tmpFsMapping)

toString

public java.lang.String toString()

Overrides:

toString in class java.lang.Object