Stability	unstable
Safe Haskell	Safe-Inferred
Language	Haskell2010

Test.Hspec.Core.Spec

Contents

Defining a spec
The SpecM monad
A type class for examples
Internal representation of a spec tree
Re-exports

Description

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!

Synopsis

it :: (HasCallStack, Example a) => String -> a -> SpecWith (Arg a)
specify :: (HasCallStack, Example a) => String -> a -> SpecWith (Arg a)
describe :: HasCallStack => String -> SpecWith a -> SpecWith a
context :: HasCallStack => String -> SpecWith a -> SpecWith a
pending :: HasCallStack => Expectation
pendingWith :: HasCallStack => String -> Expectation
xit :: (HasCallStack, Example a) => String -> a -> SpecWith (Arg a)
xspecify :: (HasCallStack, Example a) => String -> a -> SpecWith (Arg a)
xdescribe :: HasCallStack => String -> SpecWith a -> SpecWith a
xcontext :: HasCallStack => String -> SpecWith a -> SpecWith a
focus :: SpecWith a -> SpecWith a
fit :: (HasCallStack, Example a) => String -> a -> SpecWith (Arg a)
fspecify :: (HasCallStack, Example a) => String -> a -> SpecWith (Arg a)
fdescribe :: HasCallStack => String -> SpecWith a -> SpecWith a
fcontext :: HasCallStack => String -> SpecWith a -> SpecWith a
parallel :: SpecWith a -> SpecWith a
sequential :: SpecWith a -> SpecWith a
type Spec = SpecWith ()
type SpecWith a = SpecM a ()
newtype SpecM a r = SpecM (WriterT (Endo Config, [SpecTree a]) (ReaderT Env IO) r)
runSpecM :: SpecWith a -> IO (Endo Config, [SpecTree a])
fromSpecList :: [SpecTree a] -> SpecWith a
runIO :: IO r -> SpecM a r
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
getSpecDescriptionPath :: SpecM a [String]
class Example e where
- type Arg e
- evaluateExample :: e -> Params -> (ActionWith (Arg e) -> IO ()) -> ProgressCallback -> IO Result
data Params = Params {
- paramsQuickCheckArgs :: Args
- paramsSmallCheckDepth :: Maybe Int
}
defaultParams :: Params
type ActionWith a = a -> IO ()
type Progress = (Int, Int)
type ProgressCallback = Progress -> IO ()
data Result = Result {
- resultInfo :: String
- resultStatus :: ResultStatus
}
data ResultStatus
- = Success
- | Pending (Maybe Location) (Maybe String)
- | Failure (Maybe Location) FailureReason
data Location = Location {
- locationFile :: FilePath
- locationLine :: Int
- locationColumn :: Int
}
data FailureReason
- = NoReason
- | Reason String
- | ColorizedReason String
- | ExpectedButGot (Maybe String) String String
- | Error (Maybe String) SomeException
safeEvaluate :: IO Result -> IO Result
safeEvaluateExample :: Example e => e -> Params -> (ActionWith (Arg e) -> IO ()) -> ProgressCallback -> IO Result
type SpecTree a = Tree (IO ()) (Item a)
data Tree c a
- = Node String [Tree c a]
- | NodeWithCleanup (Maybe (String, Location)) c [Tree c a]
- | Leaf a
data Item a = Item {
- itemRequirement :: String
- itemLocation :: Maybe Location
- itemIsParallelizable :: Maybe Bool
- itemIsFocused :: Bool
- itemExample :: Params -> (ActionWith a -> IO ()) -> ProgressCallback -> IO Result
}
specGroup :: HasCallStack => String -> [SpecTree a] -> SpecTree a
specItem :: (HasCallStack, Example e) => String -> e -> SpecTree (Arg e)
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]
type HasCallStack = ?callStack :: CallStack
type Expectation = Assertion

Defining a spec

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

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) Source #

specify is an alias for it.

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

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

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

context is an alias for describe.

pending :: HasCallStack => Expectation Source #

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 Source #

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) Source #

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) Source #

xspecify is an alias for xit.

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

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 Source #

xcontext is an alias for xdescribe.

focus :: SpecWith a -> SpecWith a Source #

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) Source #

fit is an alias for fmap focus . it

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

fspecify is an alias for fit.

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

fdescribe is an alias for fmap focus . describe

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

fcontext is an alias for fdescribe.

parallel :: SpecWith a -> SpecWith a Source #

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

sequential :: SpecWith a -> SpecWith a Source #

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

The `SpecM` monad

type Spec = SpecWith () Source #

type SpecWith a = SpecM a () Source #

newtype SpecM a r Source #

A writer monad for SpecTree forests

Constructors

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

Instances

Instances details

Applicative (SpecM a) Source #
Instance details 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 #
Functor (SpecM a) Source #
Instance details Defined in Test.Hspec.Core.Spec.Monad Methods fmap :: (a0 -> b) -> SpecM a a0 -> SpecM a b # (<$) :: a0 -> SpecM a b -> SpecM a a0 #
Monad (SpecM a) Source #
Instance details 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 #

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

Convert a Spec to a forest of SpecTrees.

fromSpecList :: [SpecTree a] -> SpecWith a Source #

Create a Spec from a forest of SpecTrees.

runIO :: IO r -> SpecM a r Source #

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 Source #

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

Deprecated: Use mapSpecItem_ instead.

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

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

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

Since: 2.10.0

getSpecDescriptionPath :: SpecM a [String] Source #

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

Example

Expand

>>> :{
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 Source #

A type class for examples

Associated Types

type Arg e Source #

type Arg e = ()

Methods

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

Instances

Instances details

Example Property Source #
Instance details Defined in Test.Hspec.Core.QuickCheck Associated Types type Arg Property Source # Methods evaluateExample :: Property -> Params -> (ActionWith (Arg Property) -> IO ()) -> ProgressCallback -> IO Result Source #
Example Result Source #
Instance details Defined in Test.Hspec.Core.Example Associated Types type Arg Result Source # Methods evaluateExample :: Result -> Params -> (ActionWith (Arg Result) -> IO ()) -> ProgressCallback -> IO Result Source #
Example Expectation Source #
Instance details Defined in Test.Hspec.Core.Example Associated Types type Arg Expectation Source # Methods evaluateExample :: Expectation -> Params -> (ActionWith (Arg Expectation) -> IO ()) -> ProgressCallback -> IO Result Source #
Example Bool Source #
Instance details Defined in Test.Hspec.Core.Example Associated Types type Arg Bool Source # Methods evaluateExample :: Bool -> Params -> (ActionWith (Arg Bool) -> IO ()) -> ProgressCallback -> IO Result Source #
Example (a -> Property) Source #
Instance details Defined in Test.Hspec.Core.QuickCheck Associated Types type Arg (a -> Property) Source # Methods evaluateExample :: (a -> Property) -> Params -> (ActionWith (Arg (a -> Property)) -> IO ()) -> ProgressCallback -> IO Result Source #
Example (a -> Result) Source #
Instance details Defined in Test.Hspec.Core.Example Associated Types type Arg (a -> Result) Source # Methods evaluateExample :: (a -> Result) -> Params -> (ActionWith (Arg (a -> Result)) -> IO ()) -> ProgressCallback -> IO Result Source #
Example (a -> Expectation) Source #
Instance details Defined in Test.Hspec.Core.Example Associated Types type Arg (a -> Expectation) Source # Methods evaluateExample :: (a -> Expectation) -> Params -> (ActionWith (Arg (a -> Expectation)) -> IO ()) -> ProgressCallback -> IO Result Source #
Example (a -> Bool) Source #
Instance details Defined in Test.Hspec.Core.Example Associated Types type Arg (a -> Bool) Source # Methods evaluateExample :: (a -> Bool) -> Params -> (ActionWith (Arg (a -> Bool)) -> IO ()) -> ProgressCallback -> IO Result Source #

data Params Source #

Constructors

Params
Fields paramsQuickCheckArgs :: Args paramsSmallCheckDepth :: Maybe Int

Instances

Instances details

Show Params Source #
Instance details Defined in Test.Hspec.Core.Example Methods showsPrec :: Int -> Params -> ShowS # show :: Params -> String # showList :: [Params] -> ShowS #

defaultParams :: Params Source #

type ActionWith a = a -> IO () Source #

An IO action that expects an argument of type a

type Progress = (Int, Int) Source #

type ProgressCallback = Progress -> IO () Source #

data Result Source #

The result of running an example

Constructors

Result
Fields resultInfo :: String resultStatus :: ResultStatus

Instances

Instances details

Show Result Source #
Instance details Defined in Test.Hspec.Core.Example Methods showsPrec :: Int -> Result -> ShowS # show :: Result -> String # showList :: [Result] -> ShowS #
Example Result Source #
Instance details Defined in Test.Hspec.Core.Example Associated Types type Arg Result Source # Methods evaluateExample :: Result -> Params -> (ActionWith (Arg Result) -> IO ()) -> ProgressCallback -> IO Result Source #
Example (a -> Result) Source #
Instance details Defined in Test.Hspec.Core.Example Associated Types type Arg (a -> Result) Source # Methods evaluateExample :: (a -> Result) -> Params -> (ActionWith (Arg (a -> Result)) -> IO ()) -> ProgressCallback -> IO Result Source #
type Arg Result Source #
Instance details Defined in Test.Hspec.Core.Example type Arg Result = ()
type Arg (a -> Result) Source #
Instance details Defined in Test.Hspec.Core.Example type Arg (a -> Result) = a

data ResultStatus Source #

Constructors

Success
Pending (Maybe Location) (Maybe String)
Failure (Maybe Location) FailureReason

Instances

Instances details

Exception ResultStatus Source #
Instance details Defined in Test.Hspec.Core.Example Methods toException :: ResultStatus -> SomeException # fromException :: SomeException -> Maybe ResultStatus # displayException :: ResultStatus -> String #
Show ResultStatus Source #
Instance details Defined in Test.Hspec.Core.Example Methods showsPrec :: Int -> ResultStatus -> ShowS # show :: ResultStatus -> String # showList :: [ResultStatus] -> ShowS #

data Location Source #

Location is used to represent source locations.

Constructors

Location
Fields locationFile :: FilePath locationLine :: Int locationColumn :: Int

Instances

Instances details

Read Location Source #
Instance details Defined in Test.Hspec.Core.Example.Location Methods readsPrec :: Int -> ReadS Location # readList :: ReadS [Location] # readPrec :: ReadPrec Location # readListPrec :: ReadPrec [Location] #
Show Location Source #
Instance details Defined in Test.Hspec.Core.Example.Location Methods showsPrec :: Int -> Location -> ShowS # show :: Location -> String # showList :: [Location] -> ShowS #
Eq Location Source #
Instance details Defined in Test.Hspec.Core.Example.Location Methods (==) :: Location -> Location -> Bool # (/=) :: Location -> Location -> Bool #

data FailureReason Source #

Constructors

NoReason
Reason String
ColorizedReason String
ExpectedButGot (Maybe String) String String
Error (Maybe String) SomeException

Instances

Instances details

Show FailureReason Source #
Instance details Defined in Test.Hspec.Core.Example Methods showsPrec :: Int -> FailureReason -> ShowS # show :: FailureReason -> String # showList :: [FailureReason] -> ShowS #
NFData FailureReason Source #
Instance details Defined in Test.Hspec.Core.Example Methods rnf :: FailureReason -> () #

safeEvaluate :: IO Result -> IO Result Source #

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

Internal representation of a spec tree

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

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 Source #

Internal tree data structure

Constructors

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

Instances

Instances details

Foldable (Tree c) Source #
Instance details 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) Source #
Instance details 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) #
Functor (Tree c) Source #
Instance details Defined in Test.Hspec.Core.Tree Methods fmap :: (a -> b) -> Tree c a -> Tree c b # (<$) :: a -> Tree c b -> Tree c a #
(Show c, Show a) => Show (Tree c a) Source #
Instance details Defined in Test.Hspec.Core.Tree Methods showsPrec :: Int -> Tree c a -> ShowS # show :: Tree c a -> String # showList :: [Tree c a] -> ShowS #
(Eq c, Eq a) => Eq (Tree c a) Source #
Instance details Defined in Test.Hspec.Core.Tree Methods (==) :: Tree c a -> Tree c a -> Bool # (/=) :: Tree c a -> Tree c a -> Bool #

data Item a Source #

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 Source #

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

specItem :: (HasCallStack, Example e) => String -> e -> SpecTree (Arg e) Source #

The specItem function creates a spec item.

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

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

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

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

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

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

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

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

location :: HasCallStack => Maybe Location Source #

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

Re-exports

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

type Expectation = Assertion #

Defining a spec

The SpecM monad

Instances

Example

A type class for examples

Instances

Instances

Instances

Instances

Instances

Instances

Internal representation of a spec tree

Instances

Re-exports

The `SpecM` monad