Doctests
| Examples in docs | |
| They run as tests | |
| Write runnable docs | |
| When doctests win |
Examples in docs
A doctest is an example placed inside documentation. It shows input and result exactly as an interactive session would, so readers can trust the example by reading it.
@doc """
Adds two numbers.
## Examples
iex> Calc.add(1, 2)
3
"""
They run as tests
Documentation examples stay honest because the test suite executes them. One line in the test module pulls every example of the target module into the run.
defmodule CalcTest do
use ExUnit.Case
doctest Calc
end
The usual command runs doctests together with unit tests, so stale examples fail the build like any other broken test.
mix test
Write runnable docs
Keep each example tiny: one call, one visible result. Short examples are easy to read and easy to keep green when the code evolves.
def add(a, b), do: a + b
Avoid hidden state in examples. Prefer plain values in and plain values out, with no files, no network, and no clock involved.
When doctests win
Doctests win for small pure helpers with stable output: math, string shaping, list transforms.
Plain tests win for behavior with side effects or randomness: file writes, HTTP calls, time handling, and anything that needs setup. Use both forms in one suite without hesitation.
Next: Debugging
Article author: Arthur Isaev
