hspec-core-2.4.3: A Testing Framework for Haskell

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

- it :: (HasCallStack, Example a) => String -> a -> SpecWith (Arg a)
- specify :: (HasCallStack, Example a) => String -> a -> SpecWith (Arg a)
- describe :: String -> SpecWith a -> SpecWith a
- context :: String -> SpecWith a -> SpecWith a
- pending :: Expectation
- pendingWith :: String -> Expectation
- xit :: (HasCallStack, Example a) => String -> a -> SpecWith (Arg a)
- xspecify :: (HasCallStack, Example a) => String -> a -> SpecWith (Arg a)
- xdescribe :: String -> SpecWith a -> SpecWith a
- xcontext :: String -> SpecWith a -> SpecWith a
- parallel :: SpecWith a -> SpecWith a
- type Spec = SpecWith ()
- type SpecWith a = SpecM a ()
- newtype SpecM a r = SpecM (WriterT [SpecTree a] IO r)
- runSpecM :: SpecWith a -> IO [SpecTree a]
- fromSpecList :: [SpecTree a] -> SpecWith a
- runIO :: IO r -> SpecM a r
- mapSpecTree :: (SpecTree a -> SpecTree b) -> SpecWith a -> SpecWith b
- mapSpecItem :: (ActionWith a -> ActionWith b) -> (Item a -> Item b) -> SpecWith a -> SpecWith b
- mapSpecItem_ :: (Item a -> Item a) -> SpecWith a -> SpecWith a
- modifyParams :: (Params -> Params) -> SpecWith a -> SpecWith a
- class Example e where
  - type Arg e
- data Params = Params {
  - paramsQuickCheckArgs :: Args
  - paramsSmallCheckDepth :: Int
  }
- defaultParams :: Params
- type ActionWith a = a -> IO ()
- type Progress = (Int, Int)
- type ProgressCallback = Progress -> IO ()
- data Result
  - = Success
  - | Pending (Maybe String)
  - | Failure (Maybe Location) FailureReason
- data Location = Location {
  - locationFile :: FilePath
  - locationLine :: Int
  - locationColumn :: Int
  - locationAccuracy :: LocationAccuracy
  }
- data LocationAccuracy
  - = ExactLocation
  - | BestEffort
- data FailureReason
  - = NoReason
  - | Reason String
  - | ExpectedButGot (Maybe String) String String
- safeEvaluateExample :: Example e => e -> Params -> (ActionWith (Arg e) -> IO ()) -> ProgressCallback -> IO (Either SomeException Result)
- type SpecTree a = Tree (ActionWith a) (Item a)
- data Tree c a
  - = Node String [Tree c a]
  - | NodeWithCleanup c [Tree c a]
  - | Leaf a
- data Item a = Item {
  - itemRequirement :: String
  - itemLocation :: Maybe Location
  - itemIsParallelizable :: Bool
  - itemExample :: Params -> (ActionWith a -> IO ()) -> ProgressCallback -> IO (Either SomeException Result)
  }
- specGroup :: String -> [SpecTree a] -> SpecTree a
- specItem :: (HasCallStack, Example a) => String -> a -> SpecTree (Arg a)

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

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

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

`context` is an alias for `describe`.

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

`xcontext` is an alias for `xdescribe`.

parallel :: SpecWith a -> SpecWith a #

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

# The `SpecM` monad

type Spec = SpecWith () #

type SpecWith a = SpecM a () #

newtype SpecM a r #

A writer monad for `SpecTree` forests

Constructors

SpecM (WriterT [SpecTree a] IO r) |

Instances

Monad (SpecM a) # |
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) # |
Methods fmap :: (a -> b) -> SpecM a a -> SpecM a b # (<$) :: a -> SpecM a b -> SpecM a a #
Applicative (SpecM a) # |
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] #

Convert a `Spec` to a forest of `SpecTree`s.

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

Create a `Spec` from a forest of `SpecTree`s.

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.

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

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

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

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

# A type class for examples

class Example e where #

A type class for examples

Minimal complete definition

evaluateExample

Associated Types

type Arg e #

Methods

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

Instances

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

Instances

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

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

Instances

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

data Location #

`Location` is used to represent source locations.

Constructors

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

Instances

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

data LocationAccuracy #

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 # |
Methods (==) :: LocationAccuracy -> LocationAccuracy -> Bool # (/=) :: LocationAccuracy -> LocationAccuracy -> Bool #
Read LocationAccuracy # |
Methods readsPrec :: Int -> ReadS LocationAccuracy # readList :: ReadS [LocationAccuracy] # readPrec :: ReadPrec LocationAccuracy # readListPrec :: ReadPrec [LocationAccuracy] #
Show LocationAccuracy # |
Methods showsPrec :: Int -> LocationAccuracy -> ShowS # show :: LocationAccuracy -> String # showList :: [LocationAccuracy] -> ShowS #

data FailureReason #

Constructors

NoReason |
Reason String |
ExpectedButGot (Maybe String) String String |

Instances

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

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

# Internal representation of a spec tree

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

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 #

Internal tree data structure

Constructors

Node String [Tree c a] |
NodeWithCleanup c [Tree c a] |
Leaf a |

Instances

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

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

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.