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
;; (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
will pass if the three calls to
equal all return non-
should is a macro with the same meaning as
better error reporting. See The
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
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.