ExUnit.Assertions

This module contains a set of assertion functions that are imported by default into your test cases.

In general, a developer will want to use the general assert macro in tests. This macro introspects your code and provides good reporting whenever there is a failure. For example, assert some_fun() == 10 will fail (assuming some_fun() returns 13):

Comparison (using ==) failed in:
code:  some_fun() == 10
left:  13
right: 10

This module also provides other convenience functions like assert_in_delta and assert_raise to easily handle other common cases such as checking a floating-point number or handling exceptions.

Summary

Functions

assert(assertion)

Asserts its argument is a truthy value

assert(value, message)

Asserts value is true, displaying the given message otherwise

assert_in_delta(value1, value2, delta, message \\ nil)

Asserts that value1 and value2 differ by no more than delta

assert_raise(exception, function)

Asserts the exception is raised during function execution. Returns the rescued exception, fails otherwise

assert_raise(exception, message, function)

Asserts the exception is raised during function execution with the expected message, which can be a Regex or an exact String. Returns the rescued exception, fails otherwise

assert_receive(pattern, timeout \\ Application.fetch_env!(:ex_unit, :assert_receive_timeout), failure_message \\ nil)

Asserts that a message matching pattern was or is going to be received within the timeout period, specified in milliseconds

assert_received(pattern, failure_message \\ nil)

Asserts that a message matching pattern was received and is in the current process’ mailbox

catch_error(expression)

Asserts expression will cause an error. Returns the error or fails otherwise

catch_exit(expression)

Asserts expression will exit. Returns the exit status/message or fails otherwise

catch_throw(expression)

Asserts expression will throw a value. Returns the thrown value or fails otherwise

flunk(message \\ "Flunked!")

Fails with a message

refute(assertion)

A negative assertion, expects the expression to be false or nil

refute(value, message)

Asserts value is nil or false (that is, value is not truthy)

refute_in_delta(value1, value2, delta, message \\ nil)

Asserts value1 and value2 are not within delta

refute_receive(pattern, timeout \\ Application.fetch_env!(:ex_unit, :refute_receive_timeout), failure_message \\ nil)

Asserts that a message matching pattern was not received (and won’t be received) within the timeout period, specified in milliseconds

refute_received(pattern, failure_message \\ nil)

Asserts a message matching pattern was not received (i.e. it is not in the current process’ mailbox)

Functions

assert(assertion) (macro)

Asserts its argument is a truthy value.

assert introspects the underlying expression and provides good reporting whenever there is a failure. For example, if the expression uses the comparison operator, the message will show the values of the two sides. The assertion

assert 1 + 2 + 3 + 4 > 15

will fail with the message:

Assertion with > failed
code:  1 + 2 + 3 + 4 > 15
left:  10
right: 15

Similarly, if a match expression is given, it will report any failure in terms of that match. Given

assert [1] = [2]

you’ll see:

match (=) failed
code:  [1] = [2]
right: [2]

Keep in mind that assert does not change its semantics based on the expression. In other words, the expression is still required to return a truthy value. For example, the following will fail:

assert nil = some_function_that_returns_nil()

Even though the match works, assert still expects a truth value. In such cases, simply use Kernel.==/2 or Kernel.match?/2.

assert(value, message)

Asserts value is true, displaying the given message otherwise.

Examples

assert false, "it will never be true"

assert_in_delta(value1, value2, delta, message \\ nil)

Asserts that value1 and value2 differ by no more than delta.

This difference is inclusive, so the test will pass if the difference and the delta are equal.

Examples

assert_in_delta 1.1, 1.5, 0.2
assert_in_delta 10, 15, 2
assert_in_delta 10, 15, 5

assert_raise(exception, function)

Asserts the exception is raised during function execution. Returns the rescued exception, fails otherwise.

Examples

assert_raise ArithmeticError, fn ->
  1 + "test"
end

assert_raise(exception, message, function)

Asserts the exception is raised during function execution with the expected message, which can be a Regex or an exact String. Returns the rescued exception, fails otherwise.

Examples

assert_raise ArithmeticError, "bad argument in arithmetic expression", fn ->
  1 + "test"
end

assert_raise RuntimeError, ~r/^today's lucky number is 0.+!$/, fn ->
  raise "today's lucky number is 0.24703648603716122!"
end

assert_receive(pattern, timeout \\ Application.fetch_env!(:ex_unit, :assert_receive_timeout), failure_message \\ nil) (macro)

Asserts that a message matching pattern was or is going to be received within the timeout period, specified in milliseconds.

Unlike assert_received, it has a default timeout of 100 milliseconds.

The pattern argument must be a match pattern. Flunks with failure_message if a message matching pattern is not received.

Examples

assert_receive :hello

Asserts against a larger timeout:

assert_receive :hello, 20_000

You can also match against specific patterns:

assert_receive {:hello, _}

x = 5
assert_receive {:count, ^x}

assert_received(pattern, failure_message \\ nil) (macro)

Asserts that a message matching pattern was received and is in the current process’ mailbox.

The pattern argument must be a match pattern. Flunks with failure_message if a message matching pattern was not received.

Timeout is set to 0, so there is no waiting time.

Examples

send self(), :hello
assert_received :hello

send self(), :bye
assert_received :hello, "Oh No!"
** (ExUnit.AssertionError) Oh No!
Process mailbox:
  :bye

You can also match against specific patterns:

send self(), {:hello, "world"}
assert_received {:hello, _}

catch_error(expression) (macro)

Asserts expression will cause an error. Returns the error or fails otherwise.

Examples

assert catch_error(error 1) == 1

catch_exit(expression) (macro)

Asserts expression will exit. Returns the exit status/message or fails otherwise.

Examples

assert catch_exit(exit 1) == 1

catch_throw(expression) (macro)

Asserts expression will throw a value. Returns the thrown value or fails otherwise.

Examples

assert catch_throw(throw 1) == 1

flunk(message \\ "Flunked!")

flunk(String.t()) :: no_return()

Fails with a message.

Examples

flunk "This should raise an error"

refute(assertion) (macro)

A negative assertion, expects the expression to be false or nil.

Keep in mind that refute does not change the semantics of the given expression. In other words, the following will fail:

refute {:ok, _} = some_function_that_returns_error_tuple()

The code above will fail because the = operator always fails when the sides do not match and refute/2 does not change it.

The correct way to write the refutation above is to use Kernel.match?/2:

refute match? {:ok, _}, some_function_that_returns_error_tuple()

Examples

refute age < 0

refute(value, message)

Asserts value is nil or false (that is, value is not truthy).

Examples

refute true, "This will obviously fail"

refute_in_delta(value1, value2, delta, message \\ nil)

Asserts value1 and value2 are not within delta.

This difference is exclusive, so the test will fail if the difference and the delta are equal.

If you supply message, information about the values will automatically be appended to it.

Examples

refute_in_delta 1.1, 1.2, 0.2
refute_in_delta 10, 11, 2

refute_receive(pattern, timeout \\ Application.fetch_env!(:ex_unit, :refute_receive_timeout), failure_message \\ nil) (macro)

Asserts that a message matching pattern was not received (and won’t be received) within the timeout period, specified in milliseconds.

The pattern argument must be a match pattern. Flunks with failure_message if a message matching pattern is received.

Examples

refute_receive :bye

Refute received with an explicit timeout:

refute_receive :bye, 1000

refute_received(pattern, failure_message \\ nil) (macro)

Asserts a message matching pattern was not received (i.e. it is not in the current process’ mailbox).

The pattern argument must be a match pattern. Flunks with failure_message if a message matching pattern was received.

Timeout is set to 0, so there is no waiting time.

Examples

send self(), :hello
refute_received :bye

send self(), :hello
refute_received :hello, "Oh No!"
** (ExUnit.AssertionError) Oh No!
Process mailbox:
  :bye