Stability	unstable
Safe Haskell	None
Language	Haskell2010

Test.Hspec.Core.Spec

Contents

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

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

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 :: String -> SpecWith a -> SpecWith a Source #

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

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

context is an alias for describe.

pending :: 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 :: 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 :: 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 :: String -> SpecWith a -> SpecWith a Source #

xcontext is an alias for xdescribe.

parallel :: SpecWith a -> SpecWith a Source #

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

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 [SpecTree a] IO r)

Instances

Monad (SpecM a) Source #
Methods (>>=) :: SpecM a a -> (a -> SpecM a b) -> SpecM a b # (>>) :: SpecM a a -> SpecM a b -> SpecM a b # return :: a -> SpecM a a # fail :: String -> SpecM a a #
Functor (SpecM a) Source #
Methods fmap :: (a -> b) -> SpecM a a -> SpecM a b # (<$) :: a -> SpecM a b -> SpecM a a #
Applicative (SpecM a) Source #
Methods pure :: a -> SpecM a a # (<>) :: SpecM a (a -> b) -> SpecM a a -> SpecM a b # (>) :: SpecM a a -> SpecM a b -> SpecM a b # (<*) :: SpecM a a -> SpecM a b -> SpecM a a #

runSpecM :: SpecWith a -> IO [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.

mapSpecTree :: (SpecTree a -> SpecTree b) -> SpecWith a -> SpecWith b Source #

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

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

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

A type class for examples

class Example e where Source #

A type class for examples

Minimal complete definition

evaluateExample

Associated Types

type Arg e Source #

Methods

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

Instances

Example Bool Source #
Associated Types type Arg Bool :: * Source # Methods evaluateExample :: Bool -> Params -> (ActionWith (Arg Bool) -> IO ()) -> ProgressCallback -> IO Result Source #
Example Property Source #
Associated Types type Arg Property :: * Source # Methods evaluateExample :: Property -> Params -> (ActionWith (Arg Property) -> IO ()) -> ProgressCallback -> IO Result Source #
Example Expectation Source #
Associated Types type Arg Expectation :: * Source # Methods evaluateExample :: Expectation -> Params -> (ActionWith (Arg Expectation) -> IO ()) -> ProgressCallback -> IO Result Source #
Example Result Source #
Associated Types type Arg Result :: * Source # Methods evaluateExample :: Result -> Params -> (ActionWith (Arg Result) -> IO ()) -> ProgressCallback -> IO Result Source #
Example (a -> Property) Source #
Associated Types type Arg (a -> Property) :: * Source # Methods evaluateExample :: (a -> Property) -> Params -> (ActionWith (Arg (a -> Property)) -> IO ()) -> ProgressCallback -> IO Result Source #
Example (a -> Expectation) Source #
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 #
Associated Types type Arg (a -> Bool) :: * Source # Methods evaluateExample :: (a -> Bool) -> Params -> (ActionWith (Arg (a -> Bool)) -> IO ()) -> ProgressCallback -> IO Result Source #
Example (a -> Result) Source #
Associated Types type Arg (a -> Result) :: * Source # Methods evaluateExample :: (a -> Result) -> Params -> (ActionWith (Arg (a -> Result)) -> IO ()) -> ProgressCallback -> IO Result Source #

data Params Source #

Constructors

Params
Fields paramsQuickCheckArgs :: Args paramsSmallCheckDepth :: Int

Instances

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

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

Instances

Eq Result Source #
Methods (==) :: Result -> Result -> Bool # (/=) :: Result -> Result -> Bool #
Read Result Source #
Methods readsPrec :: Int -> ReadS Result # readList :: ReadS [Result] # readPrec :: ReadPrec Result # readListPrec :: ReadPrec [Result] #
Show Result Source #
Methods showsPrec :: Int -> Result -> ShowS # show :: Result -> String # showList :: [Result] -> ShowS #
Exception Result Source #
Methods toException :: Result -> SomeException # fromException :: SomeException -> Maybe Result # displayException :: Result -> String #
Example Result Source #
Associated Types type Arg Result :: * Source # Methods evaluateExample :: Result -> Params -> (ActionWith (Arg Result) -> IO ()) -> ProgressCallback -> IO Result Source #
Example (a -> Result) Source #
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 #
type Arg Result = ()
type Arg (a -> Result) Source #
type Arg (a -> Result) = a

data Location Source #

Location is used to represent source locations.

Constructors

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

Instances

Eq Location Source #
Methods (==) :: Location -> Location -> Bool # (/=) :: Location -> Location -> Bool #
Read Location Source #
Methods readsPrec :: Int -> ReadS Location # readList :: ReadS [Location] # readPrec :: ReadPrec Location # readListPrec :: ReadPrec [Location] #
Show Location Source #
Methods showsPrec :: Int -> Location -> ShowS # show :: Location -> String # showList :: [Location] -> ShowS #

data LocationAccuracy Source #

A marker for source locations

Constructors

ExactLocation	The source location is accurate
BestEffort	The source location was determined on a best-effort basis and my be wrong or inaccurate

Instances

Eq LocationAccuracy Source #
Methods (==) :: LocationAccuracy -> LocationAccuracy -> Bool # (/=) :: LocationAccuracy -> LocationAccuracy -> Bool #
Read LocationAccuracy Source #
Methods readsPrec :: Int -> ReadS LocationAccuracy # readList :: ReadS [LocationAccuracy] # readPrec :: ReadPrec LocationAccuracy # readListPrec :: ReadPrec [LocationAccuracy] #
Show LocationAccuracy Source #
Methods showsPrec :: Int -> LocationAccuracy -> ShowS # show :: LocationAccuracy -> String # showList :: [LocationAccuracy] -> ShowS #

data FailureReason Source #

Constructors

NoReason
Reason String
ExpectedButGot (Maybe String) String String

Instances

Eq FailureReason Source #
Methods (==) :: FailureReason -> FailureReason -> Bool # (/=) :: FailureReason -> FailureReason -> Bool #
Read FailureReason Source #
Methods readsPrec :: Int -> ReadS FailureReason # readList :: ReadS [FailureReason] # readPrec :: ReadPrec FailureReason # readListPrec :: ReadPrec [FailureReason] #
Show FailureReason Source #
Methods showsPrec :: Int -> FailureReason -> ShowS # show :: FailureReason -> String # showList :: [FailureReason] -> ShowS #
NFData FailureReason Source #
Methods rnf :: FailureReason -> () #

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

Internal representation of a spec tree

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

A tree is used to represent a spec internally. The tree is parametrize 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 c [Tree c a]
Leaf a

Instances

Functor (Tree c) Source #
Methods fmap :: (a -> b) -> Tree c a -> Tree c b # (<$) :: a -> Tree c b -> Tree c a #
Foldable (Tree c) Source #
Methods fold :: Monoid m => Tree c m -> 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 #
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) #

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 :: Bool A flag that indicates whether it is safe to evaluate this spec item in parallel with other spec items itemExample :: Params -> (ActionWith a -> IO ()) -> ProgressCallback -> IO (Either SomeException Result) Example for behavior

specGroup :: String -> [SpecTree a] -> SpecTree a Source #

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

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

The specItem function creates a spec item.

Defining a spec

The SpecM monad

A type class for examples

Internal representation of a spec tree

The `SpecM` monad