Custom matchers

To implement the custom assertion, you should use ESpec.Assertions.Interface and implement three functions match/2, success_message/4, and error_message/4. The match function receives subject and data and should return the term {true, result} or {false, result}. success_message and error_message receive subject, data, result, and positive value and must return the string with informative message. Let's look at the example of assertion which check if the subject in a divisor of some number:

defmodule BeDivisorOfAssertion do
  use ESpec.Assertions.Interface

  defp match(subject, number) do
    result = rem(number, subject)
    {result == 0, result}
  end

  defp success_message(subject, number, _result, positive) do
    to = if positive, do: "is", else: "is not"
    "`#{inspect subject}` #{to} the divisor of #{number}."
  end  

  defp error_message(subject, number, result, positive) do
    to = if positive, do: "to", else: "not to"
    "Expected `#{inspect subject}` #{to} be the divisor of `#{number}`, but the remainder is '#{result}'."
  end
end

To use the assertion you need to define helper function and make it available in you spec. The function should return a tuple {module, args}:

defmodule MyCustomAssertions do
  def be_divisor_of(number), do: {BeDivisorOfAssertion, number}	
end

So, now you can use the custom assertion inside your specs:

defmodule CustomAssertionSpec do
  use ESpec
  import CustomAssertions

  subject 3
  it do: should be_divisor_of(6)
  it do: should_not be_divisor_of(5)
end

The positive value in success_message and in error_message is true if you use to or should and equals false when you use to_not (not_to) or should_not.