Doctests

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