testcontainers: Docker containers for your integration tests.

This is a package candidate release! Here you can preview how this package release will appear once published to the main package index (which can be accomplished via the 'maintain' link below). Please note that once a package has been published to the main package index it cannot be undone! Please consult the package uploading documentation for more information.

[maintain] [Publish]

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


[Skip to Readme]

Properties

Versions 0.1.0.0, 0.2.0.0, 0.3.0.0, 0.3.0.1, 0.3.1.0, 0.4.0.0, 0.4.0.0, 0.5.0.0
Change log CHANGELOG.md
Dependencies aeson (>=1.4.6 && <3), aeson-optics (>=1.1 && <2), async, base (>=4.12 && <5), bytestring (>=0.10.8 && <0.12), directory (>=1.3.6 && <2), exceptions (>=0.10.4 && <0.11), http-client (>=0.5.14 && <1), http-types (>=0.12.3 && <1), mtl (>=2.2.2 && <3), network (>=2.8.0 && <3.2), optics-core (>=0.1 && <0.5), process (>=1.6.5 && <1.7), random (>=1.2 && <2), resourcet (>=1.2.4 && <1.4), tasty (>=1.0 && <1.5), text (>=1.2.3 && <3), unliftio-core (>=0.1.0 && <0.3) [details]
License MIT
Copyright 2023 Alex Biehl
Author Alex Biehl
Maintainer alex.biehl@gmail.com
Category Development
Source repo head: git clone https://github.com/testcontainers/testcontainers-hs
Uploaded by alexbiehl at 2023-02-20T15:02:18Z

Modules

[Index] [Quick Jump]

Downloads

Maintainer's Corner

Package maintainers

For package maintainers and hackage trustees


Readme for testcontainers-0.4.0.0

[back to package description]

About

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

Example

{-# LANGUAGE FlexibleContexts  #-}
{-# LANGUAGE OverloadedStrings #-}
{-# LANGUAGE RecordWildCards   #-}
module Main where

import qualified Test.Tasty           as Tasty
import qualified Test.Tasty.HUnit     as Tasty
import qualified TestContainers.Tasty as TC


data Endpoints = Endpoints
  {
    redisHost :: String
  , redisPort :: Int
  }


-- | Sets up and runs the containers required for this test suite.
setupContainers :: TC.MonadDocker m => m Endpoints
setupContainers = do

  -- Launch the container based on the redis:5.0.0 image.
  redisContainer <- TC.run $ TC.containerRequest (TC.fromTag "redis:5.0.0")
    -- Expose the port 6379 from within the container. The respective port
    -- on the host machine can be looked up using `containerPort` (see below).
    TC.& TC.setExpose [ 6379 ]
    -- Wait until the container is ready to accept requests. `run` blocks until
    -- readiness can be established.
    TC.& TC.setWaitingFor (TC.waitUntilMappedPortReachable 6379)

  pure $ Endpoints
    {
      redisHost = "0.0.0.0"
    , redisPort =
        -- Look up the corresponding port on the host machine for the exposed
        -- port 6379.
        TC.containerPort redisContainer 6379
    }


main :: IO ()
main =
  Tasty.defaultMain $
  -- Use `withContainers` to make the containers available in the closed over
  -- tests. Due to how Tasty handles resources `withContainers` passes down
  -- an IO action `start` to actually start up the containers. `start` can be
  -- invoked multiple times, Tasty makes sure to only start up the containrs
  -- once.
  --
  -- `withContainers` ensures the started containers are shut down correctly
  -- once execution leaves its scope.
  TC.withContainers setupContainers $ \start ->
    Tasty.testGroup "Some test group"
      [
        Tasty.testCase "Redis test" $ do
          -- Actually start the containers!!
          Endpoints {..} <- start
          -- ... assert some properties
          pure ()

      , Tasty.testCase "Another Redis test" $ do
          -- Invoking `start` twice gives the same Endpoints!
          Endpoints {..} <- start
          -- ... assert some properties
          pure ()
      ]