(A comment line starting with >>> denotes an expression.
All comment lines following an expression denote the result of that expression.
Result is defined by what an
REPL (e.g. ghci)
prints to stdout and stderr when evaluating that expression.)

With doctest you may check whether the implementation satisfies the given examples, by typing:

doctest Fib.hs

You may produce Haddock documentation for that module with:

haddock -h Fib.hs -o doc/

Example groups

Examples from a single Haddock comment are grouped together and share the same
scope. E.g. the following works:

-- |
-- >>> let x = 23
-- >>> x + 42
-- 65

If an example fails, subsequent examples from the same group are skipped. E.g.
for

-- |
-- >>> let x = 23
-- >>> let n = x + y
-- >>> print n

print n is not tried, because let n = x + y fails (y is not in scope!).

A note on performance

By default, doctest calls :reload between each group to clear GHCi’s scope
of any local definitions. This ensures that previous examples cannot influence
later ones. However, it can lead to performance penalties if you are using
doctest in a project with many modules. One possible remedy is to pass the
--fast flag to doctest, which disables calling :reload between groups.
If doctests are running too slowly, you might consider using --fast.
(With the caveat that the order in which groups appear now matters!)

However, note that due to a
bug on GHC 8.2.1 or later,
the performance of --fast suffers significantly when combined with the
--preserve-it flag (which keeps the value of GHCi’s it value between
examples).

Setup code

You can put setup code in a named chunk with the name $setup.
The setup code is run before each example group. If the setup code produces
any errors/failures, all tests from that module are skipped.

Note that you should not place setup code inbetween the module header (module ... where) and import declarations. GHC will not be able to parse it (issue
#167). It is best to place setup
code right after import declarations, but due to its declarative nature you can
place it anywhere inbetween top level declarations as well.

Multi-line input

GHCi supports commands which span multiple lines, and the same syntax works for doctest:

Note that >>> can be left off for the lines following the first: this is so that
haddock does not strip leading whitespace. The expected output has whitespace
stripped relative to the :}.

Some peculiarities on the ghci side mean that whitespace at the very start is lost.
This breaks the example broken, since the the x and y are aligned from ghci’s
perspective. A workaround is to avoid leading space, or add a newline such
that the indentation does not matter:

If you see an error like the following, ensure that
QuickCheck is a dependency
of the test-suite or executable running doctest.

<interactive>:39:3:
Not in scope: ‘polyQuickCheck’
In the splice: $(polyQuickCheck (mkName "doctest_prop"))
<interactive>:39:3:
GHC stage restriction:
‘polyQuickCheck’ is used in a top-level splice or annotation,
and must be imported, not defined locally
In the expression: polyQuickCheck (mkName "doctest_prop")
In the splice: $(polyQuickCheck (mkName "doctest_prop"))

Hiding examples from Haddock

You can put examples into [named chunks] named-chunks, and not refer to them
in the export list. That way they will not be part of the generated Haddock
documentation, but Doctest will still find them.

-- $
-- >>> 1 + 1
-- 2

Using GHC extensions

There’s two sets of GHC extensions involved when running Doctest:

The set of GHC extensions that are active when compiling the module code
(excluding the doctest examples). The easiest way to specify these extensions
is through [LANGUAGE pragmas] language-pragma in your source files.
(Doctest will not look at your cabal file.)

The set of GHC extensions that are active when executing the Doctest
examples. (These are not influenced by the LANGUAGE pragmas in the file.) The
recommended way to enable extensions for Doctest examples is to switch them
on like this:

These options will affect both the loading of the module and the execution of
the Doctest examples.

If you want to omit the information which language extensions are enabled from
the Doctest examples you can use the method described in [Hiding examples from
Haddock] (#hiding-examples-from-haddock), e.g.:

-- $
-- >>> :set -XTupleSections

Cabal integration

Doctest provides both, an executable and a library. The library exposes a
function doctest of type:

doctest :: [String] -> IO ()

Doctest’s own main is simply:

main = getArgs >>= doctest

Consequently, it is possible to create a custom executable for a project, by
passing all command-line arguments that are required for that project to
doctest. A simple example looks like this:

Changes in 0.7.0 - Print source location for failing tests - Output less clutter on failing examples - Expose Doctest's functionality through a very simplistic API, which can be used for cabal integration

Changes in 0.6.1 - Fix a parser bug with CR+LF line endings

Changes in 0.6.0 - Support for ghc-7.4 - Doctest now comes with it's own parser and does not depend on Haddock anymore