org.testcontainers.containers

Interface Container<SELF extends Container<SELF>>

All Superinterfaces:

ContainerState, LinkableContainer

All Known Implementing Classes:

FixedHostPortGenericContainer, GenericContainer, SocatContainer, VncRecordingContainer

public interface Container<SELF extends Container<SELF>>
extends LinkableContainer, ContainerState

Nested Class Summary

Nested Classes

Modifier and Type	Interface and Description
static class	Container.ExecResult Class to hold results from a "docker exec" command

Field Summary

Fields inherited from interface org.testcontainers.containers.ContainerState

STATE_HEALTHY

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.
default void	addFileSystemBind(java.lang.String hostPath, java.lang.String containerPath, BindMode mode) Adds a file system binding.
void	addFileSystemBind(java.lang.String hostPath, java.lang.String containerPath, BindMode mode, SelinuxContext selinuxContext) Adds a file system binding.
void	addLink(LinkableContainer otherContainer, java.lang.String alias) Deprecated. Links are deprecated (see #465). Please use Network features instead.
default void	followOutput(java.util.function.Consumer<OutputFrame> consumer) Follow container output, sending each frame (usually, line) to a consumer.
default void	followOutput(java.util.function.Consumer<OutputFrame> consumer, OutputFrame.OutputType... types) Follow container output, sending each frame (usually, line) to a consumer.
java.util.List<com.github.dockerjava.api.model.Bind>	getBinds()
java.lang.String[]	getCommandParts()
@NonNull java.lang.String	getDockerImageName() Get image name.
java.util.List<java.lang.String>	getEnv() Deprecated. use getEnvMap
java.util.Map<java.lang.String,java.lang.String>	getEnvMap()
java.util.List<java.lang.String>	getExtraHosts()
java.util.concurrent.Future<java.lang.String>	getImage()
java.util.Map<java.lang.String,LinkableContainer>	getLinkedContainers() Deprecated. Links are deprecated (see #465). Please use Network features instead.
java.util.List<java.lang.String>	getPortBindings()
java.lang.String	getTestHostIpAddress() Deprecated. use Testcontainers.exposeHostPorts(int...)
default SELF	self()
void	setBinds(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(java.lang.String[] commandParts)
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(java.util.List<java.lang.String> extraHosts)
void	setImage(java.util.concurrent.Future<java.lang.String> image)
void	setLinkedContainers(java.util.Map<java.lang.String,LinkableContainer> linkedContainers) Deprecated. Links are deprecated (see #465). Please use Network features instead.
void	setPortBindings(java.util.List<java.lang.String> portBindings)
void	setWaitStrategy(WaitStrategy waitStrategy)
SELF	waitingFor(@NonNull WaitStrategy waitStrategy) Specify the WaitStrategy to use to determine if the container is ready.
default 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) Deprecated. Use withCopyToContainer(Transferable, String) instead
SELF	withCopyToContainer(Transferable transferable, java.lang.String containerPath) Set the content to be copied before starting a created container
SELF	withEnv(java.util.Map<java.lang.String,java.lang.String> env) Add environment variables to be passed to the container.
default SELF	withEnv(java.lang.String key, java.util.function.Function<java.util.Optional<java.lang.String>,java.lang.String> mapper) Add an environment variable 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
default SELF	withFileSystemBind(java.lang.String hostPath, java.lang.String containerPath) Adds a file system binding.
SELF	withFileSystemBind(java.lang.String hostPath, java.lang.String containerPath, BindMode mode) Adds a file system binding.
SELF	withImagePullPolicy(ImagePullPolicy policy) 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	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	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 interface org.testcontainers.containers.traits.LinkableContainer

getContainerName

Methods inherited from interface org.testcontainers.containers.ContainerState

copyFileFromContainer, copyFileFromContainer, copyFileToContainer, copyFileToContainer, execInContainer, execInContainer, execInContainerWithUser, execInContainerWithUser, getBoundPortNumbers, getContainerId, getContainerInfo, getContainerIpAddress, getCurrentContainerInfo, getDockerClient, getExposedPorts, getFirstMappedPort, getHost, getLogs, getLogs, getMappedPort, isCreated, isHealthy, isRunning

Method Detail

self

default SELF self()

Returns:

a reference to this container instance, cast to the expected generic type.

setCommand

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

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

Parameters:

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

setCommand

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

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

Parameters:

commandParts - a command as an array of string parts

addEnv

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

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

Parameters:

key - environment variable key

value - environment variable value

addFileSystemBind

default void addFileSystemBind(java.lang.String hostPath,
                               java.lang.String containerPath,
                               BindMode mode)

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

Parameters:

hostPath - the file system path on the host

containerPath - the file system path inside the container

mode - the bind mode

addFileSystemBind

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

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

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

addLink

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

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

Add a link to another container.

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

void addExposedPort(java.lang.Integer port)

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

Parameters:

port - a TCP port

addExposedPorts

void addExposedPorts(int... ports)

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

Parameters:

ports - an array of TCP ports

waitingFor

SELF waitingFor(@NonNull
                @NonNull WaitStrategy waitStrategy)

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

Parameters:

waitStrategy - the WaitStrategy to use

Returns:

this

See Also:

Wait.defaultWaitStrategy()

withFileSystemBind

default SELF withFileSystemBind(java.lang.String hostPath,
                                java.lang.String containerPath)

Adds a file system binding.

Parameters:

hostPath - the file system path on the host

containerPath - the file system path inside the container

Returns:

this

withFileSystemBind

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

Adds a file system binding.

Parameters:

hostPath - the file system path on the host

containerPath - the file system path inside the container

mode - the bind mode

Returns:

this

withVolumesFrom

SELF withVolumesFrom(Container container,
                     BindMode mode)

Adds container volumes.

Parameters:

container - the container to add volumes from

mode - the bind mode

Returns:

this

withExposedPorts

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

Set the ports that this container listens on

Parameters:

ports - an array of TCP ports

Returns:

this

withCopyFileToContainer

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

Deprecated. Use withCopyToContainer(Transferable, String) instead

Set the file to be copied before starting a created container

Parameters:

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

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

Returns:

this

withCopyToContainer

SELF withCopyToContainer(Transferable transferable,
                         java.lang.String containerPath)

Set the content to be copied before starting a created container

Parameters:

transferable - a Transferable

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

Returns:

this

withEnv

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

Add an environment variable to be passed to the container.

Parameters:

key - environment variable key

value - environment variable value

Returns:

this

withEnv

default SELF withEnv(java.lang.String key,
                     java.util.function.Function<java.util.Optional<java.lang.String>,java.lang.String> mapper)

Add an environment variable to be passed to the container.

Parameters:

key - environment variable key

mapper - environment variable value mapper, accepts old value as an argument

Returns:

this

withEnv

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

Add environment variables to be passed to the container.

Parameters:

env - map of environment variables

Returns:

this

withLabel

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

Add a label to the container.

Parameters:

key - label key

value - label value

Returns:

this

withLabels

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

Add labels to the container.

Parameters:

labels - map of labels

Returns:

this

withCommand

SELF withCommand(java.lang.String cmd)

Set the command that should be run in the container

Parameters:

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

Returns:

this

withCommand

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

Set the command that should be run in the container

Parameters:

commandParts - a command as an array of string parts

Returns:

this

withExtraHost

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

Add an extra host entry to be passed to the container

Parameters:

hostname - hostname to use for this hosts file entry

ipAddress - IP address to use for this hosts file entry

Returns:

this

withNetworkMode

SELF withNetworkMode(java.lang.String networkMode)

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

Parameters:

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

Returns:

this

withNetwork

SELF withNetwork(Network network)

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

Parameters:

network - the instance of Network

Returns:

this

withNetworkAliases

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.

Parameters:

aliases - the list of aliases

Returns:

this

withImagePullPolicy

SELF withImagePullPolicy(ImagePullPolicy policy)

Set the image pull policy of the container

Returns:

withClasspathResourceMapping

default 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.

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

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.

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

SELF withStartupTimeout(java.time.Duration startupTimeout)

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

Parameters:

startupTimeout - timeout

Returns:

this

See Also:

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

withPrivilegedMode

SELF withPrivilegedMode(boolean mode)

Set the privilegedMode mode for the container

Parameters:

mode - boolean

Returns:

this

withMinimumRunningDuration

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.

Parameters:

minimumRunningDuration - duration this container should run for if started successfully

Returns:

this

withStartupCheckStrategy

SELF withStartupCheckStrategy(StartupCheckStrategy strategy)

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

Parameters:

strategy - startup check strategy

withWorkingDirectory

SELF withWorkingDirectory(java.lang.String workDir)

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

Parameters:

workDir - path to the working directory inside the container

setDockerImageName

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

Resolve Docker image and set it.

Parameters:

dockerImageName - image name

getDockerImageName

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

Get image name.

Returns:

image name

getTestHostIpAddress

@Deprecated
java.lang.String getTestHostIpAddress()

Deprecated. use Testcontainers.exposeHostPorts(int...)

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.

Returns:

the IP address of the host machine

followOutput

default void followOutput(java.util.function.Consumer<OutputFrame> consumer)

Follow container output, sending each frame (usually, line) to a consumer. Stdout and stderr will be followed.

Parameters:

consumer - consumer that the frames should be sent to

followOutput

default void followOutput(java.util.function.Consumer<OutputFrame> consumer,
                          OutputFrame.OutputType... types)

Follow container output, sending each frame (usually, line) to a consumer. This method allows Stdout and/or stderr to be selected.

Parameters:

consumer - consumer that the frames should be sent to

types - types that should be followed (one or both of STDOUT, STDERR)

withLogConsumer

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.

Parameters:

consumer - consumer that output frames should be sent to

Returns:

this

getPortBindings

java.util.List<java.lang.String> getPortBindings()

Specified by:

getPortBindings in interface ContainerState

Returns:

the port bindings

getExtraHosts

java.util.List<java.lang.String> getExtraHosts()

getImage

java.util.concurrent.Future<java.lang.String> getImage()

getEnv

@Deprecated
java.util.List<java.lang.String> getEnv()

Deprecated. use getEnvMap

getEnvMap

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

getCommandParts

java.lang.String[] getCommandParts()

getBinds

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

getLinkedContainers

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

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

setExposedPorts

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

setPortBindings

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

setExtraHosts

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

setImage

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

setEnv

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

setCommandParts

void setCommandParts(java.lang.String[] commandParts)

setBinds

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

setLinkedContainers

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

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

setWaitStrategy

void setWaitStrategy(WaitStrategy waitStrategy)