Next: Interactive Debugging, Up: How to Debug Tests [Contents]

### 4.1 Understanding Explanations

Failed `should` forms are reported like this:

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

ERT shows what the `should` expression looked like and what values its subexpressions had: The source code of the assertion was `(should (= (+ 1 2) 4))`, which applied the function `=` to the arguments `3` and `4`, resulting in the value `nil`. In this case, the test is wrong; it should expect 3 rather than 4.

If a predicate like `equal` is used with `should`, ERT provides a so-called explanation:

    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))))

In this case, the function `equal` was applied to the arguments `(a b c)` and `(a b d)`. ERT’s explanation shows that the item at index 2 differs between the two lists; in one list, it is the atom c, in the other, it is the atom d.

In simple examples like the above, the explanation is unnecessary. But in cases where the difference is not immediately apparent, it can save time:

    F test1
        (ert-test-failed
         ((should
           (equal x y))
          :form
          (equal a a)
          :value nil :explanation
          (different-symbols-with-the-same-name a a)))

ERT only provides explanations for predicates that have an explanation function registered. See Defining Explanation Functions.