Function: ert-deftest

ert-deftest is an autoloaded macro defined in ert.el.gz.

Signature

(ert-deftest NAME () [DOCSTRING] [:expected-result RESULT-TYPE] [:tags '(TAG...)] BODY...)

Documentation

Define NAME (a symbol) as a test.

BODY is evaluated as a progn when the test is run. It should signal a condition on failure or just return if the test passes.

should, should-not, should-error, skip-when, and skip-unless are useful for assertions in BODY.

Use ert to run tests interactively.

Tests that are expected to fail can be marked as such using :expected-result. See ert-test-result-type-p for a description of valid values for RESULT-TYPE.

Macros in BODY are expanded when the test is defined, not when it is run. If a macro (possibly with side effects) is to be tested, it has to be wrapped in (eval (quote ...)).

If NAME is already defined as a test and Emacs is running in batch mode, an error is signaled.

Probably introduced at or before Emacs version 29.1.

Source Code

;; Defined in /usr/src/emacs/lisp/emacs-lisp/ert.el.gz
;;;###autoload
(cl-defmacro ert-deftest (name () &body docstring-keys-and-body)
  "Define NAME (a symbol) as a test.

BODY is evaluated as a `progn' when the test is run.  It should
signal a condition on failure or just return if the test passes.

`should', `should-not', `should-error', `skip-when', and
`skip-unless' are useful for assertions in BODY.

Use `ert' to run tests interactively.

Tests that are expected to fail can be marked as such
using :expected-result.  See `ert-test-result-type-p' for a
description of valid values for RESULT-TYPE.

Macros in BODY are expanded when the test is defined, not when it
is run.  If a macro (possibly with side effects) is to be tested,
it has to be wrapped in `(eval (quote ...))'.

If NAME is already defined as a test and Emacs is running
in batch mode, an error is signaled.

\(fn NAME () [DOCSTRING] [:expected-result RESULT-TYPE] \
[:tags \\='(TAG...)] BODY...)"
  (declare (debug (&define [&name "test@" symbolp]
			   sexp [&optional stringp]
			   [&rest keywordp sexp] def-body))
           (doc-string 3)
           (indent 2))
  (let ((documentation nil)
        (documentation-supplied-p nil))
    (when (stringp (car docstring-keys-and-body))
      (setq documentation (pop docstring-keys-and-body)
            documentation-supplied-p t))
    (cl-destructuring-bind
        ((&key (expected-result nil expected-result-supplied-p)
               (tags nil tags-supplied-p))
         body)
        (ert--parse-keys-and-body docstring-keys-and-body)
      `(cl-macrolet ((skip-when (form) `(ert--skip-when ,form))
                     (skip-unless (form) `(ert--skip-unless ,form)))
         (ert-set-test ',name
                       (make-ert-test
                        :name ',name
                        ,@(when documentation-supplied-p
                            `(:documentation ,documentation))
                        ,@(when expected-result-supplied-p
                            `(:expected-result-type ,expected-result))
                        ,@(when tags-supplied-p
                            `(:tags ,tags))
                        ;; Add `nil' after the body to enable compiler warnings
                        ;; about unused computations at the end.
                        :body (lambda () ,@body nil)
                        :file-name ,(or (macroexp-file-name) buffer-file-name)))
         ',name))))