Hspec: A Testing Framework for Haskell

Contents

Passing options to Hspec

In the last section we have seen how to create a test driver for your tests. 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
                --color                 colorize the output
                --no-color              do not colorize the output
                --diff                  show colorized diffs
                --no-diff               do not show colorized diffs
  -f FORMATTER  --format=FORMATTER      use a custom formatter; this can be one
                                        of:
                                           specdoc
                                           progress
                                           failed-examples
                                           silent
  -o FILE       --out=FILE              write output to a file instead of STDOUT
                --depth=N               maximum depth of generated test values
                                        for SmallCheck properties
  -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
                --print-cpu-time        include used CPU time in summary
                --dry-run               pretend that everything passed; don't
                                        verify anything
                --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)

Specifying options on the command-line

How to specify command-line options depends on how your 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: