View Source doctest

An OTP library to test -doc attributes.

Requirements

OTP >= 27.

Installation

% rebar.config
{profiles, [
    {test, [
        {deps, [{doctest, "0.1.0"}]}
    ]}
]}.

Usage

Via parse_transform

Take this module:

-module(math).
-moduledoc """
A module for basic arithmetic.
""".

-export([add/2]).

-ifdef(TEST).
-include_lib("doctest/include/doctest.hrl").
% -doctest <see the options section>.
-endif.

-doc """
Adds two numbers together.

_Example_:
```erlang
1> math:add(0, 1).
1
2> math:add(
.. 1,
.. 1
.. ).
2
```
""".
add(A, B) ->
    A+B.

This will produce the file <project_cwd>/test/math_DOCTEST.erl with the following tests:

% <name>_<arity>_test
add_2_test() ->
    [
        ?assertEqual(math:add(0, 1), 1),
        ?assertEqual(math:add( 1, 1 ), 2)
    ].

Note that the code is defined like the Erlang shell, starting with 1&gt and continues in multiple lines with ... The result is a value without starting with those shell symbols.

Options

Options are defined via the -doctest attribute and can be defined multiple times.

Available options

boolean(): enable or disable tests.
```
-doctest true.
```
atom(): define the test module name.
```
-doctest math_DOCTEST.
```
proplists:proplist() | all: define the functions to be tested.
```
-doctest [add/2].
```
string() | {abs, string()} | {cwd, string()}: define the test file location.
```
-doctest {abs, "/tmp/doctests"}.
```

map(): define all or partial options.

-doctest #{
    enabled => true,
    module => math_DOCTEST,
    funs => [add/2],
    location => {abs, "/tmp/doctests"}
}.

Important

Currently, only exported functions can be tested.

TODO

[ ] All kinds of tests;
[ ] Ability to test modules via function and not only via parse_transform;
[ ] Maybe add a mechanism to test non-exported functions, but probably this makes no sense;
[ ] Test and fix issues on umbrella applications;
[ ] Improve docs;
[ ] Implement -moduledoc tests in the same way that for -doc.