hspec-effectful
Copyright(c) 2026 Institute for Digital Autonomy
LicenseEUPL-1.2
MaintainerIDA
Safe HaskellTrustworthy
LanguageHaskell2010

Effectful.Hspec

Description

Effectful bindings for the Hspec library built on top of hunit-effectful.

Overview

This library provides Hspec's test combinators expressed in terms of the Hspec effect. This effect allows you to intersperse test assertions with arbitrary other effects.

Example usage

Suppose we wish to test stateful operations on an account balance:

deposit :: (State Int :> es) => Int -> Eff es ()
deposit amount = modify (+ amount)

balance :: (State Int :> es) => Eff es Int
balance = get
withdraw :: (State Int :> es) => Int -> Eff es Bool
withdraw amount = do
    funds <- balance
    if funds < amount
        then pure False
        else do
            put $ funds - amount
            pure True

Use describe to group related examples, it to state individual expectations and setup/teardown combinators such as before_, after_, or around_ to run the examples from a known initial state:

accountSpec :: (State Int :> es, Hspec :> es) => Eff es ()
accountSpec = describe "account" . before_ (put @Int 0) $ do
    it "accumulates deposits" $ do
        deposit 100
        deposit 50
        balance `shouldReturn` 150

    it "checks for sufficient funds before withdrawing" $ do
        deposit 100
        withdraw 30 `shouldReturn` True
        withdraw 1000 `shouldReturn` False
        balance `shouldReturn` 70

Finally, run the spec with runHspec, which also resolves the underlying HUnit effect:

main :: IO ()
main = runEff . runHspec . evalState @Int 0 $ accountSpec
Synopsis

Effect

data Hspec (a :: Type -> Type) b Source #

Instances

Instances details
type DispatchOf Hspec Source # 
Instance details

Defined in Effectful.Hspec

type DispatchOf Hspec = 'Static 'WithSideEffects
data StaticRep Hspec Source # 
Instance details

Defined in Effectful.Hspec

data StaticRep Hspec = Hspec {}

type Expectation (es :: [Effect]) = Assertion es Source #

runHspecWith' :: forall (es :: [Effect]) a. (IOE :> es, HUnit :> es) => Config -> Eff (Hspec ': es) a -> Eff es a Source #

runHspecWith :: forall (es :: [Effect]) a. IOE :> es => Config -> Eff (Hspec ': es) a -> Eff es a Source #

runHspec' :: forall (es :: [Effect]) a. (IOE :> es, HUnit :> es) => Eff (Hspec ': es) a -> Eff es a Source #

runHspec :: forall (es :: [Effect]) a. IOE :> es => Eff (Hspec ': es) a -> Eff es a Source #

runHUnit :: forall (es :: [Effect]) a. IOE :> es => Eff (HUnit ': es) a -> Eff es a #

Spec construction

describe :: forall (es :: [Effect]) a. (HasCallStack, Hspec :> es) => String -> Eff es a -> Eff es a Source #

Lifted describe.

context :: forall (es :: [Effect]) a. (HasCallStack, Hspec :> es) => String -> Eff es a -> Eff es a Source #

Lifted context.

it :: forall (es :: [Effect]). (HasCallStack, Hspec :> es) => String -> Eff es () -> Eff es () Source #

Lifted it.

specify :: forall (es :: [Effect]). (HasCallStack, Hspec :> es) => String -> Eff es () -> Eff es () Source #

Lifted specify.

pending :: forall (es :: [Effect]). (HasCallStack, Hspec :> es) => Eff es () Source #

Lifted pending.

pendingWith :: forall (es :: [Effect]). (HasCallStack, Hspec :> es) => String -> Eff es () Source #

Lifted pendingWith.

Skipping

xit :: forall (es :: [Effect]). (HasCallStack, Hspec :> es) => String -> Eff es () -> Eff es () Source #

Lifted xit.

xspecify :: forall (es :: [Effect]). (HasCallStack, Hspec :> es) => String -> Eff es () -> Eff es () Source #

Lifted xspecify.

xdescribe :: forall (es :: [Effect]) a. (HasCallStack, Hspec :> es) => String -> Eff es a -> Eff es a Source #

Lifted xdescribe.

xcontext :: forall (es :: [Effect]) a. (HasCallStack, Hspec :> es) => String -> Eff es a -> Eff es a Source #

Lifted xcontext.

Focusing

focus :: forall (es :: [Effect]) a. (HasCallStack, Hspec :> es) => Eff es a -> Eff es a Source #

Lifted focus.

fit :: forall (es :: [Effect]). (HasCallStack, Hspec :> es) => String -> Eff es () -> Eff es () Source #

Lifted fit.

fspecify :: forall (es :: [Effect]). (HasCallStack, Hspec :> es) => String -> Eff es () -> Eff es () Source #

Lifted fspecify.

fdescribe :: forall (es :: [Effect]) a. (HasCallStack, Hspec :> es) => String -> Eff es a -> Eff es a Source #

Lifted fdescribe.

fcontext :: forall (es :: [Effect]) a. (HasCallStack, Hspec :> es) => String -> Eff es a -> Eff es a Source #

Lifted fcontext.

parallel :: forall (es :: [Effect]) a. (HasCallStack, Hspec :> es) => Eff es a -> Eff es a Source #

Lifted parallel.

sequential :: forall (es :: [Effect]) a. (HasCallStack, Hspec :> es) => Eff es a -> Eff es a Source #

Lifted sequential.

Setup / Teardown

before_ :: forall (es :: [Effect]) a. (HasCallStack, Hspec :> es) => Eff es () -> Eff es a -> Eff es a Source #

Lifted before_.

beforeAll_ :: forall (es :: [Effect]) a. (HasCallStack, Hspec :> es) => Eff es () -> Eff es a -> Eff es a Source #

Lifted beforeAll_.

after_ :: forall (es :: [Effect]) a. (HasCallStack, Hspec :> es) => Eff es () -> Eff es a -> Eff es a Source #

Lifted after_.

afterAll_ :: forall (es :: [Effect]) a. (HasCallStack, Hspec :> es) => Eff es () -> Eff es a -> Eff es a Source #

Lifted afterAll_.

around_ :: forall (es :: [Effect]) a. (HasCallStack, Hspec :> es) => (Eff es () -> Eff es ()) -> Eff es a -> Eff es a Source #

Lifted around_.

aroundAll_ :: forall (es :: [Effect]) a. (HasCallStack, Hspec :> es) => (Eff es () -> Eff es ()) -> Eff es a -> Eff es a Source #

Lifted aroundAll_.

Expectations

expectationFailure :: forall (es :: [Effect]). (HasCallStack, Hspec :> es) => String -> Expectation es Source #

shouldBe :: forall a (es :: [Effect]). (HasCallStack, Show a, Eq a, Hspec :> es) => a -> a -> Expectation es infix 1 Source #

actual `shouldBe` expected sets the expectation that actual is equal to expected.

shouldSatisfy :: forall a (es :: [Effect]). (HasCallStack, Show a, Hspec :> es) => a -> (a -> Bool) -> Expectation es infix 1 Source #

v `shouldSatisfy` p sets the expectation that p v is True.

shouldStartWith :: forall a (es :: [Effect]). (HasCallStack, Show a, Eq a, Hspec :> es) => [a] -> [a] -> Expectation es infix 1 Source #

list `shouldStartWith` prefix sets the expectation that list starts with prefix.

shouldEndWith :: forall a (es :: [Effect]). (HasCallStack, Show a, Eq a, Hspec :> es) => [a] -> [a] -> Expectation es infix 1 Source #

list `shouldEndWith` suffix sets the expectation that list ends with suffix.

shouldContain :: forall a (es :: [Effect]). (HasCallStack, Show a, Eq a, Hspec :> es) => [a] -> [a] -> Expectation es infix 1 Source #

list `shouldContain` sublist sets the expectation that sublist is contained, wholly and intact, anywhere in list.

shouldMatchList :: forall a (es :: [Effect]). (HasCallStack, Show a, Eq a, Hspec :> es) => [a] -> [a] -> Expectation es infix 1 Source #

xs `shouldMatchList` ys sets the expectation that xs has the same elements that ys has, possibly in another order.

shouldReturn :: forall a (es :: [Effect]). (HasCallStack, Show a, Eq a, Hspec :> es) => Eff es a -> a -> Expectation es infix 1 Source #

action `shouldReturn` expected sets the expectation that action returns expected.

shouldNotBe :: forall a (es :: [Effect]). (HasCallStack, Show a, Eq a, Hspec :> es) => a -> a -> Expectation es infix 1 Source #

actual `shouldNotBe` notExpected sets the expectation that actual is not equal to notExpected.

shouldNotSatisfy :: forall a (es :: [Effect]). (HasCallStack, Show a, Hspec :> es) => a -> (a -> Bool) -> Expectation es infix 1 Source #

v `shouldNotSatisfy` p sets the expectation that p v is False.

shouldNotContain :: forall a (es :: [Effect]). (HasCallStack, Show a, Eq a, Hspec :> es) => [a] -> [a] -> Expectation es infix 1 Source #

list `shouldNotContain` sublist sets the expectation that sublist is not contained anywhere in list.

shouldNotReturn :: forall a (es :: [Effect]). (HasCallStack, Show a, Eq a, Hspec :> es) => Eff es a -> a -> Expectation es infix 1 Source #

action `shouldNotReturn` notExpected sets the expectation that action does not return notExpected.

shouldThrow :: forall e (es :: [Effect]) a. (HasCallStack, Exception e, Hspec :> es) => Eff es a -> Selector e -> Expectation es infix 1 Source #

action `shouldThrow` selector sets the expectation that action throws an exception. The precise nature of the expected exception is described with a Selector.

anyException :: Selector SomeException #

data Config #

Constructors

Config 

Fields

defaultConfig :: Config #

type Spec = SpecWith () #

A SpecWith that can be evaluated directly by the hspec function as it does not require any parameters.

type HasCallStack = ?callStack :: CallStack #

Request a CallStack.

NOTE: The implicit parameter ?callStack :: CallStack is an implementation detail and should not be considered part of the CallStack API, we may decide to change the implementation in the future.

Since: base-4.9.0.0

Properties

prop :: forall prop (es :: [Effect]). (HasCallStack, Testable prop, Hspec :> es) => String -> prop -> Eff es () Source #

Lifted prop.

xprop :: forall prop (es :: [Effect]). (HasCallStack, Testable prop, Hspec :> es) => String -> prop -> Eff es () Source #

Lifted xprop.

fprop :: forall prop (es :: [Effect]). (HasCallStack, Testable prop, Hspec :> es) => String -> prop -> Eff es () Source #

Lifted fprop.