#+TITLE: Assert Explainer (or: can we have py.test in Haskell?)

Assert Explainer is a library & GHC source plugin to help writing assertions. In
particular, it is to help you understand *why* an assertion has failed.

How many times have you written some kind of unit test assertion like

#+BEGIN_SRC haskell
  assert (length xs == 4)
#+END_SRC

And got:

#+BEGIN_SRC
exception: Assertion failed!
#+END_SRC

This sucks! Why did the assertion fail? When things have gone wrong, it's too late to find out way - the information has gone.

With AssertExplainer, you simply write =Bool=-valued expressions, and
the plugin will take care of the rest.

First:

#+BEGIN_SRC haskell
{-# OPTIONS -fplugin=AssertExplainer #-}
#+END_SRC

Then write your assertion. The above would be simply:

#+BEGIN_SRC haskell
  assert (length xs == 4)
#+END_SRC

No need for lots of special =assertEqual= etc functions.

When the assertion fails, you will get much more context:

#+BEGIN_SRC
✘ Assertion failed!
    length xs == 4 /= True (at Test.hs:18:12-25)

  I found the following sub-expressions:
    - length xs = 3
    - xs = [1,2,3]
#+END_SRC

Ultimately, my goal is to write something more akin to
[[https://docs.pytest.org/en/latest/example/reportingdemo.html#tbreportdemo][py.test's assertion magic]]. This is just a proof of concept right now,
but maybe we'll get there!