Generate "runners" used in tabular tests of assertions and assertion-like functions.

A typical example:

  a = assertion_runners_for(&assert_equal/2)

  ["value", "value"] |> a.pass.()
  ["value", "     "] |> a.fail.("Assertion with === failed")
                     |> a.plus.(left: "value", right: "     ")

assert_equal takes two arguments, and those are passed to the runner functions (pass and fail) in a list. If there's only a single argument, the enclosing list can be omitted:

  a = assertion_runners_for(&assert_ok/1)

  :ok     |> a.pass.()
  :error  |> a.fail.(Messages.not_ok)

The functions created are, unless noted in the individual descriptions below, these:

• pass: A runner that applies a function to arguments and checks for success. What, precisely, counts as success depends on the function under test. For a flow assertion, success means returning its first argument.

  In the examples above, pass took only one argument (the value on the left side of the |>). That's because the expected output of assert_ok is trivial. In other cases, you must give the expected output to pass. That looks like this:

  test "ok_content" do
    a = content_runners_for(&ok_content/1)
    {:ok, "content"}    |> a.pass.("content")
    ...

• fail: takes an argument that is matched against an AssertionError.

  • A string, which must match the error message exactly.
  • A regular expression, like ~r/different lengths/, which can match part of the message.
  • A keyword list, which is checked with FlowAssertions.MapA.assert_fields/2. A typical use might be:

     [ {1, 2}, 3 ] |> a.fail.(left: {1, 2}, right: 3)

    Note that the left and right values are the true values from ExUnit.AssertionError, not string versions as from inspect. If the error message is also to be tested, it should be given in keyword form:

     a.fail.(left: "a", right: "bb", message: ~r/different lengths/)

    Warning: field names like :left, :right, and :message are not part of the public API of ExUnit.AssertionError, so those names could change in the future (though I doubt it). See the AssertionError source for some other fields.

• plus: Provides an arguably nicer way to check both the :message and other AssertionError fields. It's appended to fail like this:

   [datetime] |> a.fail.(Messages.wrong_struct_name(NaiveDateTime, Date))
              |> a.plus.(left: datetime)

• inspect_. This is a function to help with test-writing workflow. It mainly exists because it's hard for me to get the display of error information right without looking at it. That is, a check like this:

   [ [1, 2, 3],   [7, 1, 3] ]     |> a.fail.(~r/different elements/)
                                  |> a.plus.(...)

  is likely to come from looking a message like the one at the end of this bullet list, then tweaking the message and maybe the code:, left:, or right: output. I only "solidify" the final design in a test after everything looks right. Normally, producing such error output would mean writing throwaway code, but inspect_ avoids that. Once I pick test inputs (the values before the |>), I just write this:

   [ [1, 2, 3],   [7, 1, 3] ]     |> a.inspect_.(~r/a first message version/)
                                       ^^^^^^^^

  The trailing _ indicates that inspect_ is replacing a function that takes one argument. Use inspect to replace a function with zero arguments, like pass.

Beware the typo

The most common mistake I make with this library is this kind of typo:

  ["", "a" ]  |> a.fail(~s/Checker `has_slice("a")` failed/)

There should be a period after fail. The result (as of Elixir 1.11) is

  ** (ArgumentError) you attempted to apply a function on %{arity: 1,
  fail: #Function<5.65840318/2 in FlowAssertions.Define.Tabular.make_
  assertion_fail/1>, inspect: #Function<0.65840318/1 in FlowAssertion
  ...
  Assertions.Define.Tabular.start/2>}. Modules (the first argument of
  apply) must always be an atom

... which is perhaps not as clear as it should be. But now you're forewarned.