A Setup.hs helper for doctests running

Version on this page:1.0.2
LTS Haskell 22.16:1.0.9@rev:3
Stackage Nightly 2024-04-12:1.0.9@rev:3
Latest on Hackage:1.0.9@rev:3

See all snapshots cabal-doctest appears in

BSD-3-Clause licensed and maintained by Oleg Grenrus
This version can be pinned in stack with:cabal-doctest-1.0.2@sha256:402929d4fe601bdf64127d1a37a5c12ced8a4e7682f13bddad4e89953b9c8e2d,1357

Module documentation for 1.0.2


Hackage Build Status

A Setup.hs helper for running doctests.

Example Usage

See [] for an example package. (Note that the example requires Cabal-1.24 or later, but you can relax this bound safely, although running doctests won’t be supported on versions of Cabal older than 1.24.)

To use this library in your Setup.hs, you should specify a custom-setup section in your .cabal file. For example:

   base >= 4 && <5,
   cabal-doctest >= 1 && <1.1

/Note:/ Cabal dependency is needed because of Cabal/GH-4288 bug.

You’ll also need to specify build-type: Custom at the top of the .cabal file. Now put this into your Setup.hs file:

module Main where

import Distribution.Extra.Doctest (defaultMainWithDoctests)

main :: IO ()
main = defaultMainWithDoctests "doctests"

When you build your project, this Setup will generate a Build_doctests module. To use it in a testsuite, simply do this:

module Main where

import Build_doctests (flags, pkgs, module_sources)
import Data.Foldable (traverse_)
import Test.DocTest (doctest)

main :: IO ()
main = do
    traverse_ putStrLn args -- optionally print arguments
    doctest args
    args = flags ++ pkgs ++ module_sources

Additional configuration

The cabal-doctest based Setup.hs supports few extensions fields in pkg.cabal files to customise the doctest runner behaviour, without customising the default doctest.hs.

test-suite doctests:
  if impl(ghc >= 8.0)
    x-doctest-options: -fdiagnostics-color=never
  x-doctest-source-dirs: test
  x-doctest-modules: Servant.Utils.LinksSpec

  • x-doctest-options Additional arguments passed into doctest command.
  • x-doctest-modules Additional modules to doctest. May be useful if you have doctest in test or executables (i.e not default library complonent).
  • x-doctest-src-dirs Additional source directories to look for the modules.


  • custom-setup section is supported starting from cabal-install-1.24. For older cabal-install's you have to install custom setup dependencies manually.

  • stack respects custom-setup starting from version 1.3.3. Before that you have to use explicit-setup-deps setting in your stack.yaml. (stack/GH-2094)

  • There is an issue in the Cabal issue tracker about adding cabal doctest command. After that command is implemented, this library will be deprecated.

  • If your library contains cbits, you might need to depend on the library itself in doctests test-suite. We aren’t sure whether this a bug or not. See #5 issue for longer explanation.

  • You can use x-doctest-options field in test-suite doctests to pass additional flags to the doctest.

  • For build-type: Configure packages, you can use defaultMainAutoconfWithDoctests function to make custom Setup.hs script.

  • If you use the default . in hs-source-dirs, then running doctests might fail with weird errors (ambigious module errors). Workaround is to move sources under src/ or some non-top-level directory.


Copyright 2017 Oleg Grenrus.

Available under the BSD 3-clause license.


1.0.2 – 2017-05-16

  • Add defaultMainAutoconfWithDoctests and addDoctestsUserHook.

  • Add support for .hsc and other preprocessed files (#8)

  • Add support for x-doctest-source-dirs and x-doctest-modules.

1.0.1 – 2017-05-05

  • Add support for x-doctest-options cabal-file field

  • Proper support for GHC-8.2.1 & Cabal-

  • Add support to default-extensions in library.

1 – 2017-01-31

  • First version. Released on an unsuspecting world.