-- Hoogle documentation, generated by Haddock
-- See Hoogle, http://www.haskell.org/hoogle/
-- | Docker containers for your integration tests.
--
-- testcontainers is a Haskell library that provides a friendly API to
-- run Docker containers. It is designed to create a runtime environment
-- to use during your integration tests
@package testcontainers
@version 0.3.0.1
module TestContainers.Docker
-- | Docker related functionality is parameterized over this Monad.
type MonadDocker m = (MonadIO m, MonadMask m, MonadThrow m, MonadCatch m, MonadResource m, MonadReader Config m)
-- | Configuration for defaulting behavior.
data Config
Config :: Maybe Int -> Tracer -> Config
-- | The number of seconds to maximally wait for a container to become
-- ready. Default is `Just 60`.
--
-- Nothing = waits indefinitely.
[$sel:configDefaultWaitTimeout:Config] :: Config -> Maybe Int
-- | Traces execution inside testcontainers library.
[$sel:configTracer:Config] :: Config -> Tracer
-- | Default configuration.
defaultDockerConfig :: Config
-- | Autoselect the default configuration depending on wether you use
-- Docker For Mac or not.
determineConfig :: IO Config
-- | Traces execution within testcontainers library.
data Tracer
-- | Type representing various events during testcontainer execution.
data Trace
-- | The low-level invocation of docker command
--
--
-- TraceDockerInvocation args stdin exitcode
--
TraceDockerInvocation :: [Text] -> Text -> ExitCode -> Trace
-- | Line written to STDOUT by a Docker process.
TraceDockerStdout :: Text -> Trace
-- | Line written to STDERR by a Docker process.
TraceDockerStderr :: Text -> Trace
-- | Waiting for a container to become ready. Attached with the timeout to
-- wait (in seconds).
TraceWaitUntilReady :: Maybe Int -> Trace
-- | Opening socket
TraceOpenSocket :: Text -> Int -> Maybe IOException -> Trace
-- | Construct a new Tracer from a tracing function.
newTracer :: (Trace -> IO ()) -> Tracer
withTrace :: MonadIO m => Tracer -> Trace -> m ()
-- | A tag to a Docker image.
type ImageTag = Text
-- | Handle to a Docker image.
data Image
-- | The image tag assigned by Docker. Uniquely identifies an Image
-- within Docker.
imageTag :: Image -> ImageTag
-- | Identifies a container within the Docker runtime. Assigned by
-- docker run.
type ContainerId = Text
-- | Handle to a Docker container.
data Container
-- | Returns the id of the container.
containerId :: Container -> ContainerId
-- | Returns the underlying image of the container.
containerImage :: Container -> Image
-- | Looks up the ip address of the container.
containerIp :: Container -> Text
-- | Looks up an exposed port on the host.
containerPort :: Container -> Int -> Int
-- | Returns the internal release key used for safely shutting down the
-- container. Use this with care. This function is considered an internal
-- detail.
containerReleaseKey :: Container -> ReleaseKey
-- | A description of how to build an Image.
data ToImage
-- | Get an Image from a tag.
fromTag :: ImageTag -> ToImage
-- | Build the image from a build path and an optional path to the
-- Dockerfile (default is Dockerfile)
fromBuildContext :: FilePath -> Maybe FilePath -> ToImage
-- | Build a contextless image only from a Dockerfile passed as
-- Text.
fromDockerfile :: Text -> 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.
build :: MonadDocker m => ToImage -> m ToImage
-- | Failing to interact with Docker results in this exception being
-- thrown.
data DockerException
DockerException :: ExitCode -> [Text] -> Text -> DockerException
-- | Exit code of the underlying Docker process.
[$sel:exitCode:DockerException] :: DockerException -> ExitCode
-- | Arguments that were passed to Docker.
[$sel:args:DockerException] :: DockerException -> [Text]
-- | Docker's STDERR output.
[$sel:stderr:DockerException] :: DockerException -> Text
InspectUnknownContainerId :: ContainerId -> DockerException
-- | Id of the Container that we tried to lookup the port mapping.
[$sel:id:DockerException] :: DockerException -> ContainerId
InspectOutputInvalidJSON :: ContainerId -> DockerException
-- | Id of the Container that we tried to lookup the port mapping.
[$sel:id:DockerException] :: DockerException -> ContainerId
InspectOutputUnexpected :: ContainerId -> DockerException
-- | Id of the Container that we tried to lookup the port mapping.
[$sel:id:DockerException] :: DockerException -> ContainerId
UnknownPortMapping :: ContainerId -> Text -> DockerException
-- | Id of the Container that we tried to lookup the port mapping.
[$sel:id:DockerException] :: DockerException -> ContainerId
-- | Textual representation of port mapping we were trying to look up.
[$sel:port:DockerException] :: DockerException -> Text
-- | Parameters for a running a Docker container.
data ContainerRequest
-- | Default ContainerRequest. Used as base for every Docker
-- container.
containerRequest :: ToImage -> ContainerRequest
-- | Set the name of a Docker container. This is equivalent to invoking
-- docker run with the --name parameter.
setName :: Text -> ContainerRequest -> ContainerRequest
-- | The command to execute inside the Docker container. This is the
-- equivalent of passing the command on the docker run
-- invocation.
setCmd :: [Text] -> ContainerRequest -> ContainerRequest
-- | Wether to remove the container once exited. This is equivalent to
-- passing --rm to docker run. (default is
-- True).
setRm :: Bool -> ContainerRequest -> ContainerRequest
-- | Set the environment for the container. This is equivalent to passing
-- --env key=value to docker run.
setEnv :: [(Text, Text)] -> ContainerRequest -> ContainerRequest
-- | Set link on the container. This is equivalent to passing --link
-- other_container to docker run.
setLink :: [ContainerId] -> 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)
--
setExpose :: [Int] -> 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.
setWaitingFor :: WaitUntilReady -> ContainerRequest -> ContainerRequest
-- | 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.
run :: MonadDocker m => ContainerRequest -> m Container
-- | The parsed JSON output of docker inspect command.
type InspectOutput = Value
-- | Runs the `docker inspect` command. Memoizes the result.
inspect :: MonadDocker m => Container -> m InspectOutput
-- | Stops a Docker container. stop is essentially docker
-- stop.
stop :: MonadDocker m => Container -> m ()
-- | Kills a Docker container. kill is essentially docker
-- kill.
kill :: MonadDocker m => Container -> m ()
-- | Remove a Docker container. rm is essentially docker rm
-- -f
rm :: MonadDocker m => Container -> m ()
-- | Access STDOUT and STDERR of a running Docker container. This is
-- essentially docker logs under the hood.
withLogs :: forall m a. MonadDocker m => Container -> (Handle -> Handle -> m a) -> m a
-- | A strategy that describes how to asses readiness of a
-- Container. Allows Users to plug in their definition of
-- readiness.
data WaitUntilReady
-- | Blocks until the container is ready. waitUntilReady might throw
-- exceptions depending on the used WaitUntilReady on the
-- container.
waitUntilReady :: MonadDocker m => Container -> WaitUntilReady -> m ()
-- | The exception thrown by waitUntilTimeout.
newtype TimeoutException
TimeoutException :: ContainerId -> TimeoutException
-- | The id of the underlying container that was not ready in time.
[$sel:id:TimeoutException] :: TimeoutException -> ContainerId
-- | 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.
waitUntilTimeout :: Int -> WaitUntilReady -> 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.
waitWithLogs :: (Container -> Handle -> Handle -> IO ()) -> WaitUntilReady
-- | The exception thrown by waitForLine in case the expected log
-- line wasn't found.
newtype UnexpectedEndOfPipe
UnexpectedEndOfPipe :: ContainerId -> UnexpectedEndOfPipe
-- | The id of the underlying container.
[$sel:id:UnexpectedEndOfPipe] :: UnexpectedEndOfPipe -> ContainerId
-- | A data type indicating which pipe to scan for a specific log line.
data Pipe
-- | Refer to logs on STDOUT.
Stdout :: Pipe
-- | Refer to logs on STDERR.
Stderr :: Pipe
-- | 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`)
--
waitForLogLine :: Pipe -> (Text -> Bool) -> WaitUntilReady
dockerHostOs :: MonadDocker m => m Text
isDockerOnLinux :: MonadDocker m => m Bool
-- | Waits until the port of a container is ready to accept connections.
-- This combinator should always be used with waitUntilTimeout.
waitUntilMappedPortReachable :: Int -> WaitUntilReady
-- | Convenient alias for ResourceT IO.
type ResIO = ResourceT IO
-- | 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.
runResourceT :: MonadUnliftIO m => ResourceT m a -> m a
-- | & 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"
--
(&) :: a -> (a -> b) -> b
infixl 1 &
instance GHC.Show.Show TestContainers.Docker.DockerException
instance GHC.Classes.Eq TestContainers.Docker.DockerException
instance GHC.Show.Show TestContainers.Docker.UnexpectedEndOfPipe
instance GHC.Classes.Eq TestContainers.Docker.UnexpectedEndOfPipe
instance GHC.Show.Show TestContainers.Docker.TimeoutException
instance GHC.Classes.Eq TestContainers.Docker.TimeoutException
instance GHC.Show.Show TestContainers.Docker.Pipe
instance GHC.Classes.Ord TestContainers.Docker.Pipe
instance GHC.Classes.Eq TestContainers.Docker.Pipe
instance GHC.Show.Show TestContainers.Docker.Image
instance GHC.Classes.Eq TestContainers.Docker.Image
instance GHC.Classes.Eq TestContainers.Docker.Trace
instance GHC.Show.Show TestContainers.Docker.Trace
instance GHC.Base.Semigroup TestContainers.Docker.Tracer
instance GHC.Base.Monoid TestContainers.Docker.Tracer
instance GHC.Exception.Type.Exception TestContainers.Docker.TimeoutException
instance GHC.Exception.Type.Exception TestContainers.Docker.UnexpectedEndOfPipe
instance GHC.Exception.Type.Exception TestContainers.Docker.DockerException
module TestContainers.Image
-- | Image for Redis database.
--
--
-- redis = fromTag "redis:5.0"
--
redis :: ToImage
-- | Image for Mongo database.
--
--
-- mongo = Tag "mongo:4.0.17"
--
mongo :: ToImage
-- | Handle to a Docker image.
data Image
-- | A description of how to build an Image.
data 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.
build :: MonadDocker m => ToImage -> m ToImage
-- | Get an Image from a tag.
fromTag :: ImageTag -> ToImage
-- | Build the image from a build path and an optional path to the
-- Dockerfile (default is Dockerfile)
fromBuildContext :: FilePath -> Maybe FilePath -> ToImage
-- | Build a contextless image only from a Dockerfile passed as
-- Text.
fromDockerfile :: Text -> ToImage
-- | This module shall be used as entrypoint to the testcontainers library.
-- It exports all the necessary types and functions for most common
-- use-cases.
module TestContainers
-- | A tag to a Docker image.
type ImageTag = Text
-- | Handle to a Docker image.
data Image
-- | The image tag assigned by Docker. Uniquely identifies an Image
-- within Docker.
imageTag :: Image -> ImageTag
-- | A description of how to build an Image.
data ToImage
-- | Get an Image from a tag.
fromTag :: ImageTag -> ToImage
-- | Build the image from a build path and an optional path to the
-- Dockerfile (default is Dockerfile)
fromBuildContext :: FilePath -> Maybe FilePath -> 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.
build :: MonadDocker m => ToImage -> m ToImage
-- | Parameters for a running a Docker container.
data ContainerRequest
-- | Default ContainerRequest. Used as base for every Docker
-- container.
containerRequest :: ToImage -> ContainerRequest
-- | Set the name of a Docker container. This is equivalent to invoking
-- docker run with the --name parameter.
setName :: Text -> ContainerRequest -> ContainerRequest
-- | The command to execute inside the Docker container. This is the
-- equivalent of passing the command on the docker run
-- invocation.
setCmd :: [Text] -> ContainerRequest -> ContainerRequest
-- | Wether to remove the container once exited. This is equivalent to
-- passing --rm to docker run. (default is
-- True).
setRm :: Bool -> ContainerRequest -> ContainerRequest
-- | Set the environment for the container. This is equivalent to passing
-- --env key=value to docker run.
setEnv :: [(Text, Text)] -> ContainerRequest -> ContainerRequest
-- | Set link on the container. This is equivalent to passing --link
-- other_container to docker run.
setLink :: [ContainerId] -> 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)
--
setExpose :: [Int] -> 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.
setWaitingFor :: WaitUntilReady -> ContainerRequest -> ContainerRequest
-- | Handle to a Docker container.
data Container
-- | Looks up the ip address of the container.
containerIp :: Container -> Text
-- | Looks up an exposed port on the host.
containerPort :: Container -> Int -> Int
-- | Returns the internal release key used for safely shutting down the
-- container. Use this with care. This function is considered an internal
-- detail.
containerReleaseKey :: Container -> ReleaseKey
-- | Returns the underlying image of the container.
containerImage :: Container -> Image
-- | 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.
run :: MonadDocker m => ContainerRequest -> m Container
-- | The parsed JSON output of docker inspect command.
type InspectOutput = Value
-- | Runs the `docker inspect` command. Memoizes the result.
inspect :: MonadDocker m => Container -> m InspectOutput
-- | Stops a Docker container. stop is essentially docker
-- stop.
stop :: MonadDocker m => Container -> m ()
-- | Kills a Docker container. kill is essentially docker
-- kill.
kill :: MonadDocker m => Container -> m ()
-- | Remove a Docker container. rm is essentially docker rm
-- -f
rm :: MonadDocker m => Container -> m ()
-- | Access STDOUT and STDERR of a running Docker container. This is
-- essentially docker logs under the hood.
withLogs :: forall m a. MonadDocker m => Container -> (Handle -> Handle -> m a) -> m a
-- | A strategy that describes how to asses readiness of a
-- Container. Allows Users to plug in their definition of
-- readiness.
data 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.
waitUntilTimeout :: Int -> WaitUntilReady -> WaitUntilReady
-- | A data type indicating which pipe to scan for a specific log line.
data Pipe
-- | Refer to logs on STDOUT.
Stdout :: Pipe
-- | Refer to logs on STDERR.
Stderr :: Pipe
-- | 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.
waitWithLogs :: (Container -> Handle -> Handle -> IO ()) -> 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`)
--
waitForLogLine :: Pipe -> (Text -> Bool) -> WaitUntilReady
-- | Waits until the port of a container is ready to accept connections.
-- This combinator should always be used with waitUntilTimeout.
waitUntilMappedPortReachable :: Int -> WaitUntilReady
-- | Docker related functionality is parameterized over this Monad.
type MonadDocker m = (MonadIO m, MonadMask m, MonadThrow m, MonadCatch m, MonadResource m, MonadReader Config m)
-- | Configuration for defaulting behavior.
data Config
Config :: Maybe Int -> Tracer -> Config
-- | The number of seconds to maximally wait for a container to become
-- ready. Default is `Just 60`.
--
-- Nothing = waits indefinitely.
[$sel:configDefaultWaitTimeout:Config] :: Config -> Maybe Int
-- | Traces execution inside testcontainers library.
[$sel:configTracer:Config] :: Config -> Tracer
-- | Default configuration.
defaultDockerConfig :: Config
-- | Autoselect the default configuration depending on wether you use
-- Docker For Mac or not.
determineConfig :: IO Config
-- | Traces execution within testcontainers library.
data Tracer
-- | Type representing various events during testcontainer execution.
data Trace
-- | The low-level invocation of docker command
--
--
-- TraceDockerInvocation args stdin exitcode
--
TraceDockerInvocation :: [Text] -> Text -> ExitCode -> Trace
-- | Line written to STDOUT by a Docker process.
TraceDockerStdout :: Text -> Trace
-- | Line written to STDERR by a Docker process.
TraceDockerStderr :: Text -> Trace
-- | Waiting for a container to become ready. Attached with the timeout to
-- wait (in seconds).
TraceWaitUntilReady :: Maybe Int -> Trace
-- | Opening socket
TraceOpenSocket :: Text -> Int -> Maybe IOException -> Trace
-- | Construct a new Tracer from a tracing function.
newTracer :: (Trace -> IO ()) -> Tracer
-- | Failing to interact with Docker results in this exception being
-- thrown.
data DockerException
DockerException :: ExitCode -> [Text] -> Text -> DockerException
-- | Exit code of the underlying Docker process.
[$sel:exitCode:DockerException] :: DockerException -> ExitCode
-- | Arguments that were passed to Docker.
[$sel:args:DockerException] :: DockerException -> [Text]
-- | Docker's STDERR output.
[$sel:stderr:DockerException] :: DockerException -> Text
InspectUnknownContainerId :: ContainerId -> DockerException
-- | Id of the Container that we tried to lookup the port mapping.
[$sel:id:DockerException] :: DockerException -> ContainerId
InspectOutputInvalidJSON :: ContainerId -> DockerException
-- | Id of the Container that we tried to lookup the port mapping.
[$sel:id:DockerException] :: DockerException -> ContainerId
InspectOutputUnexpected :: ContainerId -> DockerException
-- | Id of the Container that we tried to lookup the port mapping.
[$sel:id:DockerException] :: DockerException -> ContainerId
UnknownPortMapping :: ContainerId -> Text -> DockerException
-- | Id of the Container that we tried to lookup the port mapping.
[$sel:id:DockerException] :: DockerException -> ContainerId
-- | Textual representation of port mapping we were trying to look up.
[$sel:port:DockerException] :: DockerException -> Text
-- | The exception thrown by waitUntilTimeout.
newtype TimeoutException
TimeoutException :: ContainerId -> TimeoutException
-- | The id of the underlying container that was not ready in time.
[$sel:id:TimeoutException] :: TimeoutException -> ContainerId
-- | The exception thrown by waitForLine in case the expected log
-- line wasn't found.
newtype UnexpectedEndOfPipe
UnexpectedEndOfPipe :: ContainerId -> UnexpectedEndOfPipe
-- | The id of the underlying container.
[$sel:id:UnexpectedEndOfPipe] :: UnexpectedEndOfPipe -> ContainerId
dockerHostOs :: MonadDocker m => m Text
isDockerOnLinux :: MonadDocker m => m Bool
-- | Image for Redis database.
--
--
-- redis = fromTag "redis:5.0"
--
redis :: ToImage
-- | Image for Mongo database.
--
--
-- mongo = Tag "mongo:4.0.17"
--
mongo :: ToImage
-- | Convenient alias for ResourceT IO.
type ResIO = ResourceT IO
-- | 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.
runResourceT :: MonadUnliftIO m => ResourceT m a -> m a
-- | & 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"
--
(&) :: a -> (a -> b) -> b
infixl 1 &
module TestContainers.Hspec
-- | Allow Spec to depend on Docker containers. Hspec takes care of
-- initialization and de-initialization of the containers.
--
--
-- containers :: MonadDocker m => m Boolean
-- containers = do
-- _redis <- TestContainers.run $ TestContainers.containerRequest TestContainers.redis
-- _kafka <- TestContainers.run $ TestContainers.containerRequest TestContainers.kafka
-- pure True
--
-- example :: Spec
-- example =
-- around (withContainers containers) $ describe "Example tests"
-- it "first test" $ \isBoolean -> do
-- isBoolean shouldBe True
--
--
-- withContainers allows you naturally scope the handling of
-- containers for your tests.
withContainers :: forall a. (forall m. MonadDocker m => m a) -> (a -> IO ()) -> IO ()
module TestContainers.Tasty
-- | Tasty Ingredient that adds useful options to control defaults
-- within the TetContainers library.
--
--
-- main :: IO ()
-- main = defaultMainWithIngredients (ingredient : defaultIngredients) tests
--
ingredient :: Ingredient
withContainers :: forall a. (forall m. MonadDocker m => m a) -> (IO a -> TestTree) -> TestTree
-- | & 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"
--
(&) :: a -> (a -> b) -> b
infixl 1 &
-- | 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.
runResourceT :: MonadUnliftIO m => ResourceT m a -> m a
-- | Convenient alias for ResourceT IO.
type ResIO = ResourceT IO
-- | The parsed JSON output of docker inspect command.
type InspectOutput = Value
-- | Handle to a Docker container.
data Container
-- | Handle to a Docker image.
data Image
-- | A data type indicating which pipe to scan for a specific log line.
data Pipe
-- | Refer to logs on STDOUT.
Stdout :: Pipe
-- | Refer to logs on STDERR.
Stderr :: Pipe
-- | The exception thrown by waitUntilTimeout.
newtype TimeoutException
TimeoutException :: ContainerId -> TimeoutException
-- | The id of the underlying container that was not ready in time.
[$sel:id:TimeoutException] :: TimeoutException -> ContainerId
-- | The exception thrown by waitForLine in case the expected log
-- line wasn't found.
newtype UnexpectedEndOfPipe
UnexpectedEndOfPipe :: ContainerId -> UnexpectedEndOfPipe
-- | The id of the underlying container.
[$sel:id:UnexpectedEndOfPipe] :: UnexpectedEndOfPipe -> ContainerId
-- | A strategy that describes how to asses readiness of a
-- Container. Allows Users to plug in their definition of
-- readiness.
data WaitUntilReady
-- | A description of how to build an Image.
data ToImage
-- | A tag to a Docker image.
type ImageTag = Text
-- | Parameters for a running a Docker container.
data ContainerRequest
-- | Docker related functionality is parameterized over this Monad.
type MonadDocker m = (MonadIO m, MonadMask m, MonadThrow m, MonadCatch m, MonadResource m, MonadReader Config m)
-- | Failing to interact with Docker results in this exception being
-- thrown.
data DockerException
DockerException :: ExitCode -> [Text] -> Text -> DockerException
-- | Exit code of the underlying Docker process.
[$sel:exitCode:DockerException] :: DockerException -> ExitCode
-- | Arguments that were passed to Docker.
[$sel:args:DockerException] :: DockerException -> [Text]
-- | Docker's STDERR output.
[$sel:stderr:DockerException] :: DockerException -> Text
InspectUnknownContainerId :: ContainerId -> DockerException
-- | Id of the Container that we tried to lookup the port mapping.
[$sel:id:DockerException] :: DockerException -> ContainerId
InspectOutputInvalidJSON :: ContainerId -> DockerException
-- | Id of the Container that we tried to lookup the port mapping.
[$sel:id:DockerException] :: DockerException -> ContainerId
InspectOutputUnexpected :: ContainerId -> DockerException
-- | Id of the Container that we tried to lookup the port mapping.
[$sel:id:DockerException] :: DockerException -> ContainerId
UnknownPortMapping :: ContainerId -> Text -> DockerException
-- | Id of the Container that we tried to lookup the port mapping.
[$sel:id:DockerException] :: DockerException -> ContainerId
-- | Textual representation of port mapping we were trying to look up.
[$sel:port:DockerException] :: DockerException -> Text
-- | Configuration for defaulting behavior.
data Config
Config :: Maybe Int -> Tracer -> Config
-- | The number of seconds to maximally wait for a container to become
-- ready. Default is `Just 60`.
--
-- Nothing = waits indefinitely.
[$sel:configDefaultWaitTimeout:Config] :: Config -> Maybe Int
-- | Traces execution inside testcontainers library.
[$sel:configTracer:Config] :: Config -> Tracer
-- | Traces execution within testcontainers library.
data Tracer
-- | Opening socket
pattern TraceOpenSocket :: () => Text -> Int -> Maybe IOException -> Trace
-- | Waiting for a container to become ready. Attached with the timeout to
-- wait (in seconds).
pattern TraceWaitUntilReady :: () => Maybe Int -> Trace
-- | Line written to STDERR by a Docker process.
pattern TraceDockerStderr :: () => Text -> Trace
-- | The low-level invocation of docker command
--
--
-- TraceDockerInvocation args stdin exitcode
--
pattern TraceDockerInvocation :: () => [Text] -> Text -> ExitCode -> Trace
-- | Line written to STDOUT by a Docker process.
pattern TraceDockerStdout :: () => Text -> Trace
-- | Construct a new Tracer from a tracing function.
newTracer :: (Trace -> IO ()) -> Tracer
-- | Default configuration.
defaultDockerConfig :: Config
-- | Autoselect the default configuration depending on wether you use
-- Docker For Mac or not.
determineConfig :: IO Config
-- | Default ContainerRequest. Used as base for every Docker
-- container.
containerRequest :: ToImage -> ContainerRequest
-- | Set the name of a Docker container. This is equivalent to invoking
-- docker run with the --name parameter.
setName :: Text -> ContainerRequest -> ContainerRequest
-- | The command to execute inside the Docker container. This is the
-- equivalent of passing the command on the docker run
-- invocation.
setCmd :: [Text] -> ContainerRequest -> ContainerRequest
-- | Wether to remove the container once exited. This is equivalent to
-- passing --rm to docker run. (default is
-- True).
setRm :: Bool -> ContainerRequest -> ContainerRequest
-- | Set the environment for the container. This is equivalent to passing
-- --env key=value to docker run.
setEnv :: [(Text, Text)] -> ContainerRequest -> ContainerRequest
-- | Set link on the container. This is equivalent to passing --link
-- other_container to docker run.
setLink :: [ContainerId] -> 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)
--
setExpose :: [Int] -> 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.
setWaitingFor :: WaitUntilReady -> ContainerRequest -> ContainerRequest
-- | 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.
run :: MonadDocker m => ContainerRequest -> m Container
-- | Kills a Docker container. kill is essentially docker
-- kill.
kill :: MonadDocker m => Container -> m ()
-- | Stops a Docker container. stop is essentially docker
-- stop.
stop :: MonadDocker m => Container -> m ()
-- | Remove a Docker container. rm is essentially docker rm
-- -f
rm :: MonadDocker m => Container -> m ()
-- | Access STDOUT and STDERR of a running Docker container. This is
-- essentially docker logs under the hood.
withLogs :: forall m a. MonadDocker m => Container -> (Handle -> Handle -> m a) -> m a
-- | 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.
build :: MonadDocker m => ToImage -> m ToImage
-- | Get an Image from a tag.
fromTag :: ImageTag -> ToImage
-- | Build the image from a build path and an optional path to the
-- Dockerfile (default is Dockerfile)
fromBuildContext :: FilePath -> Maybe FilePath -> ToImage
-- | 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.
waitUntilTimeout :: Int -> WaitUntilReady -> WaitUntilReady
-- | Waits until the port of a container is ready to accept connections.
-- This combinator should always be used with waitUntilTimeout.
waitUntilMappedPortReachable :: Int -> 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.
waitWithLogs :: (Container -> Handle -> Handle -> IO ()) -> 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`)
--
waitForLogLine :: Pipe -> (Text -> Bool) -> WaitUntilReady
-- | The image tag assigned by Docker. Uniquely identifies an Image
-- within Docker.
imageTag :: Image -> ImageTag
-- | Returns the underlying image of the container.
containerImage :: Container -> Image
-- | Returns the internal release key used for safely shutting down the
-- container. Use this with care. This function is considered an internal
-- detail.
containerReleaseKey :: Container -> ReleaseKey
-- | Looks up the ip address of the container.
containerIp :: Container -> Text
-- | Looks up an exposed port on the host.
containerPort :: Container -> Int -> Int
-- | Runs the `docker inspect` command. Memoizes the result.
inspect :: MonadDocker m => Container -> m InspectOutput
dockerHostOs :: MonadDocker m => m Text
isDockerOnLinux :: MonadDocker m => m Bool
-- | Image for Redis database.
--
--
-- redis = fromTag "redis:5.0"
--
redis :: ToImage
-- | Image for Mongo database.
--
--
-- mongo = Tag "mongo:4.0.17"
--
mongo :: ToImage
instance Test.Tasty.Options.IsOption TestContainers.Tasty.Trace
instance Test.Tasty.Options.IsOption TestContainers.Tasty.DefaultTimeout