These are like a Python “doctest”, but for Emacs Lisp and with an Emacs twist. A doctest is a test written inside a docstring that looks like:
(defun plus (arg1 arg2)
"Return sum of ARG1 and ARG2.
>> (plus 1 1)
=> 2
>> (plus (plus 5 3) 2) ; with nesting
=> 10
>> (format \"%s\" (plus 1 2))
=> \"3\""
(+ arg1 arg2))There are benefits:
- It’s a clean way to test elisp code without any heavy dependencies
- It encourages functions that are pure or at least side-effect-free
- Your unit tests turn into documentation that your users can read!
- Use
M-x doctestto run doctests on an entire buffer. - Use
M-x doctest-hereto run the doctest on the current line. - Use
M-x doctest-defunto run the current defun’s doctests.
- Python doctest, the original
- Elixir supports doctests
- I copied the use of
>>and=>to mark input and output from Ruby doctest; prefixing output with=>is useful because checkdoc complains if lines start with an opening parentheses, which will happen often in elisp code.