Modulehspec-core-2.11.14Haskell2010

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!

16 types
1 class
41 values

Packagehspec-core-2.11.14
Exports58
LanguageHaskell2010
LicenceMIT
SourceSpec.hs

Defining a spec

10 declarations

valueit :: (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

Example a optionally accepts an argument Arg a, which is then given to the test body. This is useful for provisioning resources for a test which are created and cleaned up outside the test itself. See Arg for details.

Note that this function is often on the scene of nasty type errors due to GHC failing to infer the type of do notation in the test body. It can be helpful to use TypeApplications to explicitly specify the intended Example type.

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

specify is an alias for it.

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

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

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

context is an alias for describe.

valuepending :: 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

valuependingWith :: 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.

valuexit :: (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.

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

xspecify is an alias for xit.

valuexdescribe :: 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.

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

xcontext is an alias for xdescribe.

Focused spec items

7 declarations

During a test run, when a spec contains focused spec items, all other spec items are ignored.

valuefocus :: 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.

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

fit is an alias for fmap focus . it

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

fspecify is an alias for fit.

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

fdescribe is an alias for fmap focus . describe

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

fcontext is an alias for fdescribe.

valueparallel :: SpecWith a -> SpecWith a

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

valuesequential :: SpecWith a -> SpecWith a

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

The `SpecM` monad

12 declarations

typetype Spec = SpecWith ()

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

typetype SpecWith a = SpecM a ()

A SpecWith a represents a test or group of tests that require an a value to run.

In the common case, a Spec is a SpecWith () which requires () and can thus be executed with hspec.

To supply an argument to SpecWith tests to turn them into Spec, use functions from Test.Hspec.Core.Hooks such as around, before, mapSubject and similar.

Values of this type are created by it, describe and similar.

newtypenewtype SpecM a r

A writer monad for SpecTree forests.

This is used by describe and is used to construct the forest of spec items.

It allows for dynamically generated spec trees, for example, by using data obtained by performing IO actions with runIO.

Constructors

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

Instances3Monad, Functor, Applicative

Monad (SpecM a)Defined in hspec-core-2.11.14 · Test.Hspec.Core.Spec.Monad
Functor (SpecM a)Defined in hspec-core-2.11.14 · Test.Hspec.Core.Spec.Monad
Applicative (SpecM a)Defined in hspec-core-2.11.14 · Test.Hspec.Core.Spec.Monad

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

Convert a Spec to a forest of SpecTrees.

valuefromSpecList :: [SpecTree a] -> SpecWith a

Create a Spec from a forest of SpecTrees.

valuerunIO :: 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 itself. 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.

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

valuemapSpecItem

:: ActionWith a -> ActionWith b
-> Item a -> Item b
-> SpecWith a
-> SpecWith b

Deprecated: Use mapSpecItem_ instead.

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

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

Modifies the Params on the spec items to be generated by SpecWith.

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

valuegetSpecDescriptionPath :: SpecM a [String]

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

Example

Example1 expression

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

A type class for examples

12 declarations

classclass Example e where

A type class for examples, that is to say, test bodies as used in it and similar functions.

Associated types

type family Arg e
The argument type that is needed to run this Example. If Arg is (), no argument is required and the Example can be run as-is.
The value of Arg is the difference between Test.Hspec.Core.Spec.Spec (aka Test.Hspec.Core.Hspec.SpecWith ()), which can be executed, and Test.Hspec.Core.Spec.SpecWith a, which cannot be executed without turning it into Test.Hspec.Core.Spec.Spec first.
To supply an argument to examples, use the functions in Test.Hspec.Core.Hooks such as around, before, mapSubject and similar.

Methods

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

Evaluates an example.

evaluateExample is expected to execute the test body inside the IO action passed to the hook. It's often necessary to use an IORef to pass data out like whether the test succeeded to the outer IO action so it can be returned as a Result.

Example:

newtype MyAction = MyAction (Int -> IO Bool)

instance Example MyAction where
  type Arg MyAction = Int

  evaluateExample (MyAction act) _params hook _progress = do
    result <- newIORef (Result "" Success)
    hook $ arg -> do
      -- e.g. determines if arg is 42
      ok <- act arg
      let result' = Result "" $ if ok then Success else Failure Nothing NoReason
      writeIORef result result'
    readIORef result

Instances8Example, …

Example PropertyDefined in hspec-core-2.11.14 · Test.Hspec.Core.QuickCheck · orphan
Example BoolDefined in hspec-core-2.11.14 · Test.Hspec.Core.Example
Example ResultDefined in hspec-core-2.11.14 · Test.Hspec.Core.Example
Example ExpectationDefined in hspec-core-2.11.14 · Test.Hspec.Core.Example
Example (a -> Property)Defined in hspec-core-2.11.14 · Test.Hspec.Core.QuickCheck · orphan
Example (a -> Bool)Defined in hspec-core-2.11.14 · Test.Hspec.Core.Example
Example (a -> Result)Defined in hspec-core-2.11.14 · Test.Hspec.Core.Example
Example (a -> Expectation)Defined in hspec-core-2.11.14 · Test.Hspec.Core.Example

datadata Params

QuickCheck and SmallCheck related parameters.

Constructors

Params
- paramsQuickCheckArgs :: Args
- paramsSmallCheckDepth :: Maybe Int

Instances1Show

Show ParamsDefined in hspec-core-2.11.14 · Test.Hspec.Core.Example

valuedefaultParams :: Params

typetype ActionWith a = a -> IO ()

An IO action that expects an argument of type a.

This type is what Examples are ultimately unlifted into for execution.

typetype Progress = (Int, Int)

(CurrentItem, TotalItems) tuple.

typetype ProgressCallback = Progress -> IO ()

Callback used by composite test items that contain many tests to report their progress towards finishing them all.

This is used, for example, to report how many QuickCheck examples are finished.

datadata Result

The result of running an example

Constructors

Result
- resultInfo :: String
- resultStatus :: ResultStatus

Instances5Show, Example, Arg

Show ResultDefined in hspec-core-2.11.14 · Test.Hspec.Core.Example
Example ResultDefined in hspec-core-2.11.14 · Test.Hspec.Core.Example
Example (a -> Result)Defined in hspec-core-2.11.14 · Test.Hspec.Core.Example
type Arg Result = ()Defined in hspec-core-2.11.14 · Test.Hspec.Core.Example
type Arg (a -> Result) = aDefined in hspec-core-2.11.14 · Test.Hspec.Core.Example

datadata ResultStatus

Constructors

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

Instances2Show, Exception

Show ResultStatusDefined in hspec-core-2.11.14 · Test.Hspec.Core.Example
Exception ResultStatusDefined in hspec-core-2.11.14 · Test.Hspec.Core.Example

datadata Location

Location is used to represent source locations.

Constructors

Location
- locationFile :: FilePath
- locationLine :: Int
- locationColumn :: Int

Instances3Eq, Read, Show

Eq LocationDefined in hspec-core-2.11.14 · Test.Hspec.Core.Example.Location
Read LocationDefined in hspec-core-2.11.14 · Test.Hspec.Core.Example.Location
Show LocationDefined in hspec-core-2.11.14 · Test.Hspec.Core.Example.Location

datadata FailureReason

Constructors

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

Instances2Show, NFData

Show FailureReasonDefined in hspec-core-2.11.14 · Test.Hspec.Core.Example
NFData FailureReasonDefined in hspec-core-2.11.14 · Test.Hspec.Core.Example

valuesafeEvaluate :: IO Result -> IO Result

valuesafeEvaluateExample

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

Internal representation of a spec tree

15 declarations

typetype 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.

datadata Tree c a

Internal tree data structure

Constructors

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

Instances5Functor, Foldable, Traversable, Eq, Show

Functor (Tree c)Defined in hspec-core-2.11.14 · Test.Hspec.Core.Tree
Foldable (Tree c)Defined in hspec-core-2.11.14 · Test.Hspec.Core.Tree
Traversable (Tree c)Defined in hspec-core-2.11.14 · Test.Hspec.Core.Tree
(Eq c, Eq a) => Eq (Tree c a)Defined in hspec-core-2.11.14 · Test.Hspec.Core.Tree
(Show c, Show a) => Show (Tree c a)Defined in hspec-core-2.11.14 · Test.Hspec.Core.Tree

datadata 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
- 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
- itemAnnotations :: Annotations
  Arbitrary additional data that can be used by third-party extensions.
- itemExample :: Params -> (ActionWith a -> IO ()) -> ProgressCallback -> IO Result
  Example for behavior

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

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

valuespecItem :: (HasCallStack, Example e) => String -> e -> SpecTree (Arg e)

The specItem function creates a spec item.

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

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

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

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

valuefilterTreeWithLabels

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

valuefilterForestWithLabels

:: [String] -> a -> Bool
-> [Tree c a]
-> [Tree c a]

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

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

valuelocation :: HasCallStack => Maybe Location

valuefocusForest :: [SpecTree a] -> [SpecTree a]

Marks an entire spec forest as focused if nothing in it is already focused.

Re-exports

2 declarations

typetype HasCallStack = IP "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.

typetype Expectation = Assertion

Instances4Example, Arg

Example ExpectationDefined in hspec-core-2.11.14 · Test.Hspec.Core.Example
Example (a -> Expectation)Defined in hspec-core-2.11.14 · Test.Hspec.Core.Example
type Arg Expectation = ()Defined in hspec-core-2.11.14 · Test.Hspec.Core.Example
type Arg (a -> Expectation) = aDefined in hspec-core-2.11.14 · Test.Hspec.Core.Example

Defining a spec

Focused spec items

The SpecM monad

Constructors

Example

A type class for examples

Associated types

Methods

Constructors

Constructors

Constructors

Constructors

Constructors

Internal representation of a spec tree

Constructors

Constructors

Re-exports

The `SpecM` monad