org.testcontainers.containers

Interface Container<SELF extends Container<SELF>>

All Superinterfaces:

ContainerState, LinkableContainer

All Known Implementing Classes:

AmbassadorContainer, 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.
void	copyFileFromContainer(java.lang.String containerPath, java.lang.String destinationPath) Copies a file which resides inside the container to user defined directory
<T> T	copyFileFromContainer(java.lang.String containerPath, ThrowingFunction<java.io.InputStream,T> function) Streams a file which resides inside the container
void	copyFileToContainer(MountableFile mountableFile, java.lang.String containerPath) Copies a file or directory to the container.
void	copyFileToContainer(Transferable transferable, java.lang.String containerPath) Copies a file to the container.
Container.ExecResult	execInContainer(java.nio.charset.Charset outputCharset, java.lang.String... command) Run a command inside a running container, as though using "docker exec".
Container.ExecResult	execInContainer(java.lang.String... command) Run a command inside a running container, as though using "docker exec", and interpreting the output as UTF8.
com.github.dockerjava.api.model.Info	fetchDockerDaemonInfo() Deprecated. please use org.testcontainers.DockerClientFactory.instance().client().infoCmd().exec()
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()
com.github.dockerjava.api.DockerClient	getDockerClient()
com.github.dockerjava.api.model.Info	getDockerDaemonInfo() Deprecated. please use org.testcontainers.DockerClientFactory.instance().client().infoCmd().exec()
@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() Get the IP address that containers (e.g.
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) Set the file 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

getBoundPortNumbers, getContainerId, getContainerInfo, getContainerIpAddress, getCurrentContainerInfo, getExposedPorts, getFirstMappedPort, 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

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

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 conatiner 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

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.

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

fetchDockerDaemonInfo

@Deprecated
com.github.dockerjava.api.model.Info fetchDockerDaemonInfo()
                                                                throws java.io.IOException

Deprecated. please use org.testcontainers.DockerClientFactory.instance().client().infoCmd().exec()

Throws:

java.io.IOException

execInContainer

Container.ExecResult execInContainer(java.lang.String... command)
                              throws java.lang.UnsupportedOperationException,
                                     java.io.IOException,
                                     java.lang.InterruptedException

Run a command inside a running container, as though using "docker exec", and interpreting the output as UTF8.

Throws:

java.lang.UnsupportedOperationException

java.io.IOException

java.lang.InterruptedException

See Also:

ExecInContainerPattern.execInContainer(com.github.dockerjava.api.command.InspectContainerResponse, String...)

execInContainer

Container.ExecResult execInContainer(java.nio.charset.Charset outputCharset,
                                     java.lang.String... command)
                              throws java.lang.UnsupportedOperationException,
                                     java.io.IOException,
                                     java.lang.InterruptedException

Run a command inside a running container, as though using "docker exec".

Throws:

java.lang.UnsupportedOperationException

java.io.IOException

java.lang.InterruptedException

See Also:

ExecInContainerPattern.execInContainer(com.github.dockerjava.api.command.InspectContainerResponse, Charset, String...)

copyFileToContainer

void copyFileToContainer(MountableFile mountableFile,
                         java.lang.String containerPath)
                  throws java.io.IOException,
                         java.lang.InterruptedException

Copies a file or directory to the container.

Parameters:

mountableFile - file or directory which is copied into the container

containerPath - destination path inside the container

Throws:

java.io.IOException - if there's an issue communicating with Docker

java.lang.InterruptedException - if the thread waiting for the response is interrupted

copyFileToContainer

void copyFileToContainer(Transferable transferable,
                         java.lang.String containerPath)

Copies a file to the container.

Parameters:

transferable - file which is copied into the container

containerPath - destination path inside the container

copyFileFromContainer

void copyFileFromContainer(java.lang.String containerPath,
                           java.lang.String destinationPath)
                    throws java.io.IOException,
                           java.lang.InterruptedException

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

Parameters:

containerPath - path to file which is copied from container

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

Throws:

java.io.IOException - if there's an issue communicating with Docker or receiving entry from TarArchiveInputStream

java.lang.InterruptedException - if the thread waiting for the response is interrupted

copyFileFromContainer

<T> T copyFileFromContainer(java.lang.String containerPath,
                            ThrowingFunction<java.io.InputStream,T> function)

Streams a file which resides inside the container

Parameters:

containerPath - path to file which is copied from container

function - function that takes InputStream of the copied file

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.

getDockerClient

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

getDockerDaemonInfo

@Deprecated
com.github.dockerjava.api.model.Info getDockerDaemonInfo()

Deprecated. please use org.testcontainers.DockerClientFactory.instance().client().infoCmd().exec()

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)