Info Catalog ert: Top ert: Top ert: How to Run Tests

ert: Introduction

 
 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.  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.  Tests and Their
 Environment.
 

Info Catalog ert: Top ert: Top ert: How to Run Tests