2.1 Running Tests Interactively

You can run the tests that are currently defined in your Emacs with the command M-x ert RET t RET. (For an explanation of the t argument, see Test Selectors.) ERT will pop up a new buffer, the ERT results buffer, showing the results of the tests run. It looks like this:

Selector: t
Passed:  31
Skipped: 0
Failed:  2 (2 unexpected)
Total:   33/33

Started at:   2008-09-11 08:39:25-0700
Finished.
Finished at:  2008-09-11 08:39:27-0700

FF...............................

F addition-test
    (ert-test-failed
     ((should
       (=
        (+ 1 2)
        4))
      :form
      (= 3 4)
      :value nil))

F list-test
    (ert-test-failed
     ((should
       (equal
        (list 'a 'b 'c)
        '(a b d)))
      :form
      (equal
       (a b c)
       (a b d))
      :value nil :explanation
      (list-elt 2
                (different-atoms c d))))

At the top, there is a summary of the results: we ran all tests defined in the current Emacs (Selector: t), 31 of them passed, and 2 failed unexpectedly. See Expected Failures, for an explanation of the term unexpected in this context.

The line of dots and Fs is a progress bar where each character represents one test; it fills while the tests are running. A dot means that the test passed, an F means that it failed. Below the progress bar, ERT shows details about each test that had an unexpected result. In the example above, there are two failures, both due to failed should forms. See Understanding Explanations, for more details.

The following key bindings are available in the ERT results buffer:

RET ¶

Each name of a function or macro in this buffer is a button; moving point to it and typing RET jumps to its definition.

TAB ¶

S-TAB

Cycle between buttons forward (forward-button) and backward (backward-button).

r ¶

Re-run the test near point on its own (ert-results-rerun-test-at-point).

d ¶

Re-run the test near point on its own with the debugger enabled (ert-results-rerun-test-at-point-debugging-errors).

R ¶

Re-run all tests (ert-results-rerun-all-tests).

. ¶

Jump to the definition of the test near point (ert-results-find-test-at-point-other-window). This has the same effect as RET, but does not require point to be on the name of the test.

b ¶

Show the backtrace of a failed test (ert-results-pop-to-backtrace-for-test-at-point). See Backtraces in GNU Emacs Lisp Reference Manual, for more information about backtraces.

l ¶

Show the list of should forms executed in the test (ert-results-pop-to-should-forms-for-test-at-point).

m ¶

Show any messages that were generated (with the Lisp function message) in a test or any of the code that it invoked (ert-results-pop-to-messages-for-test-at-point).

L ¶

By default, long expressions in the failure details are abbreviated using print-length and print-level. Increase the limits to show more of the expression by moving point to a test failure with this command (ert-results-toggle-printer-limits-for-test-at-point).

D ¶

Delete a test from the running Emacs session (ert-delete-test).

h ¶

Show the documentation of a test (ert-describe-test).

T ¶

Display test timings for the last run (ert-results-pop-to-timings).

M-x ert-delete-all-tests ¶

Delete all tests from the running session.

M-x ert-describe-test ¶

Prompt for a test and then show its documentation.