HSpec

https://hackage.haskell.org/package/hspec-2.11.12/docs/
Admin
HSpec is a testing framework for Haskell that provides a behavior-driven development approach with...
Tokens:8,748
Snippets:40
Trust Score:9.7
Update:1 year ago
Show doc for...
Tokens:
Raw
### fprop Shortcut Example

Source: https://hackage.haskell.org/package/hspec-2.11.12/docs/Test-Hspec-QuickCheck

Demonstrates the `fprop` shortcut in hspec for QuickCheck properties that should be focused. It highlights the equivalence between `fprop "description" $ property` and `fit "description" $ property $ ...`.

```Haskell
fprop ".." $
  ..
```

```Haskell
fit ".." $ property $
  ..
```

--------------------------------

### Define a spec item with `it`

Source: https://hackage.haskell.org/package/hspec-2.11.12/docs/Test-Hspec

The `it` function is used to create a spec item, which includes a textual description of behavior and an example to verify it. It requires a `HasCallStack` and an `Example` instance for the provided type.

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

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

--------------------------------

### Haskell Hspec: Define Setup and Teardown Hooks

Source: https://hackage.haskell.org/package/hspec-2.11.12/docs/Test-Hspec

Enables defining setup and teardown actions for tests using `before`, `after`, `around`, and their `_` and `With` variants. These hooks can be applied at different levels (individual tests, all tests in a group).

```Haskell
type ActionWith a = a -> IO ()
before :: IO a -> SpecWith a -> Spec
before_ :: IO () -> SpecWith a -> SpecWith a
beforeWith :: (b -> IO a) -> SpecWith a -> SpecWith b
beforeAll :: HasCallStack => IO a -> SpecWith a -> Spec
beforeAll_ :: HasCallStack => IO () -> SpecWith a -> SpecWith a
beforeAllWith :: HasCallStack => (b -> IO a) -> SpecWith a -> SpecWith b
after :: ActionWith a -> SpecWith a -> SpecWith a
after_ :: IO () -> SpecWith a -> SpecWith a
afterAll :: HasCallStack => ActionWith a -> SpecWith a -> SpecWith a
afterAll_ :: HasCallStack => IO () -> SpecWith a -> SpecWith a
around :: (ActionWith a -> IO ()) -> SpecWith a -> Spec
around_ :: (IO () -> IO ()) -> SpecWith a -> SpecWith a
aroundWith :: (ActionWith a -> ActionWith b) -> SpecWith a -> SpecWith b
aroundAll :: HasCallStack => (ActionWith a -> IO ()) -> SpecWith a -> Spec
aroundAll_ :: HasCallStack => (IO () -> IO ()) -> SpecWith a -> SpecWith a
aroundAllWith :: HasCallStack => (ActionWith a -> ActionWith b) -> SpecWith a -> SpecWith b
```

--------------------------------

### prop Shortcut Example

Source: https://hackage.haskell.org/package/hspec-2.11.12/docs/Test-Hspec-QuickCheck

Demonstrates the usage of the `prop` shortcut in hspec for defining a QuickCheck property. It shows how `prop "description" $ property` is equivalent to `it "description" $ property $ ...`.

```Haskell
prop ".." $
  ..
```

```Haskell
it ".." $ property $
  ..
```

--------------------------------

### xprop Shortcut Example

Source: https://hackage.haskell.org/package/hspec-2.11.12/docs/Test-Hspec-QuickCheck

Illustrates the `xprop` shortcut in hspec, used for QuickCheck properties that should be temporarily ignored. It shows the equivalence between `xprop "description" $ property` and `xit "description" $ property $ ...`.

```Haskell
xprop ".." $
  ..
```

```Haskell
xit ".." $ property $
  ..
```

--------------------------------

### Haskell Hspec: Example Type Class

Source: https://hackage.haskell.org/package/hspec-2.11.12/docs/Test-Hspec

Defines the `Example` type class, which is fundamental for creating testable examples in Hspec. Implementations of this class determine how different types can be evaluated as test cases.

```Haskell
class Example e
Minimal complete definition
    evaluateExample
```

--------------------------------

### Use `example` for better error messages

Source: https://hackage.haskell.org/package/hspec-2.11.12/docs/Test-Hspec

The `example` function is a type-restricted version of `id` that provides improved error messages for type mismatches within expectations. It takes an `Expectation` and returns an `Expectation`.

```Haskell
example :: Expectation -> Expectation Source #
```

```Haskell
it "exposes some behavior" $ example $ do
  putStrLn
```

--------------------------------

### Temporarily disable spec items with `xit`

Source: https://hackage.haskell.org/package/hspec-2.11.12/docs/Test-Hspec

Changing `it` to `xit` marks the corresponding spec item as pending, effectively disabling it temporarily. It requires a `HasCallStack` and an `Example` instance.

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

--------------------------------

### Alias for `it`: `specify`

Source: https://hackage.haskell.org/package/hspec-2.11.12/docs/Test-Hspec

The `specify` function is an alias for `it`, providing an alternative way to define spec items with a description and an example.

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

--------------------------------

### Mark spec items as pending with `pending`

Source: https://hackage.haskell.org/package/hspec-2.11.12/docs/Test-Hspec

The `pending` function marks a spec item as pending, meaning it will not be executed and will be reported as 'pending'. This is useful for specifying behavior without an immediate example.

```Haskell
pending :: HasCallStack => Expectation #
```

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

--------------------------------

### Haskell Hspec: Running a Spec

Source: https://hackage.haskell.org/package/hspec-2.11.12/docs/Test-Hspec

The main entry point for running an Hspec specification. It takes a `Spec` and executes it, returning an `IO ()` action.

```Haskell
hspec :: Spec -> IO ()
```

--------------------------------

### Using Hooks for Test Setup/Teardown in Haskell with hspec

Source: https://hackage.haskell.org/package/hspec-2.11.12/docs/Test-Hspec

This section covers the use of hooks in hspec for managing test execution flow. It includes functions for running actions before or after spec items, with variations for different argument types and scopes (e.g., `before`, `after`, `around`, `beforeAll`, `afterAll`, `aroundAll`).

```Haskell
type ActionWith a = a -> IO ()
before :: IO a -> SpecWith a -> Spec
before_ :: IO () -> SpecWith a -> SpecWith a
beforeWith :: (b -> IO a) -> SpecWith a -> SpecWith b
beforeAll :: HasCallStack => IO a -> SpecWith a -> Spec
beforeAll_ :: HasCallStack => IO () -> SpecWith a -> SpecWith a
beforeAllWith :: HasCallStack => (b -> IO a) -> SpecWith a -> SpecWith b
after :: ActionWith a -> SpecWith a -> SpecWith a
after_ :: IO () -> SpecWith a -> SpecWith a
afterAll :: HasCallStack => ActionWith a -> SpecWith a -> SpecWith a
afterAll_ :: HasCallStack => IO () -> SpecWith a -> SpecWith a
around :: (ActionWith a -> IO ()) -> SpecWith a -> Spec
around_ :: (IO () -> IO ()) -> SpecWith a -> SpecWith a
aroundWith :: (ActionWith a -> ActionWith b) -> SpecWith a -> SpecWith b
aroundAll :: HasCallStack => (ActionWith a -> IO ()) -> SpecWith a -> Spec
aroundAll_ :: HasCallStack => (IO () -> IO ()) -> SpecWith a -> SpecWith a
aroundAllWith :: HasCallStack => (ActionWith a -> ActionWith b) -> SpecWith a -> SpecWith b
```

--------------------------------

### Haskell describe Function

Source: https://hackage.haskell.org/package/hspec-2.11.12/docs/Test-Hspec-Discover

The describe function is used to group multiple specs into a larger spec. It requires a String description and a SpecWith a, and returns a SpecWith a.

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

--------------------------------

### hspec QuickCheck Property Shortcuts

Source: https://hackage.haskell.org/package/hspec-2.11.12/docs/Test-Hspec-QuickCheck

Provides shortcuts for defining QuickCheck properties within hspec tests. These functions simplify the process of running QuickCheck properties with specific configurations like skipping or focusing.

```Haskell
prop :: (HasCallStack, Testable prop) => String -> prop -> Spec
xprop :: (HasCallStack, Testable prop) => String -> prop -> Spec
fprop :: (HasCallStack, Testable prop) => String -> prop -> Spec
```

--------------------------------

### Combine specs with `describe`

Source: https://hackage.haskell.org/package/hspec-2.11.12/docs/Test-Hspec

The `describe` function groups multiple spec items into a larger spec structure. It requires a `HasCallStack` and takes a `String` for the description and a `SpecWith a` to combine.

```Haskell
describe :: HasCallStack => String -> SpecWith a -> SpecWith a #
```

--------------------------------

### Use Test.Hspec.Api.Formatters.V1 Instead

Source: https://hackage.haskell.org/package/hspec-2.11.12/docs/Test-Hspec-Formatters

The Test.Hspec.Formatters module is deprecated. Users should migrate to Test.Hspec.Api.Formatters.V1 for the latest features and support.

```Haskell
module Test.Hspec.Core.Formatters.V1

-- Deprecated: Use Test.Hspec.Api.Formatters.V1 instead.
```

--------------------------------

### Haskell Hspec: Define a Basic Test Specification

Source: https://hackage.haskell.org/package/hspec-2.11.12/docs/Test-Hspec

Defines a basic test specification using `it` and `describe` from the Hspec library. `it` is used for individual test cases, and `describe` is used to group related tests.

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

--------------------------------

### Running Specs with hspec in Haskell

Source: https://hackage.haskell.org/package/hspec-2.11.12/docs/Test-Hspec

The `hspec` function is the primary way to execute a defined spec in Haskell. It runs the spec, outputs a report to standard output, and exits with a failure status if any tests fail. It also handles command-line options.

```Haskell
hspec :: Spec -> IO ()
```

--------------------------------

### Haskell Testing Framework hspec

Source: https://hackage.haskell.org/package/hspec-2.11.12/docs/package/hspec

hspec is a testing framework for Haskell. It provides a friendly DSL for defining tests and integrates with popular libraries like QuickCheck, SmallCheck, and HUnit. It also supports parallel test execution and automatic discovery of test files.

```Haskell
module Test.Hspec where
```

```Haskell
import Test.Hspec.Discover
```

```Haskell
import Test.Hspec.Formatters
```

```Haskell
import Test.Hspec.QuickCheck
```

```Haskell
import Test.Hspec.Runner
```

--------------------------------

### Haskell Hspec: Handle Pending and Focused Tests

Source: https://hackage.haskell.org/package/hspec-2.11.12/docs/Test-Hspec

Allows marking tests as pending or focusing on specific tests. `pending` and `pendingWith` mark tests to be skipped, while `focus`, `fit`, `fspecify`, `fdescribe`, and `fcontext` are used to run only the marked tests.

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

--------------------------------

### Haskell hspec Function

Source: https://hackage.haskell.org/package/hspec-2.11.12/docs/Test-Hspec-Discover

The hspec function runs a given spec and outputs a report to stdout. It exits with failure if any spec item fails. It also handles command-line options and config files, but evalSpec and runSpecForest offer more control.

```Haskell
hspec :: Spec -> IO ()
```

--------------------------------

### Alias for `describe`: `context`

Source: https://hackage.haskell.org/package/hspec-2.11.12/docs/Test-Hspec

The `context` function is an alias for `describe`, used to group related spec items under a common description.

```Haskell
context :: HasCallStack => String -> SpecWith a -> SpecWith a #
```

--------------------------------

### Run IO actions during spec construction with `runIO`

Source: https://hackage.haskell.org/package/hspec-2.11.12/docs/Test-Hspec

The `runIO` function allows executing an `IO` action during the construction of the spec tree. This is useful when IO operations are needed before tests run, even with options like `--dry-run`. It returns a `SpecM a r`.

```Haskell
runIO :: IO r -> SpecM a r #
```

--------------------------------

### Haskell hspecWithFormatter Function

Source: https://hackage.haskell.org/package/hspec-2.11.12/docs/Test-Hspec-Discover

The hspecWithFormatter function allows running a spec with a custom formatter, requiring the formatter to be an instance of IsFormatter.

```Haskell
hspecWithFormatter :: IsFormatter a => a -> Spec -> IO ()
```

--------------------------------

### Haskell IsFormatter Type Class

Source: https://hackage.haskell.org/package/hspec-2.11.12/docs/Test-Hspec-Discover

The IsFormatter type class defines a method toFormatter, used for creating formatters. It has instances for Formatter and IO Formatter.

```Haskell
class IsFormatter a where
  toFormatter :: a -> IO Formatter
```

```Haskell
instance IsFormatter Formatter where
  toFormatter :: Formatter -> IO Formatter
  toFormatter = toFormatter
```

```Haskell
instance IsFormatter (IO Formatter) where
  toFormatter :: IO Formatter -> IO Formatter
  toFormatter = toFormatter
```

--------------------------------

### Focusing Spec Items in Haskell with hspec

Source: https://hackage.haskell.org/package/hspec-2.11.12/docs/Test-Hspec

This snippet demonstrates how to focus specific test items within a Haskell spec using the hspec library. Functions like `focus`, `fit`, `fspecify`, `fdescribe`, and `fcontext` allow selective execution of tests.

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

--------------------------------

### Haskell postProcessSpec Function

Source: https://hackage.haskell.org/package/hspec-2.11.12/docs/Test-Hspec-Discover

The postProcessSpec function takes a FilePath and a Spec, returning a modified Spec. Its exact purpose is related to processing spec files.

```Haskell
postProcessSpec :: FilePath -> Spec -> Spec
```

--------------------------------

### Haskell Hspec: Manage Test Execution Flow

Source: https://hackage.haskell.org/package/hspec-2.11.12/docs/Test-Hspec

Provides functions for controlling the execution flow of Hspec tests, including running tests in parallel or sequentially, and handling IO actions within specs.

```Haskell
example :: Expectation -> Expectation
parallel :: SpecWith a -> SpecWith a
sequential :: SpecWith a -> SpecWith a
runIO :: IO r -> SpecM a r
```

--------------------------------

### Mark spec items as pending with reason using `pendingWith`

Source: https://hackage.haskell.org/package/hspec-2.11.12/docs/Test-Hspec

Similar to `pending`, `pendingWith` marks a spec item as pending but also accepts a `String` argument to specify the reason for being pending.

```Haskell
pendingWith :: HasCallStack => String -> Expectation #
```

--------------------------------

### Haskell Hspec: Instances for Arg Type Class

Source: https://hackage.haskell.org/package/hspec-2.11.12/docs/Test-Hspec

Shows instances of the `Arg` type class for various types, including `Property`, `Result`, `Expectation`, `Bool`, and functions returning these types. `Arg` determines the type of the argument passed to a test.

```Haskell
type Arg Property = ()
type Arg Result = ()
type Arg Expectation = ()
type Arg Bool = ()
type Arg (a -> Property) = a
type Arg (a -> Result) = a
type Arg (a -> Expectation) = a
type Arg (a -> Bool) = a
```

--------------------------------

### Alias for `xit`: `xspecify`

Source: https://hackage.haskell.org/package/hspec-2.11.12/docs/Test-Hspec

The `xspecify` function is an alias for `xit`, used to temporarily disable a spec item.

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

--------------------------------

### Temporarily disable spec subtrees with `xdescribe`

Source: https://hackage.haskell.org/package/hspec-2.11.12/docs/Test-Hspec

Changing `describe` to `xdescribe` marks all spec items within the corresponding subtree as pending, allowing for temporary disabling of multiple related tests. It requires a `HasCallStack`.

```Haskell
xdescribe :: HasCallStack => String -> SpecWith a -> SpecWith a #
```

--------------------------------

### Mark spec items for sequential evaluation with `sequential`

Source: https://hackage.haskell.org/package/hspec-2.11.12/docs/Test-Hspec

The `sequential` function marks all spec items within the given spec to be evaluated sequentially, which can be necessary for tests with dependencies or shared state.

```Haskell
sequential :: SpecWith a -> SpecWith a #
```

--------------------------------

### Alias for `xdescribe`: `xcontext`

Source: https://hackage.haskell.org/package/hspec-2.11.12/docs/Test-Hspec

The `xcontext` function is an alias for `xdescribe`, used to temporarily disable a subtree of spec items.

```Haskell
xcontext :: HasCallStack => String -> SpecWith a -> SpecWith a #
```

--------------------------------

### Modify hspec Test Arguments

Source: https://hackage.haskell.org/package/hspec-2.11.12/docs/Test-Hspec-QuickCheck

These functions allow modification of arguments used in hspec tests, such as the maximum number of successes, discard ratio, size, and shrinks. They take a function to modify the respective argument and the spec to apply the modification to.

```Haskell
modifyArgs :: (Args -> Args) -> SpecWith a -> SpecWith a
modifyMaxSuccess :: (Int -> Int) -> SpecWith a -> SpecWith a
modifyMaxDiscardRatio :: (Int -> Int) -> SpecWith a -> SpecWith a
modifyMaxSize :: (Int -> Int) -> SpecWith a -> SpecWith a
modifyMaxShrinks :: (Int -> Int) -> SpecWith a -> SpecWith a
```

--------------------------------

### Mark spec items for parallel evaluation with `parallel`

Source: https://hackage.haskell.org/package/hspec-2.11.12/docs/Test-Hspec

The `parallel` function marks all spec items within the given spec to be safe for parallel evaluation, potentially speeding up test execution.

```Haskell
parallel :: SpecWith a -> SpecWith a #
```

--------------------------------

### Haskell Spec Type Definition

Source: https://hackage.haskell.org/package/hspec-2.11.12/docs/Test-Hspec-Discover

Defines the Spec type as an alias for SpecWith (). This is a fundamental type for defining test specifications in Hspec.

```Haskell
type Spec = SpecWith ()
```

--------------------------------

### Modifying Test Subjects in Haskell with hspec

Source: https://hackage.haskell.org/package/hspec-2.11.12/docs/Test-Hspec

This snippet shows how to manipulate the subject under test within hspec. `mapSubject` allows modification of the subject, while `ignoreSubject` can be used to disregard it entirely for specific specs.

```Haskell
mapSubject :: (b -> a) -> SpecWith a -> SpecWith b
ignoreSubject :: SpecWith () -> SpecWith a
```

--------------------------------

### Haskell Hspec: Type Aliases for Specifications

Source: https://hackage.haskell.org/package/hspec-2.11.12/docs/Test-Hspec

Defines type aliases for `Spec` and `SpecWith` in Hspec. `Spec` is an alias for `SpecWith ()`, and `SpecWith a` represents a specification that can interact with a value of type `a`.

```Haskell
type Spec = SpecWith ()
type SpecWith a = SpecM a ()
```

--------------------------------

### Haskell Hspec: Subject Manipulation in Tests

Source: https://hackage.haskell.org/package/hspec-2.11.12/docs/Test-Hspec

Allows transformation and ignoring of the 'subject' in Hspec tests. `mapSubject` transforms the subject passed to the test, while `ignoreSubject` discards it.

```Haskell
mapSubject :: (b -> a) -> SpecWith a -> SpecWith b
ignoreSubject :: SpecWith () -> SpecWith a
```
Tokens:
Raw