doctest

doctest copied to clipboard

#+TITLE: Doctest for Emacs (archive) #+OPTIONS: toc:3 author:t creator:nil num:nil #+AUTHOR: Chris Rayner #+EMAIL: [email protected]

This package has a new home: https://github.com/ag91/doctest

• Description These are like a [[https://docs.python.org/3/library/doctest.html][Python "doctest"]], but for Emacs Lisp and with an Emacs twist. A doctest is a test written inside a docstring that looks like:

  #+begin_src elisp (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)) #+end_src

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
  • [[https://docs.python.org/3/library/doctest.html][Python doctest]], the original
  • [[https://elixir-lang.org/getting-started/mix-otp/docs-tests-and-with.html][Elixir]] supports doctests
  • I copied the use of ~>>~ and ~=>~ to mark input and output from [[https://github.com/tslocke/rubydoctest][Ruby doctest]]; prefixing output with ~=>~ is useful because [[https://www.emacswiki.org/emacs/CheckDoc][checkdoc]] complains if lines start with an opening parentheses, which will happen often in elisp code.