{-| This module provides a Template Haskell function for automatically generating reified typeclass dictionaries for use with "Control.Monad.TestFixture". These generated dictionaries can be used with functions like 'Control.Monad.TestFixture.unTestFixture' and 'Control.Monad.TestFixture.logTestFixture' to quickly implement monadic typeclasses in a way that can be used to “stub out” functionality in unit tests. The 'mkFixture' function is a Template Haskell code generation tool, which generates three things: 1. A record type that represents a reified typeclass dictionary (or set of typeclass dictionaries). The record contains fields that correspond to the methods of the provided typeclasses, with ordinary method names prefixed with a @_@ character and infix method names prefixed with a @~@ character. 2. A 'Default' instance for the generated record type, which automatically fills all fields with stub implementations that will throw using 'unimplemented'. 3. Typeclass implementations for all of the provided typeclasses using 'TestFixture' and the generated record type that defer to the implementations provided through the reified dictionary. In practice, this is used for generate “fixture” types that are used within tests. For example, consider some typeclasses that encode side-effectful monadic operations: > class Monad m => DB m where > fetchRecord :: DBRecord a => Id a -> m (Either DBError a) > insertRecord :: DBRecord a => a -> m (Either DBError (Id a)) > > class Monad m => HTTP m where > sendRequest :: HTTPRequest -> m (Either HTTPError HTTPResponse) The typeclasses may have relatively straightforward instances for 'IO'. However, one of the main values of them is that alternative instances may be provided in unit tests, which is what 'TestFixture' provides. Therefore, one might use 'mkFixture' to create some utilities for stubbing these typeclasses out: > mkFixture "Fixture" [''DB, ''HTTP] This generates code much like the following: > data Fixture m = > { _fetchRecord :: DBRecord a => Id a -> m (Either DBError a) > , _insertRecord :: DBRecord a => a -> m (Either DBError (Id a)) > , _sendRequest :: HTTPRequest -> m (Either HTTPError HTTPResponse) > } > > instance Default (Fixture m) where > def = Fixture > { _fetchRecord = unimplemented "_fetchRecord" > , _insertRecord = unimplemented "_insertRecord" > , _sendRequest = unimplemented "_sendRequest" > } > > type FixturePure = Fixture (TestFixture Fixture () ()) > type FixtureLog log = Fixture (TestFixture Fixture log ()) > type FixtureState state = Fixture (TestFixture Fixture () state) > type FixtureLogState log state = Fixture (TestFixture Fixture log state) > > type FixturePureT m = Fixture (TestFixture Fixture () () m) > type FixtureLogT log m = Fixture (TestFixture Fixture log () m) > type FixtureStateT state m = Fixture (TestFixture Fixture () state m) > type FixtureLogStateT log state m = Fixture (TestFixtureT Fixture log state m) > > instance Monad m => DB (TestFixtureT Fixture w s m) where > fetchRecord r = do > fn <- asks _fetchRecord > fn r > insertRecord r = do > fn <- asks _insertRecord > fn r > > instance Monad m => HTTP (TestFixtureT Fixture w s m) where > sendRequest r = do > fn <- asks _sendRequest > fn r This type can then be used in tandem with "Control.Monad.TestFixture" to create stubbed typeclass instances and run computations using them. -} module Control.Monad.TestFixture.TH ( mkFixture , def ) where import Control.Monad.TestFixture.TH.Internal (mkFixture) import Data.Default (def)