diff --git a/ChangeLog.md b/ChangeLog.md --- a/ChangeLog.md +++ b/ChangeLog.md @@ -2,6 +2,11 @@ `tmp-proc` uses [PVP Versioning][1]. + +## 0.5.1.0 -- 2022-08-08 + +* Bump version of text and base + ## 0.5.0.1 -- 2021-09-30 * Fix use of packaged data in tests diff --git a/README.lhs b/README.lhs --- a/README.lhs +++ b/README.lhs @@ -1,13 +1,15 @@ # tmp-proc -[![Hackage](https://img.shields.io/hackage/v/tmp-proc.svg)](https://hackage.haskell.org/package/tmp-proc) [![GitHub CI](https://github.com/adetokunbo/tmp-proc/actions/workflows/test.yml/badge.svg)](https://github.com/adetokunbo/tmp-proc/actions) +[![Stackage Nightly][stackage-nightly-badge]][stackage-nightly] +[![Hackage][hackage-badge]][hackage] +[![Hackage Dependencies][hackage-deps-badge]][hackage-deps] [![BSD-3.0 license](https://img.shields.io/badge/license-BSD--3.0-blue.svg)](https://github.com/adetokunbo/tmp-proc/blob/master/tmp-proc/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 +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. @@ -54,7 +56,7 @@ ## Specify a Proc instance In `tmp-proc`, docker instances are specified by making new instances of the -`Proc` typeclass. +[Proc][17] typeclass. For this tutorial, we'll test the famous [http-bin](https://httpbin.org) service. Although it's an online service in it's own right, it is also available @@ -79,8 +81,9 @@ - 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. +An instance specifies a number of useful typeclass functions; only [ping][18] is +covered in this tutorial, however they all have important roles that support +integration testing. ```haskell @@ -130,49 +133,64 @@ - `hspec` launches `Procs` during test setup - - this results in an `HList` of `ProcHandle` types being passed to each test. + ```ignore + ... + beforeAll (startupAll $ HttpBinLhs &: HNil) $ afterAll terminateAll $ do + ``` - - (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. + - this results in an `HList` of [ProcHandle][9] types being passed to each test. - - `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 `startupAll` - - this is powered by a feature of [hspec][2], it's through use of `hspec's` - `beforeAll` hook that enables this + ```ignore + ... + it "should succeed when accessing a Proc by name" $ \handles + ``` - - `startupAll` is just one example of a `tmp-proc` combinator meshing well with - the test frameworks' combinators. + - this is simply using the behavior of the `beforeAll` [hook][8] of + [hspec][2], and is one example of how `tmp-proc` combinators mesh well with + typical test frameworks' combinators. - - the `startAll` and `terminateAll` functions used here also work with - `tasty's` [withResource][6] + - the `startupAll` 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] + - `tmp-proc` provides other functions that work with other [hspec hooks][8], + e.g, [runServer][15] and others in [System.TmpProc.Warp][16] that simplify + testing with [WAI][1]. -- the test cases here show the way that `tmp-proc` functions work with an - `HList` of `ProcHandles` + - __N.B.__ In this an example, the HList has only one `Proc`. + [startupAll][13] allows for many `Procs` to be started, each of a + different type. This is possible because `startupAll` acts on and returns + a heteregenous list (`HList`) rather than the usual `List` type. Before it + completes, `startupAll` ensures all the docker services start up ok. +- the test cases here show the way that the `tmp-proc` functions use an + `HList` of `ProcHandles` to interact with the launched services + + ```ignore + ... + ixPing @"http-bin-lhs" Proxy handles `shouldReturn` OK + ``` + - `ixPing` uses [TypeApplications][7] with an index type to identify the - 'ProcHandle' to ping + [ProcHandle][9] to ping - `tmp-proc` provides similar functions that enable access to attributes - of one or many `ProcHandle`. + of one or many `ProcHandle` in an `HList`. - 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. + test code may also access the corresponding service using a + [Connection][10] 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]. +- __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 examples that use [hspec][11] or [tasty][12] in the + [example package][4]. + ## Run the Spec ```haskell @@ -190,3 +208,21 @@ [5]: https://github.com/adetokunbo/tmp-proc/tree/master/tmp-proc [6]: https://hackage.haskell.org/package/tasty-1.4.2/docs/Test-Tasty.html#v:withResource [7]: https://typeclasses.com/ghc/type-applications +[8]: https://hspec.github.io/writing-specs.html#using-hooks +[9]: https://hackage.haskell.org/package/tmp-proc-0.5.0.1/docs/System-TmpProc-Docker.html#t:ProcHandle +[10]: https://hackage.haskell.org/package/tmp-proc-0.5.0.1/docs/System-TmpProc-Docker.html#v:withTmpConn +[11]: https://hackage.haskell.org/package/tmp-proc-example-0.5.0.0/docs/src/TmpProc.Example2.IntegrationSpec.html#spec +[12]: https://hackage.haskell.org/package/tmp-proc-example-0.5.0.0/docs/src/TmpProc.Example1.IntegrationTaste.html#tests +[13]: https://hackage.haskell.org/package/tmp-proc-0.5.0.1/docs/System-TmpProc-Docker.html#v:startupAll +[14]: https://hackage.haskell.org/package/tmp-proc-0.5.0.1/docs/System-TmpProc-Docker.html#v:startup +[15]: https://hackage.haskell.org/package/tmp-proc-0.5.0.1/docs/System-TmpProc-Warp.html#v:runServer +[16]: https://hackage.haskell.org/package/tmp-proc-0.5.0.1/docs/System-TmpProc-Warp.html +[17]: https://hackage.haskell.org/package/tmp-proc-0.5.0.1/docs/System-TmpProc-Docker.html#t:Proc +[18]: https://hackage.haskell.org/package/tmp-proc-0.5.0.1/docs/System-TmpProc-Docker.html#v:ping + +[hackage-deps-badge]: +[hackage-deps]: +[hackage-badge]: +[hackage]: +[stackage-nightly-badge]: +[stackage-nightly]: diff --git a/tmp-proc.cabal b/tmp-proc.cabal --- a/tmp-proc.cabal +++ b/tmp-proc.cabal @@ -1,6 +1,6 @@ cabal-version: 3.0 name: tmp-proc -version: 0.5.0.1 +version: 0.5.1.0 synopsis: Run 'tmp' processes in integration tests description: @tmp-proc@ runs services in docker containers for use in integration tests. @@ -52,12 +52,12 @@ hs-source-dirs: src build-depends: , async ^>=2.2.1 - , base >=4.11 && <4.16 + , base >=4.11 && <5 , bytestring >=0.10.8.2 && <0.12 , mtl ^>=2.2.2 , network >=2.6.3.6 && <3.2 , process ^>=1.6.3.0 - , text ^>=1.2.3 + , text ^>=2.0 , unliftio ^>=0.2.7 , wai ^>=3.2.1 , warp >=3.2.3 && <3.4