Hspec: A Testing Framework for Haskell


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

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

        --[no-]dry-run          pretend that everything passed; don't verify
        --[no-]focused-only     do not run anything, unless there are focused
                                spec items
        --[no-]fail-on=ITEMS    empty: fail if all spec items have been filtered
                                focused: fail on focused spec items
                                pending: fail on pending spec items
                                empty-description: fail on empty descriptions
        --[no-]strict           same as --fail-on=focused,pending
        --[no-]fail-fast        abort on first failure
        --[no-]randomize        randomize execution order
  -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

  -f NAME  --format=NAME           use a custom formatter; this can be one of
                                   checks, specdoc, progress, failed-examples or
           --[no-]color            colorize the output
           --[no-]unicode          output unicode
           --[no-]diff             show colorized diffs
           --diff-context=N        output N lines of diff context (default: 3)
                                   use a value of 'full' to see the full context
           --diff-command=CMD      use an external diff command
                                   example: --diff-command="git diff"
           --[no-]pretty           try to pretty-print diff values
           --[no-]times            report times for individual spec items
           --print-cpu-time        include used CPU time in summary
  -p[N]    --print-slow-items[=N]  print the N slowest spec items (default: 10)
           --[no-]expert           be less verbose

  -a N  --qc-max-success=N  maximum number of successful tests before a
                            QuickCheck property succeeds
        --qc-max-discard=N  maximum number of discarded tests per successful
                            test before giving up
        --qc-max-size=N     size to use for the biggest test cases
        --qc-max-shrinks=N  maximum number of shrinks to perform before giving
                            up (a value of 0 turns shrinking off)
        --seed=N            used seed for QuickCheck properties

    --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 within a GHCi-session.


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

cabal test --test-show-details=direct --test-option=--format=progress
cabal test --test-show-details=direct --test-option=--match --test-option="some spec item"

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

Note: With older versions of Cabal use --show-details=direct instead of --test-show-details=direct.


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

stack test --test-arguments=--format=progress
stack test --test-arguments='--match "some spec item"'


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

*Main> :main --format=progress
*Main> :main --match "some spec item"

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:


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

Specifying options through environment variables

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

All of Hspec's options can be specified through environment variables:

HSPEC_FORMAT=progress cabal test --test-show-details=direct

Option names are converted to environment variable names by:

For flags, like --color/--no-color, there is only one corresponding environment variable with valid values of yes/no:

HSPEC_COLOR=yes cabal test --test-show-details=direct

In addition, Hspec reads options from the environment variable HSPEC_OPTIONS. This is deprecated and will be removed at some point in the future.

Precedence resolution for options that are specified in multiple places

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