TestContainers

This module shall be used as entrypoint to the testcontainers library. It exports all the necessary types and functions for most common use-cases.

Docker images

type ImageTag = Text

A tag to a Docker image.

Since: 0.1.0.0

data Image

Handle to a Docker image.

Since: 0.1.0.0

Instances

Show Image

Defined in TestContainers.Docker

Methods

showsPrec :: Int -> Image -> ShowS

show :: Image -> String

showList :: [Image] -> ShowS

Eq Image

Defined in TestContainers.Docker

Methods

(==) :: Image -> Image -> Bool

(/=) :: Image -> Image -> Bool

imageTag :: Image -> ImageTag

The image tag assigned by Docker. Uniquely identifies an Image within Docker.

Since: 0.1.0.0

Referring to Docker images

data ToImage

A description of how to build an Image.

Since: 0.1.0.0

fromTag :: ImageTag -> ToImage

Get an Image from a tag.

Since: 0.1.0.0

fromBuildContext :: FilePath -> Maybe FilePath -> ToImage

Build the image from a build path and an optional path to the Dockerfile (default is Dockerfile)

Since: 0.1.0.0

build :: ToImage -> TestContainer ToImage

Build the Image referred to by the argument. If the construction of the image is expensive (e.g. a call to fromBuildContext) we don't want to repeatedly build the image. Instead, build can be used to execute the underlying Docker build once and re-use the resulting Image.

Since: 0.1.0.0

docker run parameters

data ContainerRequest

Parameters for a running a Docker container.

Since: 0.1.0.0

containerRequest :: ToImage -> ContainerRequest

Default ContainerRequest. Used as base for every Docker container.

Since: 0.1.0.0

setName :: Text -> ContainerRequest -> ContainerRequest

Deprecated: See setFixedName

Set the name of a Docker container. This is equivalent to invoking docker run with the --name parameter.

Since: 0.1.0.0

setFixedName :: Text -> ContainerRequest -> ContainerRequest

Set the name of a Docker container. This is equivalent to invoking docker run with the --name parameter.

Since: 0.5.0.0

setSuffixedName :: Text -> ContainerRequest -> ContainerRequest

Set the name randomly suffixed of a Docker container. This is equivalent to invoking docker run with the --name parameter.

Since: 0.5.0.0

setRandomName :: ContainerRequest -> ContainerRequest

Set the name randomly given of a Docker container. This is equivalent to omitting the --name parameter calling docker run.

Since: 0.5.0.0

setCmd :: [Text] -> ContainerRequest -> ContainerRequest

The command to execute inside the Docker container. This is the equivalent of passing the command on the docker run invocation.

Since: 0.1.0.0

setVolumeMounts :: [(Text, Text)] -> ContainerRequest -> ContainerRequest

The volume mounts to link to Docker container. This is the equivalent of passing the command on the docker run -v invocation.

setRm :: Bool -> ContainerRequest -> ContainerRequest

Wether to remove the container once exited. This is equivalent to passing --rm to docker run. (default is True).

Since: 0.1.0.0

setEnv :: [(Text, Text)] -> ContainerRequest -> ContainerRequest

Set the environment for the container. This is equivalent to passing --env key=value to docker run.

Since: 0.1.0.0

withNetwork :: Network -> ContainerRequest -> ContainerRequest

Set the network the container will connect to. This is equivalent to passing --network network_name to docker run.

Since: 0.5.0.0

withNetworkAlias :: Text -> ContainerRequest -> ContainerRequest

Set the network alias for this container. This is equivalent to passing --network-alias alias to docker run.

Since: 0.5.0.0

setLink :: [ContainerId] -> ContainerRequest -> ContainerRequest

Set link on the container. This is equivalent to passing --link other_container to docker run.

Since: 0.1.0.0

setExpose :: [Port] -> ContainerRequest -> ContainerRequest

Set exposed ports on the container. This is equivalent to setting --publish $PORT to docker run. Docker assigns a random port for the host port. You will have to use containerIp and containerPort to connect to the published port.

  container <- run $ containerRequest redis & setExpose [ 6379 ]
  let (redisHost, redisPort) = (containerIp container, containerPort container 6379)
  print (redisHost, redisPort)

Since: 0.1.0.0

setWaitingFor :: WaitUntilReady -> ContainerRequest -> ContainerRequest

Set the waiting strategy on the container. Depending on a Docker container it can take some time until the provided service is ready. You will want to use to setWaitingFor to block until the container is ready to use.

Since: 0.1.0.0

withFollowLogs :: LogConsumer -> ContainerRequest -> ContainerRequest

Forwards container logs to the given LogConsumer once ran.

Since: 0.5.0.0

Logs

type LogConsumer = Pipe -> ByteString -> IO ()

An abstraction for forwarding logs.

Since: 0.5.0.0

consoleLogConsumer :: LogConsumer

A simple LogConsumer that writes log lines to stdout and stderr respectively.

Since: 0.5.0.0

docker network parameters

data NetworkRequest

Parameters for creating a new Docker network.

Since: 0.5.0.0

networkRequest :: NetworkRequest

Default parameters for creating a new Docker network.

Since: 0.5.0.0

withDriver :: Text -> NetworkRequest -> NetworkRequest

Driver to manage the Network (default "bridge").

Since: 0.5.0.0

withIpv6 :: NetworkRequest -> NetworkRequest

Enable IPv6 for the Docker network.

Since: 0.5.0.0

Creating networks

data Network

Handle to a Docker network.

Since: 0.5.0.0

type NetworkId = Text

Identifies a network within the Docker runtime. Assigned by docker network create

Since: 0.5.0.0

createNetwork :: NetworkRequest -> TestContainer Network

Creates a new Network from a NetworkRequest.

Since: 0.5.0.0

Port

data Port

Defintion of a Port. Allows for specifying ports using various protocols. Due to the Num and IsString instance allows for convenient Haskell literals.

>>> "80" :: Port
80/tcp

>>> "80/tcp" :: Port
80/tcp

>>> 80 :: Port
80/tcp

>>> "90/udp" :: Port
90/udp

Constructors

Port

Fields

• port :: Int
• protocol :: Text

Instances

IsString Port

A cursed but handy instance supporting literal Ports of them form "8080", "8080/udp", "8080/tcp".

Since: 0.5.0.0

Defined in TestContainers.Docker

Methods

fromString :: String -> Port

Num Port

A cursed but handy instance supporting literal Ports.

Since: 0.5.0.0

Defined in TestContainers.Docker

Methods

(+) :: Port -> Port -> Port

(-) :: Port -> Port -> Port

(*) :: Port -> Port -> Port

negate :: Port -> Port

abs :: Port -> Port

signum :: Port -> Port

fromInteger :: Integer -> Port

Show Port

Defined in TestContainers.Docker

Methods

showsPrec :: Int -> Port -> ShowS

show :: Port -> String

showList :: [Port] -> ShowS

Eq Port

Defined in TestContainers.Docker

Methods

(==) :: Port -> Port -> Bool

(/=) :: Port -> Port -> Bool

Ord Port

Defined in TestContainers.Docker

Methods

compare :: Port -> Port -> Ordering

(<) :: Port -> Port -> Bool

(<=) :: Port -> Port -> Bool

(>) :: Port -> Port -> Bool

(>=) :: Port -> Port -> Bool

max :: Port -> Port -> Port

min :: Port -> Port -> Port

Running Docker containers (docker run)

data Container

Handle to a Docker container.

Since: 0.1.0.0

containerAlias :: Container -> Text

Get the container's network alias. Takes the first alias found.

Since: 0.5.0.0

containerGateway :: Container -> Text

Get the IP address for the container's gateway, i.e. the host. Takes the first gateway address found.

Since: 0.5.0.0

containerIp :: Container -> Text

Looks up the ip address of the container.

Since: 0.1.0.0

containerPort :: Container -> Port -> Int

Looks up an exposed port on the host.

Since: 0.1.0.0

containerAddress :: Container -> Port -> (Text, Int)

Returns the domain and port exposing the given container's port. Differs from containerPort in that containerAddress will return the container's domain and port if the program is running in the same network. Otherwise, containerAddress will use the exposed port on the Docker host.

Since: 0.5.0.0

containerReleaseKey :: Container -> ReleaseKey

Deprecated: Containers are cleaned up with a separate resource reaper. Releasing the container manually is not going to work.

Returns the internal release key used for safely shutting down the container. Use this with care. This function is considered an internal detail.

Since: 0.1.0.0

containerImage :: Container -> Image

Returns the underlying image of the container.

Since: 0.1.0.0

run :: ContainerRequest -> TestContainer Container

Runs a Docker container from an Image and ContainerRequest. A finalizer is registered so that the container is aways stopped when it goes out of scope. This function is essentially docker run.

Since: 0.1.0.0

Inspecting Docker containers

type InspectOutput = Value

The parsed JSON output of docker inspect command.

Since: 0.1.0.0

inspect :: Container -> TestContainer InspectOutput

Runs the `docker inspect` command. Memoizes the result.

Since: 0.1.0.0

Docker container lifecycle

stop :: Container -> TestContainer ()

Stops a Docker container. stop is essentially docker stop.

Since: 0.1.0.0

kill :: Container -> TestContainer ()

Kills a Docker container. kill is essentially docker kill.

Since: 0.1.0.0

rm :: Container -> TestContainer ()

Remove a Docker container. rm is essentially docker rm -f

Since: 0.1.0.0

withLogs :: Container -> (Handle -> Handle -> TestContainer a) -> TestContainer a

Access STDOUT and STDERR of a running Docker container. This is essentially docker logs under the hood.

Since: 0.1.0.0

Readiness checks

data WaitUntilReady

A strategy that describes how to asses readiness of a Container. Allows Users to plug in their definition of readiness.

Since: 0.1.0.0

Instances

Monoid WaitUntilReady

Since: 0.5.0.0

Defined in TestContainers.Docker

Methods

mempty :: WaitUntilReady

mappend :: WaitUntilReady -> WaitUntilReady -> WaitUntilReady

mconcat :: [WaitUntilReady] -> WaitUntilReady

Semigroup WaitUntilReady

Since: 0.5.0.0

Defined in TestContainers.Docker

Methods

(<>) :: WaitUntilReady -> WaitUntilReady -> WaitUntilReady

sconcat :: NonEmpty WaitUntilReady -> WaitUntilReady

stimes :: Integral b => b -> WaitUntilReady -> WaitUntilReady

Timeout for readiness checks

waitUntilTimeout :: Int -> WaitUntilReady -> WaitUntilReady

waitUntilTimeout n waitUntilReady waits n seconds for the container to be ready. If the container is not ready by then a TimeoutException will be thrown.

Since: 0.1.0.0

Wait for container exit

data State

State of a Docker container.

Since: 0.5.0.0

data Status

Status of a Docker container.

Since: 0.5.0.0

Constructors

Created

Running

Paused

Restarting

Removing

Exited

Dead

Other Text

Instances

Show Status

Defined in TestContainers.Docker.State

Methods

showsPrec :: Int -> Status -> ShowS

show :: Status -> String

showList :: [Status] -> ShowS

Eq Status

Defined in TestContainers.Docker.State

Methods

(==) :: Status -> Status -> Bool

(/=) :: Status -> Status -> Bool

stateError :: State -> Maybe Text

Since: 0.5.0.0

stateExitCode :: State -> Maybe Int

Since: 0.5.0.0

stateFinishedAt :: State -> Maybe Text

Since: 0.5.0.0

stateOOMKilled :: State -> Bool

Whether a container was killed by the OOM killer.

Since: 0.5.0.0

statePid :: State -> Maybe Int

Since: 0.5.0.0

stateStartedAt :: State -> Maybe Text

Since: 0.5.0.0

stateStatus :: State -> Status

Returns the Status of container.

Since: 0.5.0.0

waitForState :: (State -> Bool) -> WaitUntilReady

waitForState waits for a certain state of the container. If the container reaches a terminal state InvalidStateException will be thrown.

Since: 0.5.0.0

Predicates to assert container state

successfulExit :: State -> Bool

successfulExit is supposed to be used in conjunction with waitForState.

Since: 0.5.0.0

Waiting on particular log lines

data Pipe

A data type indicating which pipe to scan for a specific log line.

Since: 0.1.0.0

Constructors

Stdout

Refer to logs on STDOUT.

Stderr

Refer to logs on STDERR.

Instances

Show Pipe

Defined in TestContainers.Docker.Internal

Methods

showsPrec :: Int -> Pipe -> ShowS

show :: Pipe -> String

showList :: [Pipe] -> ShowS

Eq Pipe

Defined in TestContainers.Docker.Internal

Methods

(==) :: Pipe -> Pipe -> Bool

(/=) :: Pipe -> Pipe -> Bool

Ord Pipe

Defined in TestContainers.Docker.Internal

Methods

compare :: Pipe -> Pipe -> Ordering

(<) :: Pipe -> Pipe -> Bool

(<=) :: Pipe -> Pipe -> Bool

(>) :: Pipe -> Pipe -> Bool

(>=) :: Pipe -> Pipe -> Bool

max :: Pipe -> Pipe -> Pipe

min :: Pipe -> Pipe -> Pipe

waitWithLogs :: (Container -> Handle -> Handle -> IO ()) -> WaitUntilReady

A low-level primitive that allows scanning the logs for specific log lines that indicate readiness of a container.

The Handles passed to the function argument represent stdout and stderr of the container.

Since: 0.1.0.0

waitForLogLine :: Pipe -> (Text -> Bool) -> WaitUntilReady

Waits for a specific line to occur in the logs. Throws a UnexpectedEndOfPipe exception in case the desired line can not be found on the logs.

Say you want to find "Ready to accept connections" in the logs on Stdout try:

waitForLogLine Stdout ("Ready to accept connections" `isInfixOf`)

Since: 0.1.0.0

Wait until connection can be established

waitUntilMappedPortReachable :: Port -> WaitUntilReady

Waits until the port of a container is ready to accept connections. This combinator should always be used with waitUntilTimeout.

Since: 0.1.0.0

Wait until the http server responds with a specific status code

waitForHttp

Arguments

:: Port

Port

-> String

URL path

-> [Int]

Acceptable status codes

-> WaitUntilReady

Waits for a specific http status code. This combinator should always be used with waitUntilTimeout.

Since: 0.5.0.0

Monad

type MonadDocker m = m ~ TestContainer

Docker related functionality is parameterized over this Monad. Since 0.5.0.0 this is just a type alias for m ~ TestContainer.

Since: 0.1.0.0

data TestContainer a

The heart and soul of the testcontainers library.

Since: 0.5.0.0

Instances

MonadFix TestContainer

Defined in TestContainers.Monad

Methods

mfix :: (a -> TestContainer a) -> TestContainer a

MonadIO TestContainer

Defined in TestContainers.Monad

Methods

liftIO :: IO a -> TestContainer a

Applicative TestContainer

Defined in TestContainers.Monad

Methods

pure :: a -> TestContainer a

(<*>) :: TestContainer (a -> b) -> TestContainer a -> TestContainer b

liftA2 :: (a -> b -> c) -> TestContainer a -> TestContainer b -> TestContainer c

(*>) :: TestContainer a -> TestContainer b -> TestContainer b

(<*) :: TestContainer a -> TestContainer b -> TestContainer a

Functor TestContainer

Defined in TestContainers.Monad

Methods

fmap :: (a -> b) -> TestContainer a -> TestContainer b

(<$) :: a -> TestContainer b -> TestContainer a

Monad TestContainer

Defined in TestContainers.Monad

Methods

(>>=) :: TestContainer a -> (a -> TestContainer b) -> TestContainer b

(>>) :: TestContainer a -> TestContainer b -> TestContainer b

return :: a -> TestContainer a

MonadCatch TestContainer

Defined in TestContainers.Monad

Methods

catch :: Exception e => TestContainer a -> (e -> TestContainer a) -> TestContainer a

MonadMask TestContainer

Defined in TestContainers.Monad

Methods

mask :: ((forall a. TestContainer a -> TestContainer a) -> TestContainer b) -> TestContainer b

uninterruptibleMask :: ((forall a. TestContainer a -> TestContainer a) -> TestContainer b) -> TestContainer b

generalBracket :: TestContainer a -> (a -> ExitCase b -> TestContainer c) -> (a -> TestContainer b) -> TestContainer (b, c)

MonadThrow TestContainer

Defined in TestContainers.Monad

Methods

throwM :: Exception e => e -> TestContainer a

MonadResource TestContainer

Defined in TestContainers.Monad

Methods

liftResourceT :: ResourceT IO a -> TestContainer a

MonadUnliftIO TestContainer

Defined in TestContainers.Monad

Methods

withRunInIO :: ((forall a. TestContainer a -> IO a) -> IO b) -> TestContainer b

MonadReader Config TestContainer

Defined in TestContainers.Monad

Methods

ask :: TestContainer Config

local :: (Config -> Config) -> TestContainer a -> TestContainer a

reader :: (Config -> a) -> TestContainer a

Monoid a => Monoid (TestContainer a)

Defined in TestContainers.Monad

Methods

mempty :: TestContainer a

mappend :: TestContainer a -> TestContainer a -> TestContainer a

mconcat :: [TestContainer a] -> TestContainer a

Semigroup a => Semigroup (TestContainer a)

Defined in TestContainers.Monad

Methods

(<>) :: TestContainer a -> TestContainer a -> TestContainer a

sconcat :: NonEmpty (TestContainer a) -> TestContainer a

stimes :: Integral b => b -> TestContainer a -> TestContainer a

Configuration

data Config

Configuration for defaulting behavior.

Since: 0.2.0.0

Constructors

Config

Fields

• configDefaultWaitTimeout :: Maybe Int

  The number of seconds to maximally wait for a container to become ready. Default is `Just 60`.

  Nothing = waits indefinitely.

• configTracer :: Tracer

  Traces execution inside testcontainers library.

• configCreateReaper :: TestContainer Reaper

  How to obtain a Reaper

Instances

MonadReader Config TestContainer

Defined in TestContainers.Monad

Methods

ask :: TestContainer Config

local :: (Config -> Config) -> TestContainer a -> TestContainer a

reader :: (Config -> a) -> TestContainer a

defaultDockerConfig :: Config

Default configuration.

Since: 0.2.0.0

determineConfig :: IO Config

Autoselect the default configuration depending on wether you use Docker For Mac or not.

data Tracer

Traces execution within testcontainers library.

Instances

Monoid Tracer

Defined in TestContainers.Trace

Methods

mempty :: Tracer

mappend :: Tracer -> Tracer -> Tracer

mconcat :: [Tracer] -> Tracer

Semigroup Tracer

Defined in TestContainers.Trace

Methods

(<>) :: Tracer -> Tracer -> Tracer

sconcat :: NonEmpty Tracer -> Tracer

stimes :: Integral b => b -> Tracer -> Tracer

data Trace

Type representing various events during testcontainer execution.

Constructors

TraceDockerInvocation [Text] Text ExitCode

The low-level invocation of docker command

  TraceDockerInvocation args stdin exitcode

TraceDockerFollowLogs [Text]

Preparations to follow the logs for a certain container

TraceDockerStdout Text

Line written to STDOUT by a Docker process.

TraceDockerStderr Text

Line written to STDERR by a Docker process.

TraceWaitUntilReady (Maybe Int)

Waiting for a container to become ready. Attached with the timeout to wait (in seconds).

TraceOpenSocket Text Int (Maybe IOException)

Opening socket

TraceHttpCall Text Int (Either String Int)

Call HTTP endpoint

Instances

Show Trace

Defined in TestContainers.Trace

Methods

showsPrec :: Int -> Trace -> ShowS

show :: Trace -> String

showList :: [Trace] -> ShowS

Eq Trace

Defined in TestContainers.Trace

Methods

(==) :: Trace -> Trace -> Bool

(/=) :: Trace -> Trace -> Bool

newTracer :: (Trace -> IO ()) -> Tracer

Construct a new Tracer from a tracing function.

Exceptions

data DockerException

Failing to interact with Docker results in this exception being thrown.

Since: 0.1.0.0

Constructors

DockerException

Fields

• exitCode :: ExitCode

  Exit code of the underlying Docker process.

• args :: [Text]

  Arguments that were passed to Docker.

• stderr :: Text

  Docker's STDERR output.

InspectUnknownContainerId

Fields

• id :: ContainerId

  Id of the Container that we tried to lookup the port mapping.

InspectOutputInvalidJSON

Fields

• id :: ContainerId

  Id of the Container that we tried to lookup the port mapping.

InspectOutputMissingNetwork

Fields

• id :: ContainerId

  Id of the Container that we tried to lookup the port mapping.

InspectOutputUnexpected

Fields

• id :: ContainerId

  Id of the Container that we tried to lookup the port mapping.

UnknownPortMapping

Fields

• id :: ContainerId

  Id of the Container that we tried to lookup the port mapping.

• port :: Text

  Textual representation of port mapping we were trying to look up.

Instances

Exception DockerException

Defined in TestContainers.Docker.Internal

Methods

toException :: DockerException -> SomeException

fromException :: SomeException -> Maybe DockerException

displayException :: DockerException -> String

Show DockerException

Defined in TestContainers.Docker.Internal

Methods

showsPrec :: Int -> DockerException -> ShowS

show :: DockerException -> String

showList :: [DockerException] -> ShowS

Eq DockerException

Defined in TestContainers.Docker.Internal

Methods

(==) :: DockerException -> DockerException -> Bool

(/=) :: DockerException -> DockerException -> Bool

newtype TimeoutException

The exception thrown by waitUntilTimeout.

Since: 0.1.0.0

Constructors

TimeoutException

Fields

• id :: ContainerId

  The id of the underlying container that was not ready in time.

Instances

Exception TimeoutException

Defined in TestContainers.Docker

Methods

toException :: TimeoutException -> SomeException

fromException :: SomeException -> Maybe TimeoutException

displayException :: TimeoutException -> String

Show TimeoutException

Defined in TestContainers.Docker

Methods

showsPrec :: Int -> TimeoutException -> ShowS

show :: TimeoutException -> String

showList :: [TimeoutException] -> ShowS

Eq TimeoutException

Defined in TestContainers.Docker

Methods

(==) :: TimeoutException -> TimeoutException -> Bool

(/=) :: TimeoutException -> TimeoutException -> Bool

newtype UnexpectedEndOfPipe

The exception thrown by waitForLine in case the expected log line wasn't found.

Since: 0.1.0.0

Constructors

UnexpectedEndOfPipe

Fields

• id :: ContainerId

  The id of the underlying container.

Instances

Exception UnexpectedEndOfPipe

Defined in TestContainers.Docker

Methods

toException :: UnexpectedEndOfPipe -> SomeException

fromException :: SomeException -> Maybe UnexpectedEndOfPipe

displayException :: UnexpectedEndOfPipe -> String

Show UnexpectedEndOfPipe

Defined in TestContainers.Docker

Methods

showsPrec :: Int -> UnexpectedEndOfPipe -> ShowS

show :: UnexpectedEndOfPipe -> String

showList :: [UnexpectedEndOfPipe] -> ShowS

Eq UnexpectedEndOfPipe

Defined in TestContainers.Docker

Methods

(==) :: UnexpectedEndOfPipe -> UnexpectedEndOfPipe -> Bool

(/=) :: UnexpectedEndOfPipe -> UnexpectedEndOfPipe -> Bool

Misc. Docker functions

dockerHostOs :: TestContainer Text

isDockerOnLinux :: TestContainer Bool

Predefined Docker images

redis :: ToImage

Image for Redis database.

redis = fromTag "redis:5.0"

Since: 0.1.0.0

mongo :: ToImage

Image for Mongo database.

mongo = Tag "mongo:4.0.17"

Since: 0.1.0.0

Reexports

type ResIO = ResourceT IO

Convenient alias for ResourceT IO.

runResourceT :: MonadUnliftIO m => ResourceT m a -> m a

Unwrap a ResourceT transformer, and call all registered release actions.

Note that there is some reference counting involved due to resourceForkIO. If multiple threads are sharing the same collection of resources, only the last call to runResourceT will deallocate the resources.

NOTE Since version 1.2.0, this function will throw a ResourceCleanupException if any of the cleanup functions throw an exception.

Since: resourcet-0.3.0

(&) :: a -> (a -> b) -> b infixl 1

& is a reverse application operator. This provides notational convenience. Its precedence is one higher than that of the forward application operator $, which allows & to be nested in $.

>>> 5 & (+1) & show
"6"

Since: base-4.8.0.0