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