Setup.hs helper for running
See [https://github.com/phadej/cabal-doctest/tree/master/example] 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
section in your
.cabal file. For example:
custom-setup setup-depends: base >= 4 && <5, Cabal, cabal-doctest >= 1 && <1.1
Cabal dependency is needed because of
You'll also need to specify
build-type: Custom at the top of the
file. Now put this into your
module Main where import Distribution.Extra.Doctest (defaultMainWithDoctests) main :: IO () main = defaultMainWithDoctests "doctests"
When you build your project, this
Setup will generate a
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 where args = flags ++ pkgs ++ module_sources
Setup.hs supports few extensions fields
pkg.cabal files to customise the
doctest runner behaviour, without
customising the default
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-optionsAdditional arguments passed into
x-doctest-modulesAdditional modules to
doctest. May be useful if you have
doctestin test or executables (i.e not default library complonent).
x-doctest-src-dirsAdditional source directories to look for the modules.
Recent versions of
Cabal(for instance, 2.0) can choose to build a package's
doctesttest suite before the library. However, in order for
cabal-doctestto work correctly, the library must be built first, as
doctestrelies on the presence of generated files that are only created when the library is built. See #19.
A hacky workaround for this problem is to depend on the library itself in a
docteststest suite. See the example's .cabal file for a demonstration. (This assumes that the test suite has the ability to read build artifacts from the library, a separate build component. In practice, this assumption holds, which is why this library works at all.)
custom-setupsection is supported starting from
cabal-install-1.24. For older
cabal-install'syou have to install custom setup dependencies manually.
custom-setupstarting from version 1.3.3. Before that you have to use
explicit-setup-depssetting in your
There is an issue in the Cabal issue tracker about adding
cabal doctestcommand. After that command is implemented, this library will be deprecated.
You can use
test-suite docteststo pass additional flags to the
build-type: Configurepackages, you can use
defaultMainAutoconfWithDoctestsfunction to make custom
If you use the default
hs-source-dirs, then running
doctestsmight fail with weird errors (ambigious module errors). Workaround is to move sources under
src/or some non-top-level directory.
extensions:field isn't supported. Upgrade your
.cabalfile to use at least
cabal-version: >= 1.10and use
If you use QuickCheck properties (
prop>) in your doctests, the
test-suite doctestshould depend on
template-haskell. This is a little HACK: These dependencies aren't needed to build the
docteststest-suite executable. However, as we let
Cabalresolve dependencies, we can pass the resolved (and installed!) package identifiers to to the
doctestcommand. This way,
template-haskellare available to
doctest, otherwise you'll get errors like:
Variable not in scope: mkName :: [Char] -> template-haskell-18.104.22.168:Language.Haskell.TH.Syntax.Name
Variable not in scope: polyQuickCheck :: Language.Haskell.TH.Syntax.Name -> Language.Haskell.TH.Lib.ExpQ
Copyright 2017 Oleg Grenrus.
Available under the BSD 3-clause license.
1.0.3 -- 2017-11-02
Add an explicit
1.0.2 -- 2017-05-16
Add support for
.hscand other preprocessed files (#8)
Add support for
1.0.1 -- 2017-05-05
Add support for
Proper support for GHC-8.2.1 & Cabal-22.214.171.124
Add support to
1 -- 2017-01-31
- First version. Released on an unsuspecting world.