Test.Hspec.Core.Spec

This module provides access to Hspec's internals. It is less stable than other parts of the API. For most users Test.Hspec is more suitable!

Defining a spec

it :: (HasCallStack, Example a) => String -> a -> SpecWith (Arg a)

The it function creates a spec item.

A spec item consists of:

• a textual description of a desired behavior
• an example for that behavior

describe "absolute" $ do
  it "returns a positive number when given a negative number" $
    absolute (-1) == 1

specify :: (HasCallStack, Example a) => String -> a -> SpecWith (Arg a)

specify is an alias for it.

describe :: HasCallStack => String -> SpecWith a -> SpecWith a

The describe function combines a list of specs into a larger spec.

context :: HasCallStack => String -> SpecWith a -> SpecWith a

context is an alias for describe.

pending :: HasCallStack => Expectation

pending can be used to mark a spec item as pending.

If you want to textually specify a behavior but do not have an example yet, use this:

describe "fancyFormatter" $ do
  it "can format text in a way that everyone likes" $
    pending

pendingWith :: HasCallStack => String -> Expectation

pendingWith is similar to pending, but it takes an additional string argument that can be used to specify the reason for why the spec item is pending.

xit :: (HasCallStack, Example a) => String -> a -> SpecWith (Arg a)

Changing it to xit marks the corresponding spec item as pending.

This can be used to temporarily disable a spec item.

xspecify :: (HasCallStack, Example a) => String -> a -> SpecWith (Arg a)

xspecify is an alias for xit.

xdescribe :: HasCallStack => String -> SpecWith a -> SpecWith a

Changing describe to xdescribe marks all spec items of the corresponding subtree as pending.

This can be used to temporarily disable spec items.

xcontext :: HasCallStack => String -> SpecWith a -> SpecWith a

xcontext is an alias for xdescribe.

focus :: SpecWith a -> SpecWith a

focus focuses all spec items of the given spec.

Applying focus to a spec with focused spec items has no effect.

fit :: (HasCallStack, Example a) => String -> a -> SpecWith (Arg a)

fit is an alias for fmap focus . it

fspecify :: (HasCallStack, Example a) => String -> a -> SpecWith (Arg a)

fspecify is an alias for fit.

fdescribe :: HasCallStack => String -> SpecWith a -> SpecWith a

fdescribe is an alias for fmap focus . describe

fcontext :: HasCallStack => String -> SpecWith a -> SpecWith a

fcontext is an alias for fdescribe.

parallel :: SpecWith a -> SpecWith a

parallel marks all spec items of the given spec to be safe for parallel evaluation.

sequential :: SpecWith a -> SpecWith a

sequential marks all spec items of the given spec to be evaluated sequentially.

The SpecM monad

type Spec = SpecWith ()

type SpecWith a = SpecM a ()

newtype SpecM a r

A writer monad for SpecTree forests

Constructors

SpecM (WriterT (Endo Config, [SpecTree a]) (ReaderT Env IO) r)

Instances

Monad (SpecM a)

Defined in Test.Hspec.Core.Spec.Monad

Methods

(>>=) :: SpecM a a0 -> (a0 -> SpecM a b) -> SpecM a b

(>>) :: SpecM a a0 -> SpecM a b -> SpecM a b

return :: a0 -> SpecM a a0

Functor (SpecM a)

Defined in Test.Hspec.Core.Spec.Monad

Methods

fmap :: (a0 -> b) -> SpecM a a0 -> SpecM a b

(<$) :: a0 -> SpecM a b -> SpecM a a0

Applicative (SpecM a)

Defined in Test.Hspec.Core.Spec.Monad

Methods

pure :: a0 -> SpecM a a0

(<*>) :: SpecM a (a0 -> b) -> SpecM a a0 -> SpecM a b

liftA2 :: (a0 -> b -> c) -> SpecM a a0 -> SpecM a b -> SpecM a c

(*>) :: SpecM a a0 -> SpecM a b -> SpecM a b

(<*) :: SpecM a a0 -> SpecM a b -> SpecM a a0

runSpecM :: SpecWith a -> IO (Endo Config, [SpecTree a])

Convert a Spec to a forest of SpecTrees.

fromSpecList :: [SpecTree a] -> SpecWith a

Create a Spec from a forest of SpecTrees.

runIO :: IO r -> SpecM a r

Run an IO action while constructing the spec tree.

SpecM is a monad to construct a spec tree, without executing any spec items. runIO allows you to run IO actions during this construction phase. The IO action is always run when the spec tree is constructed (e.g. even when --dry-run is specified). If you do not need the result of the IO action to construct the spec tree, beforeAll may be more suitable for your use case.

mapSpecForest :: ([SpecTree a] -> [SpecTree b]) -> SpecM a r -> SpecM b r

mapSpecItem :: (ActionWith a -> ActionWith b) -> (Item a -> Item b) -> SpecWith a -> SpecWith b

mapSpecItem_ :: (Item a -> Item b) -> SpecWith a -> SpecWith b

modifyParams :: (Params -> Params) -> SpecWith a -> SpecWith a

modifyConfig :: (Config -> Config) -> SpecWith a

Since: 2.10.0

getSpecDescriptionPath :: SpecM a [String]

Get the path of describe labels, from the root all the way in to the call-site of this function.

Example

>>> :{
runSpecM $ do
  describe "foo" $ do
    describe "bar" $ do
      getSpecDescriptionPath >>= runIO . print
:}
["foo","bar"]

Since: 2.10.0

A type class for examples

class Example e where

A type class for examples

Associated Types

type Arg e

type Arg e = ()

Methods

evaluateExample :: e -> Params -> (ActionWith (Arg e) -> IO ()) -> ProgressCallback -> IO Result

Instances

Example Bool

Defined in Test.Hspec.Core.Example

Associated Types

type Arg Bool

Methods

evaluateExample :: Bool -> Params -> (ActionWith (Arg Bool) -> IO ()) -> ProgressCallback -> IO Result

Example Property

Defined in Test.Hspec.Core.Example

Associated Types

type Arg Property

Methods

evaluateExample :: Property -> Params -> (ActionWith (Arg Property) -> IO ()) -> ProgressCallback -> IO Result

Example Expectation

Defined in Test.Hspec.Core.Example

Associated Types

type Arg Expectation

Methods

evaluateExample :: Expectation -> Params -> (ActionWith (Arg Expectation) -> IO ()) -> ProgressCallback -> IO Result

Example Result

Defined in Test.Hspec.Core.Example

Associated Types

type Arg Result

Methods

evaluateExample :: Result -> Params -> (ActionWith (Arg Result) -> IO ()) -> ProgressCallback -> IO Result

Example (a -> Property)

Defined in Test.Hspec.Core.Example

Associated Types

type Arg (a -> Property)

Methods

evaluateExample :: (a -> Property) -> Params -> (ActionWith (Arg (a -> Property)) -> IO ()) -> ProgressCallback -> IO Result

Example (a -> Expectation)

Defined in Test.Hspec.Core.Example

Associated Types

type Arg (a -> Expectation)

Methods

evaluateExample :: (a -> Expectation) -> Params -> (ActionWith (Arg (a -> Expectation)) -> IO ()) -> ProgressCallback -> IO Result

Example (a -> Bool)

Defined in Test.Hspec.Core.Example

Associated Types

type Arg (a -> Bool)

Methods

evaluateExample :: (a -> Bool) -> Params -> (ActionWith (Arg (a -> Bool)) -> IO ()) -> ProgressCallback -> IO Result

Example (a -> Result)

Defined in Test.Hspec.Core.Example

Associated Types

type Arg (a -> Result)

Methods

evaluateExample :: (a -> Result) -> Params -> (ActionWith (Arg (a -> Result)) -> IO ()) -> ProgressCallback -> IO Result

data Params

Constructors

Params

Fields

• paramsQuickCheckArgs :: Args
• paramsSmallCheckDepth :: Maybe Int

Instances

Show Params

Defined in Test.Hspec.Core.Example

Methods

showsPrec :: Int -> Params -> ShowS

show :: Params -> String

showList :: [Params] -> ShowS

defaultParams :: Params

type ActionWith a = a -> IO ()

An IO action that expects an argument of type a

type Progress = (Int, Int)

type ProgressCallback = Progress -> IO ()

data Result

The result of running an example

Constructors

Result

Fields

• resultInfo :: String
• resultStatus :: ResultStatus

Instances

Show Result

Defined in Test.Hspec.Core.Example

Methods

showsPrec :: Int -> Result -> ShowS

show :: Result -> String

showList :: [Result] -> ShowS

Example Result

Defined in Test.Hspec.Core.Example

Associated Types

type Arg Result

Methods

evaluateExample :: Result -> Params -> (ActionWith (Arg Result) -> IO ()) -> ProgressCallback -> IO Result

Example (a -> Result)

Defined in Test.Hspec.Core.Example

Associated Types

type Arg (a -> Result)

Methods

evaluateExample :: (a -> Result) -> Params -> (ActionWith (Arg (a -> Result)) -> IO ()) -> ProgressCallback -> IO Result

type Arg Result

Defined in Test.Hspec.Core.Example

type Arg Result = ()

type Arg (a -> Result)

Defined in Test.Hspec.Core.Example

type Arg (a -> Result) = a

data ResultStatus

Constructors

Success

Pending (Maybe Location) (Maybe String)

Failure (Maybe Location) FailureReason

Instances

Show ResultStatus

Defined in Test.Hspec.Core.Example

Methods

showsPrec :: Int -> ResultStatus -> ShowS

show :: ResultStatus -> String

showList :: [ResultStatus] -> ShowS

Exception ResultStatus

Defined in Test.Hspec.Core.Example

Methods

toException :: ResultStatus -> SomeException

fromException :: SomeException -> Maybe ResultStatus

displayException :: ResultStatus -> String

data Location

Location is used to represent source locations.

Constructors

Location

Fields

• locationFile :: FilePath
• locationLine :: Int
• locationColumn :: Int

Instances

Eq Location

Defined in Test.Hspec.Core.Example.Location

Methods

(==) :: Location -> Location -> Bool

(/=) :: Location -> Location -> Bool

Read Location

Defined in Test.Hspec.Core.Example.Location

Methods

readsPrec :: Int -> ReadS Location

readList :: ReadS [Location]

readPrec :: ReadPrec Location

readListPrec :: ReadPrec [Location]

Show Location

Defined in Test.Hspec.Core.Example.Location

Methods

showsPrec :: Int -> Location -> ShowS

show :: Location -> String

showList :: [Location] -> ShowS

data FailureReason

Constructors

NoReason

Reason String

ExpectedButGot (Maybe String) String String

Error (Maybe String) SomeException

Instances

Show FailureReason

Defined in Test.Hspec.Core.Example

Methods

showsPrec :: Int -> FailureReason -> ShowS

show :: FailureReason -> String

showList :: [FailureReason] -> ShowS

NFData FailureReason

Defined in Test.Hspec.Core.Example

Methods

rnf :: FailureReason -> ()

safeEvaluate :: IO Result -> IO Result

safeEvaluateExample :: Example e => e -> Params -> (ActionWith (Arg e) -> IO ()) -> ProgressCallback -> IO Result

Internal representation of a spec tree

type SpecTree a = Tree (IO ()) (Item a)

A tree is used to represent a spec internally. The tree is parameterized over the type of cleanup actions and the type of the actual spec items.

data Tree c a

Internal tree data structure

Constructors

Node String [Tree c a]

NodeWithCleanup (Maybe (String, Location)) c [Tree c a]

Leaf a

Instances

Functor (Tree c)

Defined in Test.Hspec.Core.Tree

Methods

fmap :: (a -> b) -> Tree c a -> Tree c b

(<$) :: a -> Tree c b -> Tree c a

Foldable (Tree c)

Defined in Test.Hspec.Core.Tree

Methods

fold :: Monoid m => Tree c m -> m

foldMap :: Monoid m => (a -> m) -> Tree c a -> m

foldMap' :: Monoid m => (a -> m) -> Tree c a -> m

foldr :: (a -> b -> b) -> b -> Tree c a -> b

foldr' :: (a -> b -> b) -> b -> Tree c a -> b

foldl :: (b -> a -> b) -> b -> Tree c a -> b

foldl' :: (b -> a -> b) -> b -> Tree c a -> b

foldr1 :: (a -> a -> a) -> Tree c a -> a

foldl1 :: (a -> a -> a) -> Tree c a -> a

toList :: Tree c a -> [a]

null :: Tree c a -> Bool

length :: Tree c a -> Int

elem :: Eq a => a -> Tree c a -> Bool

maximum :: Ord a => Tree c a -> a

minimum :: Ord a => Tree c a -> a

sum :: Num a => Tree c a -> a

product :: Num a => Tree c a -> a

Traversable (Tree c)

Defined in Test.Hspec.Core.Tree

Methods

traverse :: Applicative f => (a -> f b) -> Tree c a -> f (Tree c b)

sequenceA :: Applicative f => Tree c (f a) -> f (Tree c a)

mapM :: Monad m => (a -> m b) -> Tree c a -> m (Tree c b)

sequence :: Monad m => Tree c (m a) -> m (Tree c a)

(Eq c, Eq a) => Eq (Tree c a)

Defined in Test.Hspec.Core.Tree

Methods

(==) :: Tree c a -> Tree c a -> Bool

(/=) :: Tree c a -> Tree c a -> Bool

(Show c, Show a) => Show (Tree c a)

Defined in Test.Hspec.Core.Tree

Methods

showsPrec :: Int -> Tree c a -> ShowS

show :: Tree c a -> String

showList :: [Tree c a] -> ShowS

data Item a

Item is used to represent spec items internally. A spec item consists of:

• a textual description of a desired behavior
• an example for that behavior
• additional meta information

Everything that is an instance of the Example type class can be used as an example, including QuickCheck properties, Hspec expectations and HUnit assertions.

Constructors

Item

Fields

• itemRequirement :: String

  Textual description of behavior

• itemLocation :: Maybe Location

  Source location of the spec item

• itemIsParallelizable :: Maybe Bool

  A flag that indicates whether it is safe to evaluate this spec item in parallel with other spec items

• itemIsFocused :: Bool

  A flag that indicates whether this spec item is focused.

• itemExample :: Params -> (ActionWith a -> IO ()) -> ProgressCallback -> IO Result

  Example for behavior

specGroup :: HasCallStack => String -> [SpecTree a] -> SpecTree a

The specGroup function combines a list of specs into a larger spec.

specItem :: (HasCallStack, Example a) => String -> a -> SpecTree (Arg a)

The specItem function creates a spec item.

bimapTree :: (a -> b) -> (c -> d) -> Tree a c -> Tree b d

bimapForest :: (a -> b) -> (c -> d) -> [Tree a c] -> [Tree b d]

filterTree :: (a -> Bool) -> Tree c a -> Maybe (Tree c a)

filterForest :: (a -> Bool) -> [Tree c a] -> [Tree c a]

filterTreeWithLabels :: ([String] -> a -> Bool) -> Tree c a -> Maybe (Tree c a)

filterForestWithLabels :: ([String] -> a -> Bool) -> [Tree c a] -> [Tree c a]

pruneTree :: Tree c a -> Maybe (Tree c a)

pruneForest :: [Tree c a] -> [Tree c a]

location :: HasCallStack => Maybe Location

focusForest :: [SpecTree a] -> [SpecTree a]