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=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    --[no-]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
        --[no-]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)
        --seed=N                     used seed for --randomize and QuickCheck
                                     properties

FORMATTER OPTIONS
  -f NAME  --format=NAME           use a custom formatter; this can be one of
                                   checks, specdoc, progress, failed-examples or
                                   silent
           --[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
           --show-exceptions       use `show` when formatting exceptions
           --display-exceptions    use `displayException` when formatting
                                   exceptions
           --[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

OPTIONS FOR QUICKCHECK
  -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)

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

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

Hspec reads options from two config files:

• ~/.hspec (a file named .hspec in the user's home directory)
• .hspec (a file named .hspec in the current directory)

Example:

echo --format=progress >> .hspec

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

Specifying options through environment variables

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:

• Converting all letters to uppercase
• Replacing all dashes with underscores
• Prepending HSPEC_

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:

• options from ~/.hspec take the lowest precedence
• options from .hspec take precedence over options from ~/.hspec
• options from environment variables take precedence over options from .hspec
• command-line options take the highest precedence