-- Hoogle documentation, generated by Haddock
-- See Hoogle, http://www.haskell.org/hoogle/


-- | A flexible mock framework for testing effectful code.
--   
--   HMock is a flexible mock framework for testing effectful code in
--   Haskell. Tests can set up expectations about actions that can or
--   should be performed and their results, and then verify those
--   expectations when the test is complete.
--   
--   For more information, see the module documentation for
--   <a>Test.HMock</a>.
@package HMock
@version 0.5.1.2


-- | Internal utilities used for HMock implementation.
module Test.HMock.Internal.Util

-- | A value together with its source location.
data Located a
Loc :: Maybe String -> a -> Located a

-- | Annotates a value with its source location from the call stack.
locate :: CallStack -> a -> Located a

-- | Formats a <a>Located</a> <a>String</a> to include its source location.
withLoc :: Located String -> String

-- | Returns all ways to choose one element from a list, and the
--   corresponding remaining list.
choices :: [a] -> [(a, [a])]
instance GHC.Base.Functor Test.HMock.Internal.Util.Located


-- | Template Haskell utilities used to implement HMock.
module Test.HMock.Internal.TH

-- | Gets the unapplied top-level name from a type application.
unappliedName :: Type -> Maybe Name

-- | Fetches the <a>Name</a> of a <a>TyVarBndr</a>.
tvName :: TyVarBndr flag -> Name

-- | Creates a <a>TyVarBndr</a> for a plain variable without a kind
--   annotation.
bindVar :: Name -> TyVarBndr Specificity

-- | Substitutes a <a>Type</a> for all occurrences of the given
--   <a>Name</a>.
substTypeVar :: Name -> Type -> Type -> Type

-- | Makes variable substitutions from the given table.
substTypeVars :: [(Name, Type)] -> Type -> Type

-- | Splits a function type into a list of bound type vars, context,
--   parameter types, and return value type.
splitType :: Type -> ([Name], Cxt, [Type], Type)

-- | Gets all free type variable <a>Name</a>s in the given <a>Type</a>.
freeTypeVars :: Type -> [Name]

-- | Culls the given binders and constraints to choose only those that
--   apply to free variables in the given type.
relevantContext :: Type -> ([Name], Cxt) -> ([Name], Cxt)

-- | Produces a <a>CxtQ</a> that gives all given variable <a>Name</a>s all
--   of the given class <a>Type</a>s.
constrainVars :: [TypeQ] -> [Name] -> CxtQ

-- | Attempts to unify the given types by constructing a table of
--   substitutions for the variables of the left type that obtain the right
--   one.
unifyTypes :: Type -> Type -> Q (Maybe [(Name, Type)])

-- | Removes all module names from <a>Name</a>s in the given value, so that
--   it will pretty-print more cleanly.
removeModNames :: Data a => a -> a

-- | Determines if this is a polytype, including top-level quantification.
hasPolyType :: Type -> Bool

-- | Determines if there is a polytype nested anywhere in the given type.
--   Top-level quantification doesn't count.
hasNestedPolyType :: Type -> Bool

-- | Attempts to produce sufficient constraints for the given <a>Type</a>
--   to be an instance of the given class <a>Name</a>.
resolveInstance :: Name -> [Type] -> Q (Maybe Cxt)

-- | Attempts to produce sufficient constraints for the given <a>Type</a>
--   to be a satisfied constraint. The type should be a class applied to
--   its type parameters.
--   
--   Unlike <a>simplifyContext</a>, this function always resolves the
--   top-level constraint, and returns <a>Nothing</a> if it cannot do so.
resolveInstanceType :: Type -> Q (Maybe Cxt)

-- | Simplifies a context with complex types (requiring FlexibleContexts)
--   to try to obtain one with all constraints applied to variables.
--   
--   Should return Nothing if and only if the simplified contraint is
--   unsatisfiable, which is the case if and only if it contains a
--   component with no type variables.
simplifyContext :: Cxt -> Q (Maybe Cxt)

-- | Remove instance context from a method.
--   
--   Some GHC versions report class members including the instance context
--   (for example, <tt>show :: Show a =&gt; a -&gt; String</tt>, instead of
--   <tt>show :: a -&gt; String</tt>). This looks for the instance context,
--   and substitutes if needed to eliminate it.
localizeMember :: Type -> Name -> Type -> Q Type


-- | This module provides the basic vocabulary for talking about
--   multiplicity, which is the number of times something is allowed to
--   happen. Multiplicities can be any range of natural numbers, with or
--   without an upper bound.
module Test.HMock.Multiplicity

-- | An acceptable range of number of times for something to happen.
--   
--   A multiplicity can have a lower and an upper bound.
data Multiplicity

-- | Checks whether a certain number satisfies the <a>Multiplicity</a>.
meetsMultiplicity :: Multiplicity -> Int -> Bool

-- | Checks whether a <a>Multiplicity</a> is capable of matching any number
--   at all.
--   
--   <pre>
--   &gt;&gt;&gt; feasible once
--   True
--   
--   &gt;&gt;&gt; feasible 0
--   True
--   
--   &gt;&gt;&gt; feasible (once - 2)
--   False
--   </pre>
feasible :: Multiplicity -> Bool

-- | A <a>Multiplicity</a> that means exactly once.
--   
--   <pre>
--   &gt;&gt;&gt; meetsMultiplicity once 0
--   False
--   
--   &gt;&gt;&gt; meetsMultiplicity once 1
--   True
--   
--   &gt;&gt;&gt; meetsMultiplicity once 2
--   False
--   </pre>
once :: Multiplicity

-- | A <a>Multiplicity</a> that means any number of times. &gt;&gt;&gt;
--   meetsMultiplicity anyMultiplicity 0 True &gt;&gt;&gt;
--   meetsMultiplicity anyMultiplicity 1 True &gt;&gt;&gt;
--   meetsMultiplicity anyMultiplicity 10 True
anyMultiplicity :: Multiplicity

-- | A <a>Multiplicity</a> that means at least this many times.
--   
--   <pre>
--   &gt;&gt;&gt; meetsMultiplicity (atLeast 2) 1
--   False
--   
--   &gt;&gt;&gt; meetsMultiplicity (atLeast 2) 2
--   True
--   
--   &gt;&gt;&gt; meetsMultiplicity (atLeast 2) 3
--   True
--   </pre>
atLeast :: Multiplicity -> Multiplicity

-- | A <a>Multiplicity</a> that means at most this many times.
--   
--   <pre>
--   &gt;&gt;&gt; meetsMultiplicity (atMost 2) 1
--   True
--   
--   &gt;&gt;&gt; meetsMultiplicity (atMost 2) 2
--   True
--   
--   &gt;&gt;&gt; meetsMultiplicity (atMost 2) 3
--   False
--   </pre>
atMost :: Multiplicity -> Multiplicity

-- | A <a>Multiplicity</a> that means any number in this interval,
--   endpoints included. For example, <tt><a>between</a> 2 3</tt> means 2
--   or 3 times, while <tt><a>between</a> n n</tt> is equivalent to
--   <tt>n</tt>.
--   
--   <pre>
--   &gt;&gt;&gt; meetsMultiplicity (between 2 3) 1
--   False
--   
--   &gt;&gt;&gt; meetsMultiplicity (between 2 3) 2
--   True
--   
--   &gt;&gt;&gt; meetsMultiplicity (between 2 3) 3
--   True
--   
--   &gt;&gt;&gt; meetsMultiplicity (between 2 3) 4
--   False
--   </pre>
between :: Multiplicity -> Multiplicity -> Multiplicity
instance GHC.Classes.Eq Test.HMock.Multiplicity.Multiplicity
instance GHC.Show.Show Test.HMock.Multiplicity.Multiplicity
instance GHC.Num.Num Test.HMock.Multiplicity.Multiplicity


-- | The internal core language of expectations in HMock.
module Test.HMock.Internal.ExpectSet

-- | A set of expected steps and their responses. This is the "core"
--   language of expectations for HMock. It's based roughly on
--   Svenningsson, Svensson, Smallbone, Arts, Norell, and Hughes'
--   Expressive Semantics of Mocking. However, there are a few small
--   adjustments. We have two repetition operators which respectively
--   represent general repetition with interleaving, and consecutive
--   repetition. We also attach arbitrary multiplicities to repetition.
data ExpectSet step
[ExpectStep] :: step -> ExpectSet step
[ExpectNothing] :: ExpectSet step
[ExpectSequence] :: ExpectSet step -> ExpectSet step -> ExpectSet step
[ExpectInterleave] :: ExpectSet step -> ExpectSet step -> ExpectSet step
[ExpectEither] :: ExpectSet step -> ExpectSet step -> ExpectSet step
[ExpectMulti] :: Multiplicity -> ExpectSet step -> ExpectSet step
[ExpectConsecutive] :: Multiplicity -> ExpectSet step -> ExpectSet step

-- | Checks whether an ExpectSet is in an "accepting" state. In other
--   words, is it okay for the test to end here? If False, then there are
--   still expectations that must be satisfied before the test can succeed.
satisfied :: ExpectSet step -> Bool

-- | Computes the live steps of the ExpectSet. In other words: which
--   individual steps can be matched right now, and what are the remaining
--   expectations in each case?
liveSteps :: ExpectSet step -> [(step, ExpectSet step)]

-- | Performs a complete simplification of the ExpectSet. This could be
--   slow, but we intend to do it only for error messages, so it need not
--   be very fast.
simplify :: ExpectSet step -> ExpectSet step

-- | Get a list of all steps mentioned by an <a>ExpectSet</a>. This is used
--   to determine which classes need to be initialized before adding an
--   expectation.
getSteps :: ExpectSet step -> [step]

-- | A higher-level intermediate form of an ExpectSet suitable for
--   communication with the user. Chains of binary operators are collected
--   into sequences to be displayed in lists rather than arbitrary nesting.
data CollectedSet step
[CollectedStep] :: step -> CollectedSet step
[CollectedNothing] :: CollectedSet step
[CollectedSequence] :: [CollectedSet step] -> CollectedSet step
[CollectedInterleave] :: [CollectedSet step] -> CollectedSet step
[CollectedChoice] :: [CollectedSet step] -> CollectedSet step
[CollectedMulti] :: Multiplicity -> CollectedSet step -> CollectedSet step
[CollectedConsecutive] :: Multiplicity -> CollectedSet step -> CollectedSet step

-- | Collects an ExpectSet into the intermediate form for display. It's
--   assumed that the expression was simplified before this operation.
collect :: ExpectSet step -> CollectedSet step

-- | Converts a set of expectations into a string that summarizes them,
--   with the given prefix (used to indent).
formatExpectSet :: Show step => ExpectSet step -> String

-- | Reduces a set of expectations to the minimum steps that would be
--   required to satisfy the entire set. This weeds out unnecessary
--   information before reporting that there were unmet expectations at the
--   end of the test.
excess :: ExpectSet step -> ExpectSet step
instance GHC.Classes.Eq step => GHC.Classes.Eq (Test.HMock.Internal.ExpectSet.ExpectSet step)
instance GHC.Show.Show step => GHC.Show.Show (Test.HMock.Internal.ExpectSet.ExpectSet step)


-- | This module defines the <a>Rule</a> type, which describes a matcher
--   for methods and a (possibly empty) list of responses to use for
--   successive calls to matching methods. The <a>Expectable</a> type class
--   generalizes <a>Rule</a>, so that you can specify a bare <a>Matcher</a>
--   or <a>Action</a> in most situations where a <a>Rule</a> is needed but
--   you don't want to provide a response.
module Test.HMock.Rule

-- | A rule for matching a method and responding to it when it matches.
--   
--   The method may be matched by providing either an <a>Action</a> to
--   match exactly, or a <a>Matcher</a>. Exact matching is only available
--   when all method arguments
--   
--   A <a>Rule</a> may have zero or more responses, which are attached
--   using <a>|-&gt;</a> and <a>|=&gt;</a>. If there are no responses for a
--   <a>Rule</a>, then there must be a default response for that action,
--   and it is used. If more than one response is added, the rule will
--   perform the responses in order, repeating the last response if there
--   are additional matches.
--   
--   Example:
--   
--   <pre>
--   <a>expect</a> $
--     GetLine_ <a>anything</a>
--       <a>|-&gt;</a> "hello"
--       <a>|=&gt;</a> (GetLine prompt) -&gt; "The prompt was " ++ prompt
--       <a>|-&gt;</a> "quit"
--   </pre>
data Rule (cls :: (Type -> Type) -> Constraint) (name :: Symbol) (m :: Type -> Type) (r :: Type)

-- | Class for things that can be expected. This is includes <a>Rule</a>s,
--   but also bare <a>Matcher</a>s and <a>Action</a>s with no explicit
--   response.
class Expectable cls name m r ex | ex -> cls name m r

-- | Converts an expectable to a Rule that means the same thing.
toRule :: Expectable cls name m r ex => ex -> Rule cls name m r

-- | Attaches a return value to an expectation. This is more convenient
--   than <a>|=&gt;</a> in the common case where you just want to return a
--   known result. <tt>e <a>|-&gt;</a> r</tt> means the same thing as <tt>e
--   <a>|=&gt;</a> <a>const</a> (<a>return</a> r)</tt>.
(|->) :: (Monad m, Expectable cls name m r ex) => ex -> r -> Rule cls name m r
infixl 1 |->

-- | Attaches a response to an expectation. This is a flexible response,
--   which can look at arguments, do things in the base monad, set up more
--   expectations, etc. A matching <a>Action</a> is passed to the response.
(|=>) :: Expectable cls name m r ex => ex -> (Action cls name m r -> MockT m r) -> Rule cls name m r
infixl 1 |=>

-- | A way to match an entire action, using conditions that might depend on
--   the relationship between arguments.
data WholeMethodMatcher cls name m r
[SuchThat] :: Matcher cls name m r -> (Action cls name m r -> Bool) -> WholeMethodMatcher cls name m r
instance Test.HMock.Rule.Expectable cls name m r (Test.HMock.Internal.Rule.Rule cls name m r)
instance Test.HMock.Rule.Expectable cls name m r (Test.HMock.Mockable.Matcher cls name m r)
instance Test.HMock.Rule.Expectable cls name m r (Test.HMock.Internal.Rule.WholeMethodMatcher cls name m r)


-- | This module defines the <a>MockableBase</a> and <a>Mockable</a>
--   classes that are needed to use an MTL-style type class with
--   <a>MockT</a>. You will typically derive <a>MockableBase</a> with
--   Template Haskell, since it's mostly boilerplate. The <a>Mockable</a>
--   class adds a customizable setup method which you can define yourself
--   to add the right defaults for methods in the mocked class.
module Test.HMock.Mockable

-- | A class for <a>Monad</a> subclasses whose methods can be mocked. This
--   class augments <a>MockableBase</a> with a setup method that is run
--   before HMock touches the <a>Monad</a> subclass for the first time. The
--   default implementation does nothing, but you can derive your own
--   instances that add setup behavior.
class MockableBase cls => Mockable (cls :: (Type -> Type) -> Constraint)

-- | An action to run and set up defaults for this class. The action will
--   be run before HMock touches the class, either to add expectations or
--   to delegate a method.
--   
--   By default, unexpected actions throw errors, and actions with no
--   explicit default always return the default value of their return type,
--   or <a>undefined</a> if there is none. You can change this on a
--   per-class or per-test basis.
--   
--   <ul>
--   <li>To change defaults on a per-class basis, you should use
--   <a>allowUnexpected</a> and/or <a>byDefault</a> to perform the setup
--   you need here.</li>
--   <li>To change defaults on a per-test basis, you should use
--   <a>allowUnexpected</a> and/or <a>byDefault</a> directly from the
--   test.</li>
--   </ul>
setupMockable :: (Mockable cls, MonadIO m, Typeable m) => proxy cls -> MockSetup m ()

-- | A base class for <a>Monad</a> subclasses whose methods can be mocked.
--   You usually want to generate this instance using <a>makeMockable</a>,
--   <a>makeMockable</a>, or <a>makeMockableWithOptions</a>, since it's
--   just boilerplate.
class (Typeable cls) => MockableBase (cls :: (Type -> Type) -> Constraint) where {
    
    -- | An action that is performed. This data type will have one constructor
    --   for each method.
    data Action cls :: Symbol -> (Type -> Type) -> Type -> Type;
    
    -- | A specification for matching actions. The actual arguments should be
    --   replaced with predicates.
    data Matcher cls :: Symbol -> (Type -> Type) -> Type -> Type;
}

-- | Gets a text description of an <a>Action</a>, for use in error
--   messages.
showAction :: MockableBase cls => Action cls name m a -> String

-- | Gets a text description of a <a>Matcher</a>, for use in error
--   messages.
showMatcher :: MockableBase cls => Maybe (Action cls name m a) -> Matcher cls name m b -> String

-- | Attempts to match an <a>Action</a> with a <a>Matcher</a>.
matchAction :: MockableBase cls => Matcher cls name m a -> Action cls name m a -> MatchResult

-- | The result of matching a <tt><a>Matcher</a> a</tt> with an
--   <tt><a>Action</a> b</tt>. Because the types should already guarantee
--   that the methods match, all that's left is to match arguments.
data MatchResult

-- | No match. The arg is explanations of mismatch.
[NoMatch] :: [(Int, String)] -> MatchResult

-- | Match. Stores a witness to the equality of return types.
[Match] :: MatchResult


-- | This module contains MockT and SetupMockT state functions.
module Test.HMock.Internal.State

-- | The severity for a possible problem.
data Severity

-- | Fail the test.
Error :: Severity

-- | Print a message, but continue the test.
Warning :: Severity

-- | Don't do anything.
Ignore :: Severity

-- | Full state of a mock.
data MockState m
MockState :: TVar (ExpectSet (Step m)) -> TVar [Step m] -> TVar [Step m] -> TVar [Step m] -> TVar Severity -> TVar Severity -> TVar Severity -> TVar Severity -> TVar (Set TypeRep) -> TVar (Set (TypeRep, String)) -> Maybe (MockState m) -> MockState m
[mockExpectSet] :: MockState m -> TVar (ExpectSet (Step m))
[mockDefaults] :: MockState m -> TVar [Step m]
[mockAllowUnexpected] :: MockState m -> TVar [Step m]
[mockSideEffects] :: MockState m -> TVar [Step m]
[mockAmbiguitySeverity] :: MockState m -> TVar Severity
[mockUnexpectedSeverity] :: MockState m -> TVar Severity
[mockUninterestingSeverity] :: MockState m -> TVar Severity
[mockUnmetSeverity] :: MockState m -> TVar Severity
[mockClasses] :: MockState m -> TVar (Set TypeRep)
[mockInterestingMethods] :: MockState m -> TVar (Set (TypeRep, String))
[mockParent] :: MockState m -> Maybe (MockState m)

-- | Initializes a new <a>MockState</a> with the given parent. If the
--   parent is <a>Nothing</a>, then a new root state is made.
initMockState :: MonadIO m => Maybe (MockState m) -> m (MockState m)

-- | Gets a list of all states, starting with the innermost.
allStates :: MockState m -> [MockState m]

-- | Gets the root state.
rootState :: MockState m -> MockState m

-- | Monad for setting up a mockable class. Note that even though the type
--   looks that way, this is *not* a monad transformer. It's a very
--   restricted environment that can only be used to set up defaults for a
--   class.
newtype MockSetup m a
[MockSetup] :: ReaderT (MockState m) STM a -> MockSetup m a

-- | Runs a setup action with the root state, rather than the current one.
runInRootState :: MockSetup m a -> MockSetup m a

-- | Run an STM action in <a>MockSetup</a>
mockSetupSTM :: STM a -> MockSetup m a

-- | Runs class initialization for a <a>Mockable</a> class, if it hasn't
--   been run yet.
initClassIfNeeded :: forall cls m proxy. (Mockable cls, Typeable m, MonadIO m) => proxy cls -> MockSetup m ()

-- | Marks a method as "interesting". This can have implications for what
--   happens to calls to that method.
markInteresting :: forall (cls :: (Type -> Type) -> Constraint) name m proxy1 proxy2. (Typeable cls, KnownSymbol name) => proxy1 cls -> proxy2 name -> MockSetup m ()

-- | Determines whether a method is "interesting".
isInteresting :: forall (cls :: (Type -> Type) -> Constraint) name m proxy1 proxy2. (Typeable cls, KnownSymbol name) => proxy1 cls -> proxy2 name -> MockSetup m Bool

-- | Runs class initialization for all uninitialized <a>Mockable</a>
--   classes in the given <a>ExpectSet</a>.
initClassesAsNeeded :: MonadIO m => ExpectSet (Step m) -> MockSetup m ()

-- | Monad transformer for running mocks.
newtype MockT m a
[MockT] :: ReaderT (MockState m) m a -> MockT m a

-- | Applies a function to the base monad of <a>MockT</a>.
mapMockT :: (m a -> m b) -> MockT m a -> MockT m b

-- | This type class defines a shared API between the <a>MockT</a> and
--   <a>MockSetup</a> monads.
class MockContext ctx

-- | Runs a <a>MockSetup</a> action in this monad.
fromMockSetup :: (MockContext ctx, MonadIO m) => MockSetup m a -> ctx m a

-- | Adds an expectation to the <a>MockState</a> for the given
--   <a>ExpectSet</a>, interleaved with any existing expectations.
expectThisSet :: MonadIO m => ExpectSet (Step m) -> MockSetup m ()

-- | Reports a potential problem with the given <a>Severity</a>.
reportFault :: (HasCallStack, MonadIO m) => Severity -> String -> MockT m ()
instance GHC.Base.Monad (Test.HMock.Internal.State.MockSetup m)
instance GHC.Base.Applicative (Test.HMock.Internal.State.MockSetup m)
instance GHC.Base.Functor (Test.HMock.Internal.State.MockSetup m)
instance Control.Monad.Catch.MonadThrow m => Control.Monad.Catch.MonadThrow (Test.HMock.Internal.State.MockT m)
instance Control.Monad.Catch.MonadMask m => Control.Monad.Catch.MonadMask (Test.HMock.Internal.State.MockT m)
instance Control.Monad.Catch.MonadCatch m => Control.Monad.Catch.MonadCatch (Test.HMock.Internal.State.MockT m)
instance Control.Monad.Base.MonadBase b m => Control.Monad.Base.MonadBase b (Test.HMock.Internal.State.MockT m)
instance Control.Monad.Cont.Class.MonadCont m => Control.Monad.Cont.Class.MonadCont (Test.HMock.Internal.State.MockT m)
instance Control.Monad.Error.Class.MonadError e m => Control.Monad.Error.Class.MonadError e (Test.HMock.Internal.State.MockT m)
instance (Control.Monad.Reader.Class.MonadReader r m, Control.Monad.Writer.Class.MonadWriter w m, Control.Monad.State.Class.MonadState s m) => Control.Monad.RWS.Class.MonadRWS r w s (Test.HMock.Internal.State.MockT m)
instance Control.Monad.Writer.Class.MonadWriter w m => Control.Monad.Writer.Class.MonadWriter w (Test.HMock.Internal.State.MockT m)
instance Control.Monad.State.Class.MonadState s m => Control.Monad.State.Class.MonadState s (Test.HMock.Internal.State.MockT m)
instance Control.Monad.IO.Class.MonadIO m => Control.Monad.IO.Class.MonadIO (Test.HMock.Internal.State.MockT m)
instance Control.Monad.Fail.MonadFail m => Control.Monad.Fail.MonadFail (Test.HMock.Internal.State.MockT m)
instance GHC.Base.Monad m => GHC.Base.Monad (Test.HMock.Internal.State.MockT m)
instance GHC.Base.Applicative m => GHC.Base.Applicative (Test.HMock.Internal.State.MockT m)
instance GHC.Base.Functor m => GHC.Base.Functor (Test.HMock.Internal.State.MockT m)
instance Test.HMock.Internal.State.MockContext Test.HMock.Internal.State.MockSetup
instance Test.HMock.Internal.State.MockContext Test.HMock.Internal.State.MockT
instance Test.HMock.ExpectContext.ExpectContext Test.HMock.Internal.State.MockT
instance Control.Monad.Trans.Class.MonadTrans Test.HMock.Internal.State.MockT
instance Control.Monad.IO.Unlift.MonadUnliftIO m => Control.Monad.IO.Unlift.MonadUnliftIO (Test.HMock.Internal.State.MockT m)
instance Control.Monad.Reader.Class.MonadReader r m => Control.Monad.Reader.Class.MonadReader r (Test.HMock.Internal.State.MockT m)
instance Test.HMock.ExpectContext.ExpectContext Test.HMock.Internal.State.MockSetup


-- | This module defines the desugaring from multi-response <a>Rule</a>s
--   into multiple steps.
module Test.HMock.Internal.Step

-- | A Rule that contains only a single response. This is the target for
--   desugaring the multi-response rule format.
data SingleRule (cls :: (Type -> Type) -> Constraint) (name :: Symbol) (m :: Type -> Type) (r :: Type)
[:->] :: WholeMethodMatcher cls name m r -> Maybe (Action cls name m r -> MockT m r) -> SingleRule cls name m r

-- | A single step of an expectation.
data Step m
[Step] :: MockableMethod cls name m r => Located (SingleRule cls name m r) -> Step m

-- | Expands a Rule into an expectation. The expected multiplicity will be
--   one if there are no responses; otherwise one call is expected per
--   response.
expandRule :: MockableMethod cls name m r => CallStack -> Rule cls name m r -> ExpectSet (Step m)

-- | Expands a Rule into an expectation, given a target multiplicity. It is
--   an error if there are too many responses for the multiplicity. If
--   there are too few responses, the last response will be repeated.
expandRepeatRule :: MockableMethod cls name m r => Multiplicity -> CallStack -> Rule cls name m r -> ExpectSet (Step m)

-- | Newtype wrapper to make the type of ExpectSet conform to the
--   ExpectContext class. The "return type" a is a phantom.
newtype Expected m a
Expected :: ExpectSet (Step m) -> Expected m a
[unwrapExpected] :: Expected m a -> ExpectSet (Step m)
instance Test.HMock.ExpectContext.ExpectContext Test.HMock.Internal.Step.Expected
instance GHC.Show.Show (Test.HMock.Internal.Step.Step m)


-- | Internal module to define <a>Rule</a>, so that its constructor can be
--   visible to other implementation code.
module Test.HMock.Internal.Rule

-- | A way to match an entire action, using conditions that might depend on
--   the relationship between arguments.
data WholeMethodMatcher cls name m r
[JustMatcher] :: Matcher cls name m r -> WholeMethodMatcher cls name m r
[SuchThat] :: Matcher cls name m r -> (Action cls name m r -> Bool) -> WholeMethodMatcher cls name m r

-- | Displays a WholeMethodMatcher. The predicate isn't showable, but we
--   can at least indicate whether there is one present.
showWholeMatcher :: MockableBase cls => Maybe (Action cls name m a) -> WholeMethodMatcher cls name m b -> String

-- | A rule for matching a method and responding to it when it matches.
--   
--   The method may be matched by providing either an <a>Action</a> to
--   match exactly, or a <a>Matcher</a>. Exact matching is only available
--   when all method arguments
--   
--   A <a>Rule</a> may have zero or more responses, which are attached
--   using <a>|-&gt;</a> and <a>|=&gt;</a>. If there are no responses for a
--   <a>Rule</a>, then there must be a default response for that action,
--   and it is used. If more than one response is added, the rule will
--   perform the responses in order, repeating the last response if there
--   are additional matches.
--   
--   Example:
--   
--   <pre>
--   <a>expect</a> $
--     GetLine_ <a>anything</a>
--       <a>|-&gt;</a> "hello"
--       <a>|=&gt;</a> (GetLine prompt) -&gt; "The prompt was " ++ prompt
--       <a>|-&gt;</a> "quit"
--   </pre>
data Rule (cls :: (Type -> Type) -> Constraint) (name :: Symbol) (m :: Type -> Type) (r :: Type)
[:=>] :: WholeMethodMatcher cls name m r -> [Action cls name m r -> MockT m r] -> Rule cls name m r


-- | This module defines the <a>ExpectContext</a> class, whose members
--   provide the combinators for building the execution plan for your
--   mocks. Notably, there is a <a>MockT</a> instance for
--   <a>ExpectContext</a>, so you can use these combinators to add
--   expectations inside your tests that run in <a>MockT</a>, as well as
--   nesting them in other combinators.
module Test.HMock.ExpectContext

-- | All constraints needed to mock a method with the given class, name,
--   base monad, and return type.
type MockableMethod (cls :: (Type -> Type) -> Constraint) (name :: Symbol) (m :: Type -> Type) (r :: Type) = (Mockable cls, Typeable m, KnownSymbol name, Typeable r)

-- | Type class for contexts in which one can build expectations. Notably,
--   this includes <a>MockT</a>, which expects actions to be performed
--   during a test.
--   
--   The methods of this class represent the user-facing API for build your
--   execution plan for mocks.
class ExpectContext (ctx :: (Type -> Type) -> Type -> Type)

-- | Creates an expectation that an action is performed once per given
--   response (or exactly once if there is no response).
--   
--   <pre>
--   <a>runMockT</a> <a>$</a> do
--     <a>expect</a> <a>$</a>
--       ReadFile "foo.txt"
--         <a>|-&gt;</a> "lorem ipsum"
--         <a>|-&gt;</a> "oops, the file changed out from under me!"
--     callCodeUnderTest
--   </pre>
--   
--   In this example, <a>readFile</a> must be called exactly twice by the
--   tested code, and will return "lorem ipsum" the first time, but
--   something different the second time.
expect :: (ExpectContext ctx, HasCallStack, MonadIO m, MockableMethod cls name m r, Expectable cls name m r expectable) => expectable -> ctx m ()

-- | Creates an expectation that an action is performed some number of
--   times.
--   
--   <pre>
--   <a>runMockT</a> <a>$</a> do
--     <a>expect</a> <a>$</a> MakeList
--     <a>expectN</a> (<a>atLeast</a> 2) <a>$</a>
--       CheckList "Cindy Lou Who" <a>|-&gt;</a> Nice
--   
--     callCodeUnderTest
--   </pre>
expectN :: (ExpectContext ctx, HasCallStack, MonadIO m, MockableMethod cls name m r, Expectable cls name m r expectable) => Multiplicity -> expectable -> ctx m ()

-- | Specifies a response if a matching action is performed, but doesn't
--   expect anything. This is equivalent to <tt><a>expectN</a>
--   <a>anyMultiplicity</a></tt>, but shorter.
--   
--   In this example, the later use of <a>expectAny</a> overrides earlier
--   uses, but only for calls that match its conditions.
--   
--   <pre>
--   <a>runMockT</a> <a>$</a> do
--     <a>expectAny</a> <a>$</a>
--       ReadFile_ anything <a>|-&gt;</a> "tlhIngan maH!"
--     <a>expectAny</a> <a>$</a>
--       ReadFile "config.txt" <a>|-&gt;</a> "lang: klingon"
--   
--     callCodeUnderTest
--   </pre>
expectAny :: (ExpectContext ctx, HasCallStack, MonadIO m, MockableMethod cls name m r, Expectable cls name m r expectable) => expectable -> ctx m ()

-- | Creates a sequential expectation. Other actions can still happen
--   during the sequence, but these specific expectations must be met in
--   this order.
--   
--   <pre>
--   <a>inSequence</a>
--     [ <a>expect</a> <a>$</a> MoveForward,
--       <a>expect</a> <a>$</a> TurnRight,
--       <a>expect</a> <a>$</a> MoveForward
--     ]
--   </pre>
--   
--   Beware of using <a>inSequence</a> too often. It is appropriate when
--   the property you are testing is that the order of effects is correct.
--   If that's not the purpose of the test, consider adding several
--   independent expectations, instead. This avoids over-asserting, and
--   keeps your tests less brittle.
inSequence :: (ExpectContext ctx, MonadIO m) => (forall ctx'. ExpectContext ctx' => [ctx' m ()]) -> ctx m ()

-- | Combines multiple expectations, which can occur in any order. Most of
--   the time, you can achieve the same thing by expecting each separately,
--   but this can be combined in compound expectations to describe more
--   complex ordering constraints.
--   
--   If ambiguity checking is disabled, the choice is left-biased, so
--   earlier options are preferred over ambiguous later options.
--   
--   <pre>
--   <a>inSequence</a>
--     [ <a>inAnyOrder</a>
--         [ <a>expect</a> <a>$</a> AdjustMirrors,
--           <a>expect</a> <a>$</a> FastenSeatBelt
--         ],
--       <a>expect</a> <a>$</a> StartCar
--     ]
--   </pre>
inAnyOrder :: (ExpectContext ctx, MonadIO m) => (forall ctx'. ExpectContext ctx' => [ctx' m ()]) -> ctx m ()

-- | Combines multiple expectations, requiring exactly one of them to
--   occur. If ambiguity checking is disabled, the choice is left-biased,
--   so earlier options are preferred over ambiguous later options.
--   
--   <pre>
--   <a>anyOf</a>
--     [ <a>expect</a> $ ApplyForJob,
--       <a>expect</a> $ ApplyForUniversity
--     ]
--   </pre>
anyOf :: (ExpectContext ctx, MonadIO m) => (forall ctx'. ExpectContext ctx' => [ctx' m ()]) -> ctx m ()

-- | Creates a parent expectation that the child expectation will happen a
--   certain number of times. Unlike <a>expectN</a>, the child expectation
--   can be arbitrarily complex and span multiple actions. Also unlike
--   <a>expectN</a>, each new execution will restart response sequences for
--   rules with more than one response.
--   
--   Different occurrences of the child can be interleaved. If ambiguity
--   checking is disabled, progressing on an existing occurrence is
--   preferred over starting a new occurrence when it's ambiguous.
times :: (ExpectContext ctx, MonadIO m) => Multiplicity -> (forall ctx'. ExpectContext ctx' => ctx' m ()) -> ctx m ()

-- | Creates a parent expectation that the child expectation will happen a
--   certain number of times. Unlike <a>expectN</a>, the child expectation
--   can be arbitrarily complex and span multiple actions. Also unlike
--   <a>expectN</a>, each new execution will restart response sequences for
--   rules with more than one response.
--   
--   Different occurrences of the child must happen consecutively, with one
--   finishing before the next begins.
consecutiveTimes :: (ExpectContext ctx, MonadIO m) => Multiplicity -> (forall ctx'. ExpectContext ctx' => ctx' m ()) -> ctx m ()


-- | This module defines monads for working with mocks. HMock tests run in
--   the <a>MockT</a> monad transformer. A more limited monad,
--   <a>MockSetup</a>, is used for setting up defaults for each class. Both
--   are instances of the <a>MockContext</a> monad, which defines a shared
--   API.
module Test.HMock.MockT

-- | Monad transformer for running mocks.
data MockT m a

-- | Runs a test in the <a>MockT</a> monad, handling all of the mocks.
runMockT :: forall m a. MonadIO m => MockT m a -> m a

-- | Runs a test in the <a>MockT</a> monad. The test can unlift other MockT
--   pieces to the base monad while still acting on the same set of
--   expectations. This can be useful for testing concurrency or similar
--   mechanisms.
--   
--   <pre>
--   test = <a>withMockT</a> <a>$</a> inMockT -&gt; do
--      <a>expect</a> <a>$</a> ...
--   
--      <a>liftIO</a> <a>$</a> <a>forkIO</a> <a>$</a> inMockT firstThread
--      <a>liftIO</a> <a>$</a> <a>forkIO</a> <a>$</a> inMockT secondThread
--   </pre>
--   
--   This is a low-level primitive. Consider using the <tt>unliftio</tt>
--   package for higher level implementations of multithreading and other
--   primitives.
withMockT :: forall m b. MonadIO m => ((forall a. MockT m a -> m a) -> MockT m b) -> m b

-- | Starts a nested block within <a>MockT</a>. The nested block has its
--   own set of expectations, which must be fulfilled before the end of the
--   block.
--   
--   Beware: use of <a>nestMockT</a> might signify that you are doing too
--   much in a single test. Consider splitting large tests into a separate
--   test for each case.
nestMockT :: forall m a. MonadIO m => MockT m a -> MockT m a

-- | Starts a nested block within <a>MockT</a>. The nested block has its
--   own set of expectations, which must be fulfilled before the end of the
--   block. It can unlift other MockT pieces to the base monad while still
--   acting on the same set of expectations. This can be useful for testing
--   concurrency or similar mechanisms.
--   
--   Beware: use of <a>nestMockT</a> might signify that you are doing too
--   much in a single test. Consider splitting large tests into a separate
--   test for each case.
withNestedMockT :: forall m b. MonadIO m => ((forall a. MockT m a -> m a) -> MockT m b) -> MockT m b

-- | The severity for a possible problem.
data Severity

-- | Fail the test.
Error :: Severity

-- | Print a message, but continue the test.
Warning :: Severity

-- | Don't do anything.
Ignore :: Severity

-- | Sets the severity for ambiguous actions. An ambiguous action is one
--   that matches expectations in more than one way. If this is not set to
--   <a>Error</a>, the most recently added expectation will take
--   precedence.
--   
--   This defaults to <a>Ignore</a>.
setAmbiguityCheck :: MonadIO m => Severity -> MockT m ()

-- | Sets the severity for uninteresting actions. An uninteresting action
--   is one for which no expectations or other configuration have been
--   added that mention the method at all. If this is not set to
--   <a>Error</a>, then uninteresting methods are treated just like
--   unexpected methods.
--   
--   Before you weaken this check, consider that the labeling of methods as
--   "uninteresting" is non-compositional. A change in one part of your
--   test can result in a formerly uninteresting action being considered
--   interesting in a different part of the test.
--   
--   This defaults to <a>Error</a>.
setUninterestingActionCheck :: MonadIO m => Severity -> MockT m ()

-- | Sets the severity for unexpected actions. An unexpected action is one
--   that doesn't match any expectations *and* isn't explicitly allowed by
--   <a>allowUnexpected</a>. If this is not set to <a>Error</a>, the action
--   returns its default response.
--   
--   This defaults to <a>Error</a>.
setUnexpectedActionCheck :: MonadIO m => Severity -> MockT m ()

-- | Sets the severity for unmet expectations. An unmet expectation happens
--   when an expectation is added, but either the test (or nesting level)
--   ends or <a>verifyExpectations</a> is used before a matching action
--   takes place.
--   
--   This defaults to <a>Error</a>.
setUnmetExpectationCheck :: MonadIO m => Severity -> MockT m ()

-- | Fetches a <a>String</a> that describes the current set of outstanding
--   expectations. This is sometimes useful for debugging test code. The
--   exact format is not specified.
describeExpectations :: MonadIO m => MockT m String

-- | Verifies that all mock expectations are satisfied. If there is a
--   nested block in effect, only the expectations of that nested block are
--   verified You normally don't need to do this, because it happens
--   automatically at the end of your test or nested block. However, it's
--   occasionally useful to check expectations early.
--   
--   Beware: use of <a>verifyExpectations</a> might signify that you are
--   doing too much in a single test. Consider splitting large tests into a
--   separate test for each case.
verifyExpectations :: MonadIO m => MockT m ()

-- | Monad for setting up a mockable class. Note that even though the type
--   looks that way, this is *not* a monad transformer. It's a very
--   restricted environment that can only be used to set up defaults for a
--   class.
data MockSetup m a

-- | This type class defines a shared API between the <a>MockT</a> and
--   <a>MockSetup</a> monads.
class MockContext ctx

-- | Adds a handler for unexpected actions. Matching calls will not fail,
--   but will use a default response instead. The rule passed in must have
--   zero or one responses: if there is a response,
--   <tt><a>allowUnexpected</a> (m <a>|=&gt;</a> r)</tt> is equivalent to
--   <tt><a>allowUnexpected</a> m &gt;&gt; <a>byDefault</a> (m
--   <a>|=&gt;</a> r)</tt>.
--   
--   The difference between <a>expectAny</a> and <a>allowUnexpected</a> is
--   subtle, but comes down to ambiguity:
--   
--   <ul>
--   <li><a>allowUnexpected</a> is not an expectation, so it cannot be
--   ambiguous. It only has an effect if no true expectation matches,
--   regardless of when the expectations were added.</li>
--   <li><a>expectAny</a> adds an expectation, so if another expectation is
--   in effect at the same time, a call to the method is ambiguous. If
--   ambiguity checking is enabled, the method will throw an error;
--   otherwise, the more recently added of the two expectations is
--   used.</li>
--   </ul>
allowUnexpected :: forall cls name m r rule ctx. (MonadIO m, MockableMethod cls name m r, Expectable cls name m r rule, MockContext ctx) => rule -> ctx m ()

-- | Sets a default action for *expected* matching calls. The new default
--   only applies to calls for which an expectation exists, but it lacks an
--   explicit response. The rule passed in must have exactly one response.
byDefault :: forall cls name m r ctx. (MonadIO m, MockableMethod cls name m r, MockContext ctx) => Rule cls name m r -> ctx m ()

-- | Adds a side-effect, which happens whenever a matching call occurs, in
--   addition to the usual response. The return value is entirely ignored.
--   
--   Be warned: using side effects makes it easy to break abstraction
--   boundaries. Be aware that there may be other uses of a method besides
--   the one which you intend to intercept here. If possible, add the
--   desired behavior to the response for the matching expectation instead.
whenever :: forall cls name m r ctx. (MonadIO m, MockableMethod cls name m r, MockContext ctx) => Rule cls name m r -> ctx m ()


-- | Functions to delegate <a>Action</a>s to HMock to match expectations.
--   There is one delegation function that works if the return type has a
--   <a>Default</a> instance, and another that doesn't require the
--   <a>Default</a> instance, but causes the method to return
--   <a>undefined</a> by default.
module Test.HMock.MockMethod

-- | Implements a method in a <a>Mockable</a> monad by delegating to the
--   mock framework. If the method is called unexpectedly, an exception
--   will be thrown. However, an expected invocation without a specified
--   response will return the default value.
mockMethod :: (HasCallStack, MonadIO m, MockableMethod cls name m r, Default r) => Action cls name m r -> MockT m r

-- | Implements a method in a <a>Mockable</a> monad by delegating to the
--   mock framework. If the method is called unexpectedly, an exception
--   will be thrown. However, an expected invocation without a specified
--   response will return undefined. This can be used in place of
--   <a>mockMethod</a> when the return type has no default.
mockDefaultlessMethod :: (HasCallStack, MonadIO m, MockableMethod cls name m r) => Action cls name m r -> MockT m r


-- | This module provides Template Haskell splices that can be used to
--   derive boilerplate instances for HMock. <a>makeMockable</a> implements
--   the common case where you just want to generate everything you need to
--   mock with a class. The variant <a>makeMockableWithOptions</a> is
--   similar, but takes an options parameter that can be used to customize
--   the generation.
module Test.HMock.TH

-- | Custom options for deriving <a>MockableBase</a> and related instances.
data MakeMockableOptions
MakeMockableOptions :: Bool -> Bool -> String -> Bool -> MakeMockableOptions

-- | Whether to generate a <a>Mockable</a> instance with an empty setup.
--   Defaults to <a>True</a>.
--   
--   If this is <a>False</a>, you are responsible for providing a
--   <a>Mockable</a> instance as follows:
--   
--   <pre>
--   instance <a>Mockable</a> MyClass where
--     <a>setupMockable</a> _ = ...
--   </pre>
[mockEmptySetup] :: MakeMockableOptions -> Bool

-- | Whether to derive instances of the class for <a>MockT</a> or not.
--   Defaults to <a>True</a>.
--   
--   This option will cause a build error if some members of the class are
--   unmockable or are not methods. In this case, you'll need to define
--   this instance yourself, delegating the mockable methods as follows:
--   
--   <pre>
--   instance MyClass (<a>MockT</a> m) where
--     myMethod x y = <a>mockMethod</a> (MyMethod x y)
--     ...
--   </pre>
[mockDeriveForMockT] :: MakeMockableOptions -> Bool

-- | Suffix to add to <a>Action</a> and <a>Matcher</a> names. Defaults to
--   <tt>""</tt>.
[mockSuffix] :: MakeMockableOptions -> String

-- | Whether to warn about limitations of the generated mocks. This is
--   mostly useful temporarily for finding out why generated code doesn't
--   match your expectations. Defaults to <tt><a>False</a></tt>.
[mockVerbose] :: MakeMockableOptions -> Bool

-- | Defines all instances necessary to use HMock with the given type,
--   using default options. The type should be a type class extending
--   <a>Monad</a>, applied to zero or more type arguments.
--   
--   This defines all of the following instances, if necessary:
--   
--   <ul>
--   <li><a>MockableBase</a> and the associated <a>Action</a> and
--   <a>Matcher</a> types.</li>
--   <li><a>Expectable</a> instances for the <a>Action</a> type.</li>
--   <li><a>Mockable</a> with an empty setup.</li>
--   <li>Instances of the provided application type class to allow unit
--   tests to be run with the <a>MockT</a> monad transformer.</li>
--   </ul>
makeMockable :: Q Type -> Q [Dec]

-- | Defines all instances necessary to use HMock with the given type,
--   using the provided options. The type should be a type class extending
--   <a>Monad</a>, applied to zero or more type arguments.
--   
--   This defines the following instances, if necessary:
--   
--   <ul>
--   <li><a>MockableBase</a> and the associated <a>Action</a> and
--   <a>Matcher</a> types.</li>
--   <li><a>Expectable</a> instances for the <a>Action</a> type.</li>
--   <li>If <a>mockEmptySetup</a> is <a>True</a>: <a>Mockable</a> with an
--   empty setup.</li>
--   <li>If <a>mockDeriveForMockT</a> is <a>True</a>: Instances of the
--   provided application type class to allow unit tests to be run with the
--   <a>MockT</a> monad transformer.</li>
--   </ul>
makeMockableWithOptions :: Q Type -> MakeMockableOptions -> Q [Dec]
instance GHC.Show.Show Test.HMock.TH.Method
instance GHC.Show.Show Test.HMock.TH.Instance
instance Data.Default.Class.Default Test.HMock.TH.MakeMockableOptions


-- | This module provides a monad transformer, <a>MockT</a>, which can be
--   used to test with mocks of Haskell <tt>mtl</tt>-style type classes. To
--   use a mock, you define the expected actions and their results, and
--   then run the code you are testing. The framework verifies that the
--   behavior of the code matched your expectations.
--   
--   For an introduction to the idea of mocks, see <a>Mocks Aren't
--   Stubs</a>, by Martin Fowler.
--   
--   WARNING: Hmock's API is likely to change soon. Please ensure you use
--   an upper bound on the version number. The current API works fine for
--   mocking with MTL-style classes. I want HMock to also work with effect
--   systems, servant, haxl, and more. To accomplish this, I'll need to
--   make breaking changes to the API.
--   
--   Suppose you have a <tt>MonadFilesystem</tt> typeclass, which is
--   instantiated by monads that implement filesystem operations:
--   
--   <pre>
--   class <a>Monad</a> m =&gt; MonadFilesystem m where
--     readFile :: <a>FilePath</a> -&gt; m <a>String</a>
--     writeFile :: <a>FilePath</a> -&gt; <a>String</a> -&gt; m ()
--   </pre>
--   
--   You can use HMock to test code using <tt>MonadFilesystem</tt> like
--   this:
--   
--   <pre>
--   copyFile :: MonadFilesystem m =&gt; <a>FilePath</a> -&gt; <a>FilePath</a> -&gt; m ()
--   copyFile a b = readFile a &gt;&gt;= writeFile b
--   
--   <a>makeMockable</a> [t|MonadFilesystem|]
--   
--   spec = describe "copyFile" <a>$</a>
--     it "reads a file and writes its contents to another file" <a>$</a>
--       <a>runMockT</a> <a>$</a> do
--         <a>expect</a> <a>$</a> ReadFile "foo.txt" <a>|-&gt;</a> "contents"
--         <a>expect</a> <a>$</a> WriteFile "bar.txt" "contents" <a>|-&gt;</a> ()
--         copyFile "foo.txt" "bar.txt"
--   </pre>
--   
--   The Template Haskell splice, <a>makeMockable</a>, generates the
--   boilerplate needed to use <tt>MonadFilesystem</tt> with HMock. You
--   then use <a>runMockT</a> to begin a test with mocks, <a>expect</a> to
--   set up your expected actions and responses, and finally execute your
--   code.
module Test.HMock