Next: Expected Failures, Up: How to Write Tests [Contents]

### 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 (see Assertions in Common Lisp Extensions), 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.

See Understanding Explanations, for more details on what `should` reports.

Next: Expected Failures, Up: How to Write Tests [Contents]