QuickCheck, HUnit, hspec, tasty and doctest: not run here

Every page of this group shows a run: a program that was compiled, a command that was run and the output it printed. This page is the exception and says so on all of its sections. The five test tools that most Haskell projects use, QuickCheck, HUnit, hspec, tasty and doctest, are not installed here, and the container has no network, so there is no output to show. What can be shown is the proof that they are absent, the error the package resolver gives for one of them, and the route to install each on a machine that has a network.

The point of the page is that a missing library is not a reason to invent a result. The three preceding pages build a suite out of the GHC boot libraries alone; this one tells you what you get when you can add the rest, so the choice is informed.

What is not in the image

ghc-pkg list prints the packages this GHC has installed. The list is the boot libraries that come with the compiler: base, containers, text, bytestring, mtl, stm, parsec and the rest of the set a GHC installation needs to compile itself. A grep for the five test tools finds nothing, and the status says the grep matched no line:

ghc-pkg list | grep -iE 'quickcheck|hunit|hspec|tasty|doctest'
echo "status $?"

status 1

A distribution package would be the other way to get them. Alpine does package some Haskell libraries, and none of these five is installed in this image; the list above is the whole set. A library built against another GHC is one whose interface files this compiler refuses to load, so the version has to match the compiler, which is why the usual answer is to build from Hackage with the cabal that ships with the same GHC.

Why cabal cannot fetch it

Cabal resolves a package against an index of Hackage, and the index is downloaded by cabal update. With no network the download neither fails nor finishes: the command prints its first line and waits. The timeout ends it and reports 124, which is the status it uses for a command it had to kill.

timeout 20 cabal update; echo "status $?"

Downloading the latest package list from hackage.haskell.org
status 124

Nothing was downloaded, so the index is still missing, and the build on the Cabal page says so: The package list for 'hackage.haskell.org' does not exist. A package that lives in GHC needs no index, which is why the price package built. A package that does not is unknown to the resolver, and the error names it:

cabal build --offline --enable-tests; echo "status $?"

Warning: The package list for 'hackage.haskell.org' does not exist. Run 'cabal
update' to download it.
Resolving dependencies...
Error: [Cabal-7107]
Could not resolve dependencies:
[__0] trying: price-0.1.0.0 (user goal)
[__1] trying: price:*test
[__2] unknown package: HUnit (dependency of price *test)
[__2] fail (backjumping, conflict set: HUnit, price, price:test)
After searching the rest of the dependency tree exhaustively, these were the goals I've had most trouble fulfilling: price, price:test, HUnit

status 1

unknown package: HUnit is the whole story: the resolver has no package of that name, offline forbids it from looking, and the build stops before a compiler runs. The same error appears for QuickCheck, hspec, tasty and doctest, and the name in the message is the one to add to the index first.

The install route

On a machine with a network there are two routes, and they differ in who owns the versions. The project route adds the library to the build-depends of the component that uses it, and cabal build downloads and builds that version into the project store; it is the route that keeps a build reproducible, because the version is written in the manifest.

cabal update
cabal build

The other route installs a library into a package environment that GHC sees, without a project: cabal install --lib HUnit writes it and its dependencies where ghc and runghc find it, which is what a reader wants for a script or a single file. The same command works for every library on this page.

cabal install --lib QuickCheck HUnit hspec tasty doctest

stack has its own resolver and its own store, and ghcup installs the compiler rather than the libraries. Neither is in this image: only GHC, cabal-install, the boot libraries, hlint, ormolu and hpc are.

QuickCheck

Not run here. QuickCheck is the property library the page on property checks builds by hand, and it adds the three things that page names as missing. A class Arbitrary gives every type a generator, so a property is a function and the inputs come from its type instead of from a generator written per property. Shrinking reduces a failing input to a small one, so a report is usually a single value instead of a long string. And a property runs in the Property monad, where ==> discards inputs that do not apply and collect reports the distribution of the cases.

A property in QuickCheck reads prop_reverse :: [Int] -> Bool with prop_reverse xs = reverse (reverse xs) == xs, and quickCheck prop_reverse runs a hundred cases and prints the counterexample and the number of cases it took. The page on tools that are not here prints no such line, because this container never ran it.

cabal install --lib QuickCheck

HUnit and hspec

Not run here. HUnit is the assertion library: a test is a Test built from assertEqual, assertBool or assertFailure, a list of tests is a TestList, and a runner executes them and reports the failures. It is the same shape as the driver of the first page with the message building, the counting and the reporting already written.

hspec is the layer above HUnit that most new projects choose: a describe and it block per behaviour, an expectation such as shouldBe or shouldSatisfy, and a runner that prints a tree of the sections with a dot per passing example. It comes with its own test discovery through hspec-discover, which is a second package. Both install the same way:

cabal install --lib HUnit
cabal install --lib hspec

tasty

Not run here. tasty is a test runner, not an assertion library: it collects tests from providers, tasty-hunit, tasty-quickcheck, tasty-hspec, and runs them with one command line that can filter by pattern, repeat a failing test, or print the timings. A project with both unit tests and properties uses one runner for both, which is the reason it exists.

The providers are separate packages, so a tasty suite declares the runner and the providers it uses. The runner itself installs like the rest:

cabal install --lib tasty tasty-hunit tasty-quickcheck

doctest

Not run here. doctest reads the examples in the Haddock comments of a module, the lines that start with >>>, runs them in GHCi and compares the printed result. An example that a reader can copy is then also a test, which is the cheapest kind of documentation to keep true. It is a program of its own and it needs the modules of the package compiled, so a Cabal project adds it to the test suite as a build tool rather than as a library.

The test suite stanza gains build-tool-depends: doctest:doctest and a main that calls Test.DocTest.doctest with the source directories, and cabal test then runs the examples with everything else. On this page there is no such run.

cabal install --lib doctest

What all five have in common is that they are libraries on top of the two things the group already builds: a program that checks values and an exit status that says whether it passed. A project that can add packages should use them; a project that cannot is not without tests, as the previous pages show, and the Cabal test suite lesson is where the hand-written driver meets the build tool.

The commands that produced output on this page were run with GHC 9.10.3 and cabal-install 3.16.0.0 on Alpine Linux 3.24.3 (x86_64) in a Docker container. The five libraries were not installed and nothing on this page is their output.

Article author: Arthur Isaev