File: ert.el.html

ERT is a tool for automated testing in Emacs Lisp. Its main features are facilities for defining and running test cases and reporting the results as well as for debugging test failures interactively.

The main entry points are ert-deftest, which is similar to defun but defines a test, and ert-run-tests-interactively, which runs tests and offers an interactive interface for inspecting results and debugging. There is also ert-run-tests-batch-and-exit for non-interactive use.

The body of ert-deftest forms resembles a function body, but the additional operators should, should-not, should-error, skip-when and skip-unless are available. should is similar to cl's assert, but signals a different error when its condition is violated that is caught and processed by ERT. In addition, it analyzes its argument form and records information that helps debugging (cl-assert tries to do something similar when its second argument SHOW-ARGS is true, but should is more sophisticated). For information on should-not and should-error, see their docstrings. The skip-when and skip-unless forms skip the test immediately, which is useful for checking the test environment (like availability of features, external binaries, etc).

See ERT's Info manual (ert) Top as well as the docstrings for more details. To see some examples of tests written in ERT, see the test suite distributed with the Emacs source distribution (in the "test" directory).

Defined variables (21)

ert--find-test-regexpThe regexp the ‘find-function’ mechanisms use for finding test definitions.
ert--infosThe stack of ‘ert-info’ infos that currently apply.
ert--running-testsList of tests that are currently in execution.
ert--selector-historyList of recent test selectors read from terminal.
ert-batch-backtrace-line-lengthTarget length for lines in ERT batch backtraces.
ert-batch-backtrace-right-marginThe maximum line length for printing backtraces in ‘ert-run-tests-batch’.
ert-batch-print-length‘print-length’ setting used in ‘ert-run-tests-batch’.
ert-batch-print-level‘print-level’ setting used in ‘ert-run-tests-batch’.
ert-debug-on-errorNon-nil means enter debugger when a test fails or terminates with an error.
ert-load-file-nameThe name of the loaded ERT test file, a string.
ert-quietNon-nil makes ERT only print important information in batch mode.
ert-results-mode-abbrev-tableAbbrev table for ‘ert-results-mode’.
ert-results-mode-hookHook run after entering ‘ert-results-mode’.
ert-results-mode-mapKeymap for ‘ert-results-mode’.
ert-results-mode-menuMenu for ‘ert-results-mode’.
ert-results-mode-syntax-tableSyntax table for ‘ert-results-mode’.
ert-simple-view-mode-abbrev-tableAbbrev table for ‘ert-simple-view-mode’.
ert-simple-view-mode-hookHook run after entering ‘ert-simple-view-mode’.
ert-simple-view-mode-mapKeymap for ‘ert-simple-view-mode’.
ert-simple-view-mode-syntax-tableSyntax table for ‘ert-simple-view-mode’.
ert-test-run-redisplay-interval-secsHow many seconds ERT should wait between redisplays while running tests.

Defined functions (302)

copy-ert--ewoc-entry(ARG)
copy-ert--stats(ARG)
copy-ert--test-execution-info(ARG)
copy-ert-test(ARG)
copy-ert-test-aborted-with-non-local-exit(ARG)
copy-ert-test-failed(ARG)
copy-ert-test-passed(ARG)
copy-ert-test-quit(ARG)
copy-ert-test-result(ARG)
copy-ert-test-result-with-condition(ARG)
copy-ert-test-skipped(ARG)
ert(SELECTOR)
ert--abbreviate-string(S LEN SUFFIXP)
ert--activate-font-lock-keywords()
ert--button-action-position()
ert--erts-specifications(END)
ert--ewoc-entry-expanded-p(CL-X)
ert--ewoc-entry-expanded-p--cmacro(CL-WHOLE-ARG CL-X)
ert--ewoc-entry-extended-printer-limits-p(CL-X)
ert--ewoc-entry-extended-printer-limits-p--cmacro(CL-WHOLE-ARG CL-X)
ert--ewoc-entry-hidden-p(CL-X)
ert--ewoc-entry-hidden-p--cmacro(CL-WHOLE-ARG CL-X)
ert--ewoc-entry-p(CL-X)
ert--ewoc-entry-p--cmacro(CL-WHOLE-ARG CL-X)
ert--ewoc-entry-test(CL-X)
ert--ewoc-entry-test--cmacro(CL-WHOLE-ARG CL-X)
ert--ewoc-position(EWOC NODE)
ert--expand-should(WHOLE FORM INNER-EXPANDER)
ert--expand-should-1(WHOLE FORM INNER-EXPANDER)
ert--explain-equal(A B)
ert--explain-equal-including-properties(A B)
ert--explain-equal-including-properties-rec(A B)
ert--explain-equal-rec(A B)
ert--explain-format-atom(X)
ert--explain-string-equal(A B)
ert--force-message-log-buffer-truncation()
ert--format-time-iso8601(TIME)
ert--get-explainer(FN-NAME)
ert--insert-backtrace-header(NAME)
ert--insert-human-readable-selector(SELECTOR)
ert--insert-infos(RESULT)
ert--make-stats(TESTS SELECTOR)
ert--make-xrefs-region(BEGIN END)
ert--parse-keys-and-body(KEYS-AND-BODY)
ert--plist-difference-explanation(A B)
ert--pp-with-indentation-and-newline(OBJECT)
ert--print-test-for-ewoc(ENTRY)
ert--remove-from-list
ert--results-expand-collapse-button-action(BUTTON)
ert--results-font-lock-function(ENABLEDP)
ert--results-format-expected-unexpected(EXPECTED UNEXPECTED)
ert--results-move(NODE EWOC-FN ERROR-MESSAGE)
ert--results-progress-bar-button-action(BUTTON)
ert--results-test-at-point-allow-redefinition()
ert--results-test-at-point-no-redefinition(&optional ERROR)
ert--results-test-node-at-point()
ert--results-test-node-or-null-at-point()
ert--results-update-after-test-redefinition(POS NEW-TEST)
ert--results-update-ewoc-hf(EWOC STATS)
ert--results-update-stats-display(EWOC STATS)
ert--results-update-stats-display-maybe(EWOC STATS)
ert--run-test-debugger(INFO CONDITION DEBUGFUN)
ert--run-test-internal(TEST-EXECUTION-INFO)
ert--setup-results-buffer(STATS LISTENER)
ert--should-error-handle-error(FORM-DESCRIPTION-FN CONDITION TYPE EXCLUDE-SUBTYPES)
ert--signal-should-execution(FORM-DESCRIPTION)
ert--significant-plist-keys(PLIST)
ert--skip-unless(FORM)
ert--skip-when(FORM)
ert--special-operator-p(THING)
ert--stats-aborted-p(CL-X)
ert--stats-aborted-p--cmacro(CL-WHOLE-ARG CL-X)
ert--stats-current-test(CL-X)
ert--stats-current-test--cmacro(CL-WHOLE-ARG CL-X)
ert--stats-end-time(CL-X)
ert--stats-end-time--cmacro(CL-WHOLE-ARG CL-X)
ert--stats-failed-expected(CL-X)
ert--stats-failed-expected--cmacro(CL-WHOLE-ARG CL-X)
ert--stats-failed-unexpected(CL-X)
ert--stats-failed-unexpected--cmacro(CL-WHOLE-ARG CL-X)
ert--stats-next-redisplay(CL-X)
ert--stats-next-redisplay--cmacro(CL-WHOLE-ARG CL-X)
ert--stats-p(CL-X)
ert--stats-p--cmacro(CL-WHOLE-ARG CL-X)
ert--stats-passed-expected(CL-X)
ert--stats-passed-expected--cmacro(CL-WHOLE-ARG CL-X)
ert--stats-passed-unexpected(CL-X)
ert--stats-passed-unexpected--cmacro(CL-WHOLE-ARG CL-X)
ert--stats-selector(CL-X)
ert--stats-selector--cmacro(CL-WHOLE-ARG CL-X)
ert--stats-set-test-and-result(STATS POS TEST RESULT)
ert--stats-skipped(CL-X)
ert--stats-skipped--cmacro(CL-WHOLE-ARG CL-X)
ert--stats-start-time(CL-X)
ert--stats-start-time--cmacro(CL-WHOLE-ARG CL-X)
ert--stats-test-end-times(CL-X)
ert--stats-test-end-times--cmacro(CL-WHOLE-ARG CL-X)
ert--stats-test-key(TEST)
ert--stats-test-map(CL-X)
ert--stats-test-map--cmacro(CL-WHOLE-ARG CL-X)
ert--stats-test-pos(STATS TEST)
ert--stats-test-results(CL-X)
ert--stats-test-results--cmacro(CL-WHOLE-ARG CL-X)
ert--stats-test-start-times(CL-X)
ert--stats-test-start-times--cmacro(CL-WHOLE-ARG CL-X)
ert--stats-tests(CL-X)
ert--stats-tests--cmacro(CL-WHOLE-ARG CL-X)
ert--string-first-line(S)
ert--test-execution-info-ert-debug-on-error(CL-X)
ert--test-execution-info-ert-debug-on-error--cmacro(CL-WHOLE-ARG CL-X)
ert--test-execution-info-exit-continuation(CL-X)
ert--test-execution-info-exit-continuation--cmacro(CL-WHOLE-ARG CL-X)
ert--test-execution-info-p(CL-X)
ert--test-execution-info-p--cmacro(CL-WHOLE-ARG CL-X)
ert--test-execution-info-result(CL-X)
ert--test-execution-info-result--cmacro(CL-WHOLE-ARG CL-X)
ert--test-execution-info-test(CL-X)
ert--test-execution-info-test--cmacro(CL-WHOLE-ARG CL-X)
ert--test-name-button-action(BUTTON)
ert--tests-running-mode-line-indicator()
ert--unload-function()
ert-char-for-test-result(RESULT EXPECTEDP)
ert-deftest(NAME () [DOCSTRING] [:expected-result RESULT-TYPE] [:tags '(TAG...)] BODY...)
ert-delete-all-tests()
ert-delete-test(TEST-NAME)
ert-describe-test(TEST-OR-TEST-NAME)
ert-equal-including-properties(O1 O2)
ert-face-for-stats(STATS)
ert-face-for-test-result(EXPECTEDP)
ert-fail(DATA)
ert-find-test-other-window(TEST-NAME)
ert-get-test(SYMBOL)
ert-info
ert-insert-test-name-button(TEST-NAME)
ert-make-test-unbound(SYMBOL)
ert-pass()
ert-read-test-name(PROMPT &optional DEFAULT HISTORY ADD-DEFAULT-TO-PROMPT)
ert-read-test-name-at-point(PROMPT)
ert-reason-for-test-result(RESULT)
ert-results-describe-test-at-point()
ert-results-find-test-at-point-other-window()
ert-results-jump-between-summary-and-result()
ert-results-mode()
ert-results-mode-menu(ARG1)
ert-results-next-test()
ert-results-pop-to-backtrace-for-test-at-point()
ert-results-pop-to-messages-for-test-at-point()
ert-results-pop-to-should-forms-for-test-at-point()
ert-results-pop-to-timings()
ert-results-previous-test()
ert-results-rerun-all-tests()
ert-results-rerun-test-at-point()
ert-results-rerun-test-at-point-debugging-errors()
ert-results-toggle-printer-limits-for-test-at-point()
ert-run-or-rerun-test(STATS TEST LISTENER)
ert-run-test(ERT-TEST)
ert-run-tests(SELECTOR LISTENER &optional INTERACTIVELY)
ert-run-tests-batch(&optional SELECTOR)
ert-run-tests-batch-and-exit(&optional SELECTOR)
ert-run-tests-interactively(SELECTOR)
ert-running-test()
ert-select-tests(SELECTOR UNIVERSE)
ert-set-test(SYMBOL DEFINITION)
ert-simple-view-mode()
ert-skip(DATA)
ert-stats-completed(STATS)
ert-stats-completed-expected(STATS)
ert-stats-completed-unexpected(STATS)
ert-stats-skipped(STATS)
ert-stats-total(STATS)
ert-string-for-test-result(RESULT EXPECTEDP)
ert-summarize-tests-batch-and-exit(&optional HIGH)
ert-test--erts-test(GEN-SPECS FILE)
ert-test-aborted-with-non-local-exit-duration(CL-X)
ert-test-aborted-with-non-local-exit-duration--cmacro(CL-WHOLE-ARG CL-X)
ert-test-aborted-with-non-local-exit-messages(CL-X)
ert-test-aborted-with-non-local-exit-messages--cmacro(CL-WHOLE-ARG CL-X)
ert-test-aborted-with-non-local-exit-p(CL-X)
ert-test-aborted-with-non-local-exit-p--cmacro(CL-WHOLE-ARG CL-X)
ert-test-aborted-with-non-local-exit-should-forms(CL-X)
ert-test-aborted-with-non-local-exit-should-forms--cmacro(CL-WHOLE-ARG CL-X)
ert-test-at-point()
ert-test-body(CL-X)
ert-test-body--cmacro(CL-WHOLE-ARG CL-X)
ert-test-boundp(SYMBOL)
ert-test-documentation(CL-X)
ert-test-documentation--cmacro(CL-WHOLE-ARG CL-X)
ert-test-erts-file(FILE &optional TRANSFORM)
ert-test-expected-result-type(CL-X)
ert-test-expected-result-type--cmacro(CL-WHOLE-ARG CL-X)
ert-test-failed-backtrace(CL-X)
ert-test-failed-backtrace--cmacro(CL-WHOLE-ARG CL-X)
ert-test-failed-condition(CL-X)
ert-test-failed-condition--cmacro(CL-WHOLE-ARG CL-X)
ert-test-failed-duration(CL-X)
ert-test-failed-duration--cmacro(CL-WHOLE-ARG CL-X)
ert-test-failed-infos(CL-X)
ert-test-failed-infos--cmacro(CL-WHOLE-ARG CL-X)
ert-test-failed-messages(CL-X)
ert-test-failed-messages--cmacro(CL-WHOLE-ARG CL-X)
ert-test-failed-p(CL-X)
ert-test-failed-p--cmacro(CL-WHOLE-ARG CL-X)
ert-test-failed-should-forms(CL-X)
ert-test-failed-should-forms--cmacro(CL-WHOLE-ARG CL-X)
ert-test-file-name(CL-X)
ert-test-file-name--cmacro(CL-WHOLE-ARG CL-X)
ert-test-location(TEST)
ert-test-most-recent-result(CL-X)
ert-test-most-recent-result--cmacro(CL-WHOLE-ARG CL-X)
ert-test-name(CL-X)
ert-test-name--cmacro(CL-WHOLE-ARG CL-X)
ert-test-p(CL-X)
ert-test-p--cmacro(CL-WHOLE-ARG CL-X)
ert-test-passed-duration(CL-X)
ert-test-passed-duration--cmacro(CL-WHOLE-ARG CL-X)
ert-test-passed-messages(CL-X)
ert-test-passed-messages--cmacro(CL-WHOLE-ARG CL-X)
ert-test-passed-p(CL-X)
ert-test-passed-p--cmacro(CL-WHOLE-ARG CL-X)
ert-test-passed-should-forms(CL-X)
ert-test-passed-should-forms--cmacro(CL-WHOLE-ARG CL-X)
ert-test-quit-backtrace(CL-X)
ert-test-quit-backtrace--cmacro(CL-WHOLE-ARG CL-X)
ert-test-quit-condition(CL-X)
ert-test-quit-condition--cmacro(CL-WHOLE-ARG CL-X)
ert-test-quit-duration(CL-X)
ert-test-quit-duration--cmacro(CL-WHOLE-ARG CL-X)
ert-test-quit-infos(CL-X)
ert-test-quit-infos--cmacro(CL-WHOLE-ARG CL-X)
ert-test-quit-messages(CL-X)
ert-test-quit-messages--cmacro(CL-WHOLE-ARG CL-X)
ert-test-quit-p(CL-X)
ert-test-quit-p--cmacro(CL-WHOLE-ARG CL-X)
ert-test-quit-should-forms(CL-X)
ert-test-quit-should-forms--cmacro(CL-WHOLE-ARG CL-X)
ert-test-result-duration(CL-X)
ert-test-result-duration--cmacro(CL-WHOLE-ARG CL-X)
ert-test-result-expected-p(TEST RESULT)
ert-test-result-messages(CL-X)
ert-test-result-messages--cmacro(CL-WHOLE-ARG CL-X)
ert-test-result-p(CL-X)
ert-test-result-p--cmacro(CL-WHOLE-ARG CL-X)
ert-test-result-should-forms(CL-X)
ert-test-result-should-forms--cmacro(CL-WHOLE-ARG CL-X)
ert-test-result-type-p(RESULT RESULT-TYPE)
ert-test-result-with-condition-backtrace(CL-X)
ert-test-result-with-condition-backtrace--cmacro(CL-WHOLE-ARG CL-X)
ert-test-result-with-condition-condition(CL-X)
ert-test-result-with-condition-condition--cmacro(CL-WHOLE-ARG CL-X)
ert-test-result-with-condition-duration(CL-X)
ert-test-result-with-condition-duration--cmacro(CL-WHOLE-ARG CL-X)
ert-test-result-with-condition-infos(CL-X)
ert-test-result-with-condition-infos--cmacro(CL-WHOLE-ARG CL-X)
ert-test-result-with-condition-messages(CL-X)
ert-test-result-with-condition-messages--cmacro(CL-WHOLE-ARG CL-X)
ert-test-result-with-condition-p(CL-X)
ert-test-result-with-condition-p--cmacro(CL-WHOLE-ARG CL-X)
ert-test-result-with-condition-should-forms(CL-X)
ert-test-result-with-condition-should-forms--cmacro(CL-WHOLE-ARG CL-X)
ert-test-skipped-backtrace(CL-X)
ert-test-skipped-backtrace--cmacro(CL-WHOLE-ARG CL-X)
ert-test-skipped-condition(CL-X)
ert-test-skipped-condition--cmacro(CL-WHOLE-ARG CL-X)
ert-test-skipped-duration(CL-X)
ert-test-skipped-duration--cmacro(CL-WHOLE-ARG CL-X)
ert-test-skipped-infos(CL-X)
ert-test-skipped-infos--cmacro(CL-WHOLE-ARG CL-X)
ert-test-skipped-messages(CL-X)
ert-test-skipped-messages--cmacro(CL-WHOLE-ARG CL-X)
ert-test-skipped-p(CL-X)
ert-test-skipped-p--cmacro(CL-WHOLE-ARG CL-X)
ert-test-skipped-should-forms(CL-X)
ert-test-skipped-should-forms--cmacro(CL-WHOLE-ARG CL-X)
ert-test-tags(CL-X)
ert-test-tags--cmacro(CL-WHOLE-ARG CL-X)
ert-write-junit-test-report(STATS)
ert-write-junit-test-summary-report(&rest LOGFILES)
make-ert--ewoc-entry
make-ert--ewoc-entry--cmacro
make-ert--stats
make-ert--stats--cmacro
make-ert--test-execution-info
make-ert--test-execution-info--cmacro
make-ert-test
make-ert-test--cmacro
make-ert-test-aborted-with-non-local-exit
make-ert-test-aborted-with-non-local-exit--cmacro
make-ert-test-failed
make-ert-test-failed--cmacro
make-ert-test-passed
make-ert-test-passed--cmacro
make-ert-test-quit
make-ert-test-quit--cmacro
make-ert-test-result
make-ert-test-result--cmacro
make-ert-test-result-with-condition
make-ert-test-result-with-condition--cmacro
make-ert-test-skipped
make-ert-test-skipped--cmacro
should(FORM)
should-error(FORM &rest KEYWORD-ARGS)
should-not(FORM)

Defined faces (2)

ert-test-result-expectedFace used for expected results in the ERT results buffer.
ert-test-result-unexpectedFace used for unexpected results in the ERT results buffer.