cabal-doctest alternatives and similar packages
Based on the "cabal" category.
Alternatively, view cabal-doctest alternatives based on common mentions on social networks and blogs.
8.4 0.0 cabal-doctest VS cabal-metaavoid cabal dependency hell by installing all your cabal dependencies at the same time
Do you think we are missing an alternative of cabal-doctest or a related project?
Setup.hs helper for running
For most use cases—a
.cabal file with a single library containing
doctests—adapting the simple example located
will be sufficient. (Note that this 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 System.Environment.Compat (unsetEnv) import Test.DocTest (doctest) main :: IO () main = do traverse_ putStrLn args -- optionally print arguments unsetEnv "GHC_ENVIRONMENT" -- see 'Notes'; you may not need this doctest args where args = flags ++ pkgs ++ module_sources
System.Environment.Compat module is from the
package. That's already in the transitive closure of
System.Environment.unsetEnv was added with GHC 7.8 so,
if you don't need to support versions of GHC older than 7.8, you can
Example with multiple .cabal components
cabal-doctest also supports more exotic use cases where a
contains more components with doctests than just the main library, including:
- Doctests in executables
- Doctests in Internal libraries (if using
Unlike the simple example shown above, these examples involve named
components. You don't need to change the
Setup.hs script to support
this use case. However, in this scenario
Build_doctests will generate extra
copies of the
module_sources values for each additional
Simplest approach is to use
x-doctest-components field, for example
x-doctest-components: lib lib:internal exe:example
In that case, the testdrive is general:
module Main where import Build_doctests (Component (..), components) import Data.Foldable (for_) import System.Environment.Compat (unsetEnv) import Test.DocTest (doctest) main :: IO () main = for_ components $ \(Component name flags pkgs sources) -> do print name putStrLn "----------------------------------------" let args = flags ++ pkgs ++ sources for_ args putStrLn unsetEnv "GHC_ENVIRONMENT" doctest args
There's also a more explicit approach: if you have an executable named
then separate values named
be generated in
Build_doctests. If the name has hyphens in it
cabal-doctest will convert those hyphens to
underscores (e.g., you'd get
bar values will have a
An example testsuite driver for this use case might look like this:
module Main where import Build_doctests (flags, pkgs, module_sources, flags_exe_my_exe, pkgs_exe_my_exe, module_sources_exe_my_exe) import Data.Foldable (traverse_) import System.Environment.Compat (unsetEnv) import Test.DocTest main :: IO () main = do unsetEnv "GHC_ENVRIONMENT" -- doctests for library traverse_ putStrLn libArgs doctest libArgs -- doctests for executable traverse_ putStrLn exeArgs doctest exeArgs where libArgs = flags ++ pkgs ++ module_sources exeArgs = flags_exe_my_exe ++ pkgs_exe_my_exe ++ module_sources_exe_my_exe
See this example for more details.
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
doctests test suite. See
the simple 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 (ambiguous 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-126.96.36.199:Language.Haskell.TH.Syntax.Name
Variable not in scope: polyQuickCheck :: Language.Haskell.TH.Syntax.Name -> Language.Haskell.TH.Lib.ExpQ
- From version 2, Stack sets the
GHC_ENVRIONMENTvariable, and GHC (as invoked by
doctest) will pick that up. This is undesirable:
cabal-doctestpasses all the necessary information on the command line already, and can lead to ambiguous module errors as GHC will load the environment in addition to what
cabal-doctestinstructs it to.
cabal-doctest tells GHC to ignore package environments
altogether on the command line. However, this is only possible since
GHC 8.2. If you are using
cabal-doctest with Stack 2 and GHC 8.0
or earlier and seeing ambiguous module errors or other mysterious
failures, try manually unsetting
GHC_ENVIRONMENT before invoking
Copyright 2017 Oleg Grenrus.
Available under the BSD 3-clause license.
*Note that all licence references and agreements mentioned in the cabal-doctest README section above are relevant to that project's source code only.