hspec-tidy-formatter

A custom hspec formatter for terminal output.

left: this formatter, right: hspec default

_{(color choices: ©hspec  me  terminal theme)}

---

The formatter should work with with any test runner backend. It may be particularly useful with Hedgehog tests through hspec-hedgehog: it omits the "passed 100 tests." otherwise printed after each spec item, yet includes manually added test output (Hedgehog.collect, Hedgehog.label etc.).

How to enable

With hspec-discover

Place a file SpecHook.hs in the source directory of the test component:

-- --- test/SpecHook.hs ---

import Test.Hspec
import qualified Test.Hspec.TidyFormatter as TidyFormatter

hook :: Spec -> Spec

-- use by default:
hook = TidyFormatter.use

-- to instead use only if requested (`hspec --format=tidy`):
-- hook = TidyFormatter.register

hspec --help can be used to inspect which formatters hspec is aware of:

 $ cabal test hspec --test-options=--help | grep -A3 FORMATTER

 FORMATTER OPTIONS
   -f NAME  --format=NAME     use a custom formatter; can be one of
-                             checks, specdoc, progress,
+                             checks, specdoc, progress, tidy
                              failed-examples or silent

By modifying Spec-s directly

main :: IO ()
main = hspec . TidyFormatter.use $ spec

spec :: Spec
spec = it "adds" $ 1+1 `shouldBe` (2::Int)

Functionality, options

• supports transient output/progress

• honors most hspec options, including: --times, --no-unicode, --no-color, --print-cpu-time, --print-slow-items=[=N]

Printing of additional text from test runners

hspec allows test runners to pass it additional text together with the outcome of each test. This formatter, by default, prints such text only if it spans more than one line. To instead print all such text unconditionally, use --times (default: --no-times). This will additionally do what this option is originally supposed to do: print the execution time for spec items (if > 0 after rounding to milliseconds).

E.g. with hspec-hedgehog, which passes the number of tests run for each item as a single line of text:

- $  hspec --format=tidy
+ $  hspec --format=tidy --times

  [...]
    is Applicative-lawful per
-     [✔] Identity
+     [✔] Identity  (21ms) (passed 100 tests.)

To instead suppress the printing of any additional text from the test runner, use --expert (default: --no-expert).

Verbosity switches --[no-]expert, --[no-]times combinations

For two spec items whose test runner returns a single line, and a few lines, respectively, of additional text:

===========       =========================================
<ARGS>            `hspec <ARGS>` example output
===========       =========================================


                                             (most verbose)


-----------       -----------------------------------------
--times           [✔] Identity  (21ms) (passed 100 tests.)
--no-expert       [✔] Hedgehog generator  (49ms)
                    passed 100 tests.
                      n:   0       1% ▏···················
                      n:   1- 4    5% █···················
                      n:   5-19   16% ███▏················


-----------       -----------------------------------------
--no-times        [✔] Identity
--no-expert       [✔] Hedgehog generator
(DEFAULT)           passed 100 tests.
                      n:   0       1% ▏···················
                      n:   1- 4    5% █···················
                      n:   5-19   16% ███▏················


-----------       -----------------------------------------
--times           [✔] Identity  (21ms)
--expert          [✔] Hedgehog generator  (49ms)


-----------       -----------------------------------------
--no-times        [✔] Identity
--expert          [✔] Hedgehog generator


                                            (least verbose)