Doctest for Emacs

Description

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!

Usage

• Use M-x doctest to run doctests on an entire buffer.
• Use M-x doctest-here to run the doctest on the current line.
• Use M-x doctest-defun to run the current defun’s doctests.

Related

• 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.