org.testcontainers.containers

Class ComposeContainer

java.lang.Object

org.testcontainers.containers.FailureDetectingExternalResource

org.testcontainers.containers.ComposeContainer

All Implemented Interfaces:

java.lang.AutoCloseable, org.junit.rules.TestRule, Startable

public class ComposeContainer
extends FailureDetectingExternalResource
implements Startable

Testcontainers implementation for Docker Compose V2.
It uses either Compose V2 contained within the Docker binary, or a containerised version of Compose V2.

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	ComposeContainer.RemoveImages

Field Summary

Fields

Modifier and Type	Field and Description
static java.lang.String	COMPOSE_EXECUTABLE

Constructor Summary

Constructors

Constructor and Description
ComposeContainer(java.io.File... composeFiles)
ComposeContainer(java.util.List<java.io.File> composeFiles)
ComposeContainer(java.lang.String identifier, java.io.File... composeFiles)
ComposeContainer(java.lang.String identifier, java.util.List<java.io.File> composeFiles)

Method Summary

Modifier and Type	Method and Description
org.junit.runners.model.Statement	apply(org.junit.runners.model.Statement base, org.junit.runner.Description description) Deprecated.
protected void	failed(java.lang.Throwable e, org.junit.runner.Description description) Deprecated.
void	finished(org.junit.runner.Description description) Deprecated.
java.util.Optional<ContainerState>	getContainerByServiceName(java.lang.String serviceName)
java.lang.String	getServiceHost(java.lang.String serviceName, java.lang.Integer servicePort) Get the host (e.g.
java.lang.Integer	getServicePort(java.lang.String serviceName, java.lang.Integer servicePort) Get the port that an exposed service can be found at, from the host machine (i.e.
void	start()
void	starting(org.junit.runner.Description description) Deprecated.
void	stop()
protected void	succeeded(org.junit.runner.Description description) Deprecated.
ComposeContainer	waitingFor(java.lang.String serviceName, @NonNull WaitStrategy waitStrategy) Specify the WaitStrategy to use to determine if the container is ready.
ComposeContainer	withBuild(boolean build) Whether to always build images before starting containers.
ComposeContainer	withEnv(java.util.Map<java.lang.String,java.lang.String> env)
ComposeContainer	withEnv(java.lang.String key, java.lang.String value)
ComposeContainer	withExposedService(java.lang.String serviceName, int servicePort)
ComposeContainer	withExposedService(java.lang.String serviceName, int instance, int servicePort)
ComposeContainer	withExposedService(java.lang.String serviceName, int instance, int servicePort, WaitStrategy waitStrategy)
ComposeContainer	withExposedService(java.lang.String serviceName, int servicePort, @NonNull WaitStrategy waitStrategy)
ComposeContainer	withLocalCompose(boolean localCompose) Use a local Docker Compose binary instead of a container.
ComposeContainer	withLogConsumer(java.lang.String serviceName, java.util.function.Consumer<OutputFrame> consumer) Attach an output consumer at container startup, enabling stdout and stderr to be followed, waited on, etc.
ComposeContainer	withOptions(java.lang.String... options) Adds options to the docker command, e.g.
ComposeContainer	withPull(boolean pull) Whether to pull images first.
ComposeContainer	withRemoveImages(ComposeContainer.RemoveImages removeImages) Remove images after containers shutdown.
ComposeContainer	withRemoveVolumes(boolean removeVolumes) Remove volumes after containers shut down.
ComposeContainer	withScaledService(java.lang.String serviceBaseName, int numInstances)
ComposeContainer	withServices(java.lang.String... services)
ComposeContainer	withStartupTimeout(java.time.Duration startupTimeout) Set the maximum startup timeout all the waits set are bounded to.
ComposeContainer	withTailChildContainers(boolean tailChildContainers) Whether to tail child container logs.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Methods inherited from interface org.testcontainers.lifecycle.Startable

close, getDependencies

Field Detail

COMPOSE_EXECUTABLE

public static final java.lang.String COMPOSE_EXECUTABLE

Constructor Detail

ComposeContainer

public ComposeContainer(java.io.File... composeFiles)

ComposeContainer

public ComposeContainer(java.util.List<java.io.File> composeFiles)

ComposeContainer

public ComposeContainer(java.lang.String identifier,
                        java.io.File... composeFiles)

ComposeContainer

public ComposeContainer(java.lang.String identifier,
                        java.util.List<java.io.File> composeFiles)

Method Detail

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
public 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
public void finished(org.junit.runner.Description description)

Deprecated.

Overrides:

finished in class FailureDetectingExternalResource

start

public void start()

Specified by:

start in interface Startable

withServices

public ComposeContainer withServices(@NonNull
                                     java.lang.String... services)

stop

public void stop()

Specified by:

stop in interface Startable

withExposedService

public ComposeContainer withExposedService(java.lang.String serviceName,
                                           int servicePort)

withExposedService

public ComposeContainer withExposedService(java.lang.String serviceName,
                                           int instance,
                                           int servicePort)

withExposedService

public ComposeContainer withExposedService(java.lang.String serviceName,
                                           int instance,
                                           int servicePort,
                                           WaitStrategy waitStrategy)

withExposedService

public ComposeContainer withExposedService(java.lang.String serviceName,
                                           int servicePort,
                                           @NonNull
                                           @NonNull WaitStrategy waitStrategy)

waitingFor

public ComposeContainer waitingFor(java.lang.String serviceName,
                                   @NonNull
                                   @NonNull WaitStrategy waitStrategy)

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

Parameters:

serviceName - the name of the service to wait for

waitStrategy - the WaitStrategy to use

Returns:

this

See Also:

Wait.defaultWaitStrategy()

getServiceHost

public java.lang.String getServiceHost(java.lang.String serviceName,
                                       java.lang.Integer servicePort)

Get the host (e.g. IP address or hostname) that an exposed service can be found at, from the host machine (i.e. should be the machine that's running this Java process).

The service must have been declared using ComposeContainer#withExposedService.

Parameters:

serviceName - the name of the service as set in the docker-compose.yml file.

servicePort - the port exposed by the service container.

Returns:

a host IP address or hostname that can be used for accessing the service container.

getServicePort

public java.lang.Integer getServicePort(java.lang.String serviceName,
                                        java.lang.Integer servicePort)

Get the port that an exposed service can be found at, from the host machine (i.e. should be the machine that's running this Java process).

The service must have been declared using ComposeContainer#withExposedService.

Parameters:

serviceName - the name of the service as set in the docker-compose.yml file.

servicePort - the port exposed by the service container.

Returns:

a port that can be used for accessing the service container.

withScaledService

public ComposeContainer withScaledService(java.lang.String serviceBaseName,
                                          int numInstances)

withEnv

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

withEnv

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

withLocalCompose

public ComposeContainer withLocalCompose(boolean localCompose)

Use a local Docker Compose binary instead of a container.

Returns:

this instance, for chaining

withPull

public ComposeContainer withPull(boolean pull)

Whether to pull images first.

Returns:

this instance, for chaining

withTailChildContainers

public ComposeContainer withTailChildContainers(boolean tailChildContainers)

Whether to tail child container logs.

Returns:

this instance, for chaining

withLogConsumer

public ComposeContainer withLogConsumer(java.lang.String serviceName,
                                        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:

serviceName - the name of the service as set in the docker-compose.yml file

consumer - consumer that output frames should be sent to

Returns:

this instance, for chaining

withBuild

public ComposeContainer withBuild(boolean build)

Whether to always build images before starting containers.

Returns:

this instance, for chaining

withOptions

public ComposeContainer withOptions(java.lang.String... options)

Adds options to the docker command, e.g. docker --compatibility.

Returns:

this instance, for chaining

withRemoveImages

public ComposeContainer withRemoveImages(ComposeContainer.RemoveImages removeImages)

Remove images after containers shutdown.

Returns:

this instance, for chaining

withRemoveVolumes

public ComposeContainer withRemoveVolumes(boolean removeVolumes)

Remove volumes after containers shut down.

Parameters:

removeVolumes - whether volumes are to be removed.

Returns:

this instance, for chaining.

withStartupTimeout

public ComposeContainer withStartupTimeout(java.time.Duration startupTimeout)

Set the maximum startup timeout all the waits set are bounded to.

Returns:

this instance. for chaining

getContainerByServiceName

public java.util.Optional<ContainerState> getContainerByServiceName(java.lang.String serviceName)