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
        --[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
                                processors)

FORMATTER OPTIONS
  -f FORMATTER  --format=FORMATTER      use a custom formatter; this can be one
                                        of checks, specdoc, progress,
                                        failed-examples or silent
                --[no-]color            colorize the output
                --[no-]diff             show colorized diffs
                --[no-]times            report times for individual spec items
                --print-cpu-time        include used CPU time in summary
  -p[N]         --print-slow-specs[=N]  print the N slowest spec items (default:
                                        10)

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

Stack

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

GHCi

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:

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: