ert: The should Macro
3.1 The ‘should’ Macro
======================
Test bodies can include arbitrary code; but to be useful, they need to
check whether the code being tested (or _code under test_) does what it
is supposed to do. The macro ‘should’ is similar to ‘cl-assert’ from
the cl package (
(cl)Assertions), but analyzes its argument form
and records information that ERT can display to help debugging.
This test definition
(ert-deftest addition-test ()
(should (= (+ 1 2) 4)))
will produce this output when run via ‘M-x ert’:
F addition-test
(ert-test-failed
((should
(=
(+ 1 2)
4))
:form
(= 3 4)
:value nil))
In this example, ‘should’ recorded the fact that (= (+ 1 2) 4)
reduced to (= 3 4) before it reduced to ‘nil’. When debugging why the
test failed, it helps to know that the function ‘+’ returned 3 here.
ERT records the return value for any predicate called directly within
‘should’.
In addition to ‘should’, ERT provides ‘should-not’, which checks that
the predicate returns ‘nil’, and ‘should-error’, which checks that the
form called within it signals an error. An example use of
‘should-error’:
(ert-deftest test-divide-by-zero ()
(should-error (/ 1 0)
:type 'arith-error))
This checks that dividing one by zero signals an error of type
‘arith-error’. The ‘:type’ argument to ‘should-error’ is optional; if
absent, any type of error is accepted. ‘should-error’ returns an error
description of the error that was signaled, to allow additional checks
to be made. The error description has the format ‘(ERROR-SYMBOL .
DATA)’.
There is no ‘should-not-error’ macro since tests that signal an error
fail anyway, so ‘should-not-error’ is effectively the default.
Understanding Explanations, for more details on what ‘should’
reports.
Info Catalog
ert: How to Write Tests
ert: Expected Failures