Hspec: A Testing Framework for Haskell

Contents

Passing options to Hspec

The previous section described how to create a test driver to run a spec. It is possible to customize how a spec is run by passing options to that test driver.

Supported options

You can get a list of supported options by passing --help to the test driver:

runhaskell Spec.hs --help
Usage: Spec.hs [OPTION]...

OPTIONS
              --help              display this help and exit
              --ignore-dot-hspec  do not read options from ~/.hspec and .hspec
  -m PATTERN  --match=PATTERN     only run examples that match given PATTERN
              --skip=PATTERN      skip examples that match given PATTERN

RUNNER OPTIONS
        --[no-]dry-run          pretend that everything passed; don't verify
                                anything
        --[no-]focused-only     do not run anything, unless there are focused
                                spec items
        --[no-]fail-on-focused  fail on focused spec items
        --[no-]fail-fast        abort on first failure
  -r    --rerun                 rerun all examples that failed in the previous
                                test run (only works in combination with
                                --failure-report or in GHCi)
        --failure-report=FILE   read/write a failure report for use with --rerun
        --rerun-all-on-success  run the whole test suite after a previously
                                failing rerun succeeds for the first time (only
                                works in combination with --rerun)
  -j N  --jobs=N                run at most N parallelizable tests
                                simultaneously (default: number of available
                                processors)

FORMATTER OPTIONS
  -f FORMATTER  --format=FORMATTER  use a custom formatter; this can be one of
                                    specdoc, progress, failed-examples or silent
                --[no-]color        colorize the output
                --[no-]diff         show colorized diffs
                --print-cpu-time    include used CPU time in summary

OPTIONS FOR QUICKCHECK
  -a N  --qc-max-success=N  maximum number of successful tests before a
                            QuickCheck property succeeds
        --qc-max-size=N     size to use for the biggest test cases
        --qc-max-discard=N  maximum number of discarded tests per successful
                            test before giving up
        --seed=N            used seed for QuickCheck properties

OPTIONS FOR SMALLCHECK
    --depth=N  maximum depth of generated test values for SmallCheck properties

Specifying options on the command-line

How to specify command-line options depends on how you run your tests. This section describes how to pass command-line options to Hspec via Cabal and Stack, and from withing a GHCi-session.

Cabal

If you are using Cabal you can use --test-option to pass command-line options to Hspec:

cabal test --show-details=direct --test-option=--format=progress

Note: When running Hspec tests via Cabal, it is recommended to always specify --show-details=direct.

Stack

If you are using stack you can use --test-arguments to pass command-line options to Hspec:

stack test --test-arguments=--format=progress

GHCi

If you run your tests from within a GHCi-session you can specify command-line options right after :main:

*Main> :main --format=progress

Specifying options in config files

Note: This section assumes that you are using hspec-2.4.0 or later.

Hspec reads options from two config files:

Example:

echo --format=progress >> .hspec
or
echo --format=progress >> ~/.hspec

Specifying options through an environment variable

Note: This section assumes that you are using hspec-2.4.3 or later.

Hspec reads options from the environment variabe HSPEC_OPTIONS:

HSPEC_OPTIONS="--format=progress" cabal test --show-details=direct

Precedence resolution for options that are specified in multiple places

If the same option is specified in multiple places, precedence is resolved as follows: