1 Introduction

ERT allows you to define tests in addition to functions, macros, variables, and the other usual Lisp constructs. Tests are simply Lisp code: code that invokes other code and checks whether it behaves as expected.

ERT keeps track of the tests that are defined and provides convenient commands to run them to verify whether the definitions that are currently loaded in Emacs pass the tests.

Some Lisp files have comments like the following (adapted from the package pp.el):

;; (pp-to-string '(quote quote))          ; expected: "'quote"
;; (pp-to-string '((quote a) (quote b)))  ; expected: "('a 'b)\n"
;; (pp-to-string '('a 'b))                ; same as above

The code contained in these comments can be evaluated from time to time to compare the output with the expected output. ERT formalizes this and introduces a common convention, which simplifies Emacs development, since programmers no longer have to manually find and evaluate such comments.

An ERT test definition equivalent to the above comments is this:

(ert-deftest pp-test-quote ()
  "Tests the rendering of `quote' symbols in `pp-to-string'."
  (should (equal (pp-to-string '(quote quote)) "'quote"))
  (should (equal (pp-to-string '((quote a) (quote b))) "('a 'b)\n"))
  (should (equal (pp-to-string '('a 'b)) "('a 'b)\n")))

If you know defun, the syntax of ert-deftest should look familiar: This example defines a test named pp-test-quote that will pass if the three calls to equal all return non-nil.

should is a macro with the same meaning as cl-assert but better error reporting. See The should Macro.

Each test should have a name that describes what functionality it tests. Test names can be chosen arbitrarily—they are in a namespace separate from functions and variables—but should follow the usual Emacs Lisp convention of having a prefix that indicates which package they belong to. Test names are displayed by ERT when reporting failures and can be used when selecting which tests to run.

The empty parentheses () in the first line don’t currently have any meaning and are reserved for future extension. They also make the syntax of ert-deftest more similar to that of defun.

The docstring describes what feature this test tests. When running tests interactively, the first line of the docstring is displayed for tests that fail, so it is good if the first line makes sense on its own.

The body of a test can be arbitrary Lisp code. It should have as few side effects as possible; each test should be written to clean up after itself, leaving Emacs in the same state as it was before the test. Tests should clean up even if they fail. See Tests and Their Environment.