BSD-3-Clause licensed by Tim Emiola
Maintained by [email protected]
This version can be pinned in stack with:tmp-proc-,3835
# tmp-proc

[![GitHub CI](](
[![BSD-3.0 license](](

`tmp-proc` is a small library designed to simplify integration tests that use
services running on docker.

This README contains a _How to_ tutorial on using this library. This tutorial
explains step by step how to specify a docker image as a `tmp proc` and use it in
a test.

__N.B.__ It assumes that docker is installed.

All code below can be compiled and run with the following commands:

# At the moment (30/09/2021), this is does not consistently run when using cabal
$ stack build tmp-proc
$ stack run readme

## Preamble: imports and language extensions

Since this is a literate haskell file, we need to specify all our language
extensions and imports up front.

{-# LANGUAGE DataKinds #-}
{-# LANGUAGE LambdaCase #-}
{-# LANGUAGE OverloadedStrings #-}
{-# LANGUAGE ScopedTypeVariables #-}
{-# LANGUAGE TypeApplications #-}
{-# LANGUAGE TypeFamilies #-}

import Test.Hspec

import qualified Data.ByteString.Char8 as C8
import Data.List (foldl')
import Data.Proxy (Proxy (..))
import Data.Text (Text)
import qualified Data.Text as Text
import Network.HTTP.Req

import System.TmpProc (HList (..), HandlesOf, HostIpAddress,
Pinged (..), Proc (..), ProcHandle (..),
SvcURI, manyNamed, startupAll, toPinged,
(&:), ixPing, nameOf, terminateAll)


## Specify a Proc instance

In `tmp-proc`, docker instances are specified by making new instances of the
`Proc` typeclass.

For this tutorial, we'll test the famous [http-bin](
service. Although it's an online service in it's own right, it is also available
as a docker image.

data HttpBinLhs = HttpBinLhs

instance Proc HttpBinLhs where
type Image HttpBinLhs = "kennethreitz/httpbin"
type Name HttpBinLhs = "http-bin-lhs"

uriOf ip = "http://" <> C8.pack (Text.unpack ip) <> "/"
runArgs = []
reset _ = pure ()
ping = pingImpl


A `Proc` instance specifies both an `Image` and `Name`.
- The `Image` corresponds to the docker image that needs to be run
- The `Name` is a label that needs to be unique; it is used an alternate index for the Proc instance.

The instance also specifies a number of useful typeclass functions; only `ping`
will be covered in this tutorial, but the others all have important roles.


pingImpl :: ProcHandle a -> IO Pinged
pingImpl handle = toPinged @HttpException Proxy $ do
gotStatus <- runReq defaultHttpConfig $ do
r <- req GET (handleUrl handle "/status/200") NoReqBody ignoreResponse $ mempty
pure $ responseStatusCode r
if (gotStatus == 200) then pure OK else pure NotOK

handleUrl :: ProcHandle a -> Text -> Url 'Http
handleUrl handle urlPath = foldl' (/:) (http $ hAddr handle)
$ Text.splitOn "/" $ Text.dropWhile (== '/') urlPath


The `pingImpl` used by the `Proc` instance above is implemented next.

Each `Proc` instance must provide a valid `ping` implementation, `tmp-proc` uses
`ping` to determine when the `Proc's` service is ready for use in the test.

## Using the Proc


spec :: Spec
spec = describe ("Tmp.Proc: " ++ Text.unpack (nameOf HttpBinLhs)) $ do
beforeAll (startupAll $ HttpBinLhs &: HNil) $ afterAll terminateAll $ do
context "When accessing the services in the list of test tmp procs" $ do

context "ixPing" $ do

it "should succeed when accessing a Proc by name" $ \handles
-> ixPing @"http-bin-lhs" Proxy handles `shouldReturn` OK

it "should succeed when accessing a Proc by type" $ \handles
-> ixPing @HttpBinLhs Proxy handles `shouldReturn` OK


With just this, it's now possible to write a simple test showing various
features of `tmp-proc`. E.g,

- `hspec` launches `Procs` during test setup

- this results in an `HList` of `ProcHandle` types being passed to each test.

- (In this example, the HList has only one `Proc`. `startupAll` allows for
many `Procs` to started, each of different type. This is possible because
`startupAll` acts on and returns a heteregenous list (or `HList`) rather
than the usual `List` type.

- `startupAll` takes an `HList` of `Procs` and returns an `HList` of
corresponding `ProcHandle` types, first ensuring that all the corresponding
docker services start up ok

- once setup succeeds, each test is passed the `ProcHandles` created by

- this is powered by a feature of [hspec][2], it's through use of `hspec's`
`beforeAll` hook that enables this

- `startupAll` is just one example of a `tmp-proc` combinator meshing well with
the test frameworks' combinators.

- the `startAll` and `terminateAll` functions used here also work with
`tasty's` [withResource][6]

- `tmp-proc` provides other functions that work with other hooks in [hspec][1]

- the test cases here show the way that `tmp-proc` functions work with an
`HList` of `ProcHandles`

- `ixPing` uses [TypeApplications][7] with an index type to identify the
'ProcHandle' to ping

- `tmp-proc` provides similar functions that enable access to attributes
of one or many `ProcHandle`.

- Though not shown here, as well as accessing a `ProcHandle's` attributes,
test code may also to access the corresponding service using a
`Connection` type specific to that service.

- __N.B.__ these test cases are completely unrealistic; there should be no
reason to use `ixPing` in a normal test case! For slightly more realism,
please take a look at the [example package][4].

## Run the Spec


main :: IO ()
main = hspec spec




Revision history for tmp-proc

tmp-proc uses PVP Versioning. – 2021-09-30

  • Fix use of packaged data in tests
  • Introduce some build flags to control how the package builds in CI environments – 2021-09-28

  • Initial release to hackage

  • Re-implemented the user surface to be more typeful and hopefully easier to use.

  • Switched the development build environment to haskell.nix – 2021-08-03

  • Update versions of major dependencies, allowing it to build with GHC 8.10 – 2019-04-01

  • Make the run*Server functions throw exceptions in app threads to the calling thread. – 2019-02-26

  • Add new public functions that allow TLS-protected endpoints – 2019-02-25

  • Reorganize the public API for simpler usage with HSpec and Tasty – 2019-02-18

  • Added integration tests, removed unnecessary internal features from the public api. – 2019-02-17

  • First version. Extracted from some a non-public test library