Skip to content

Latest commit

 

History

History
125 lines (80 loc) · 6.89 KB

startup_and_waits.md

File metadata and controls

125 lines (80 loc) · 6.89 KB

Waiting for containers to start or be ready

!!! info "Wait strategies vs Startup strategies"

**Wait strategy:** is the container in a state that is useful for testing. This is generally approximated as 'can we talk to this container over the network'. However, there are quite a few variations and nuances.

**Startup strategy:** did a container reach the desired running state. *Almost always* this just means 'wait until the container is running' - for a daemon process in a container this is the goal. Sometimes we need to wait until the container reaches a running state and then exits - this is the 'one shot startup' strategy, only used for cases where we need to run a one off command in a container but not a daemon.

Wait Strategies

Ordinarily Testcontainers will wait for up to 60 seconds for the container's first mapped network port to start listening.

This simple measure provides a basic check whether a container is ready for use.

Waiting for the first exposed port to start listening inside_block:waitForNetworkListening

If the default 60s timeout is not sufficient, it can be altered with the withStartupTimeout() method.

If waiting for a listening TCP port is not sufficient to establish whether the container is ready, you can use the waitingFor() method with other [WaitStrategy](http://static.javadoc.io/org.testcontainers/testcontainers/{{ latest_version }}/org/testcontainers/containers/wait/strategy/WaitStrategy.html) implementations as shown below.

HTTP Wait strategy examples

You can choose to wait for an HTTP(S) endpoint to return a particular status code.

Waiting for 200 OK

inside_block:waitForSimpleHttp

Variations on the HTTP wait strategy are supported, including:

Waiting for multiple possible status codes

inside_block:waitForHttpWithMultipleStatusCodes

Waiting for a status code that matches a predicate

Waiting for a status code that matches a predicate inside_block:waitForHttpWithStatusCodePredicate

Using TLS

inside_block:waitForHttpWithTls

Healthcheck Wait strategy examples

If the used image supports Docker's Healthcheck feature, you can directly leverage the healthy state of the container as your wait condition:

inside_block:healthcheckWait

Log output Wait Strategy

In some situations a container's log output is a simple way to determine if it is ready or not. For example, we can wait for a `Ready' message in the container's logs as follows:

inside_block:logMessageWait

Other Wait Strategies

For further options, check out the [Wait](http://static.javadoc.io/org.testcontainers/testcontainers/{{ latest_version }}/org/testcontainers/containers/wait/strategy/Wait.html) convenience class, or the various subclasses of [WaitStrategy](http://static.javadoc.io/org.testcontainers/testcontainers/{{ latest_version }}/org/testcontainers/containers/wait/strategy/WaitStrategy.html).

If none of these options meet your requirements, you can create your own subclass of [AbstractWaitStrategy](http://static.javadoc.io/org.testcontainers/testcontainers/{{ latest_version }}/org/testcontainers/containers/wait/strategy/AbstractWaitStrategy.html) with an appropriate wait mechanism in waitUntilReady(). The GenericContainer.waitingFor() method accepts any valid [WaitStrategy](http://static.javadoc.io/org.testcontainers/testcontainers/{{ latest_version }}/org/testcontainers/containers/wait/strategy/WaitStrategy.html).

Startup check Strategies

Ordinarily Testcontainers will check that the container has reached the running state and has not exited. In order to do that inspect is executed against the container and state parameter is extracted.

All logic is implemented in [StartupCheckStrategy](http://static.javadoc.io/org.testcontainers/testcontainers/{{ latest_version }}/org/testcontainers/containers/startupcheck/StartupCheckStrategy.html) child classes.

Running startup strategy example

This is the strategy used by default. Testcontainers just checks if container is running.

Implemented in [IsRunningStartupCheckStrategy](http://static.javadoc.io/org.testcontainers/testcontainers/{{ latest_version }}/org/testcontainers/containers/startupcheck/IsRunningStartupCheckStrategy.html) class.

One shot startup strategy example

This strategy is intended for use with containers that only run briefly and exit of their own accord. As such, success is deemed to be when the container has stopped with exit code 0.

Using one shot startup strategy inside_block:withOneShotStrategy

Indefinite one shot startup strategy example

Variant of one shot strategy that does not impose a timeout. Intended for situation such as when a long running task forms part of container startup.

It has to be assumed that the container will stop of its own accord, either with a success or failure exit code.

Using indefinite one shot startup strategy inside_block:withIndefiniteOneShotStrategy

Minimum duration startup strategy example

Checks that the container is running and has been running for a defined minimum period of time.

Using minimum duration strategy inside_block:withMinimumDurationStrategy

Other startup strategies

If none of these options meet your requirements, you can create your own subclass of [StartupCheckStrategy](http://static.javadoc.io/org.testcontainers/testcontainers/{{ latest_version }}/org/testcontainers/containers /startupcheck/StartupCheckStrategy.html) with an appropriate startup check mechanism in waitUntilStartupSuccessful(). Or you can leave it as is and just implement the checkStartupState(DockerClient dockerClient, String containerId) if you still want to check state periodically.