ExUnit.Assertions View Source

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:  assert 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.

Link to this section Summary

Functions

Asserts its argument is a truthy value

Asserts value is true, displaying the given message otherwise

Asserts that value1 and value2 differ by no more than delta

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

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

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

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

Asserts expression will cause an error

Asserts expression will exit

Asserts expression will throw a value

Fails with a message

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

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

Asserts value1 and value2 are not within delta

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

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

Link to this section Functions

Link to this macro

assert(assertion) View Source (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:  assert 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:  assert [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.

Asserts value is true, displaying the given message otherwise.

Examples

assert false, "it will never be true"
Link to this function

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

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
Link to this function

assert_raise(exception, function) View Source

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

Examples

assert_raise ArithmeticError, fn ->
  1 + "test"
end
Link to this function

assert_raise(exception, message, function) View Source

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.656568267137223!"
end
Link to this macro

assert_receive(pattern, timeout \\ Application.fetch_env!(:ex_unit, :assert_receive_timeout), failure_message \\ nil) View Source (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}
Link to this macro

assert_received(pattern, failure_message \\ nil) View Source (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, _}
Link to this macro

catch_error(expression) View Source (macro)

Asserts expression will cause an error.

Returns the error or fails otherwise.

Examples

assert catch_error(error 1) == 1
Link to this macro

catch_exit(expression) View Source (macro)

Asserts expression will exit.

Returns the exit status/message of the current process or fails otherwise.

Examples

assert catch_exit(exit 1) == 1

To assert exits from linked processes started from the test, trap exits with Process.flag/2 and assert the exit message with assert_received/2.

Process.flag(:trap_exit, true)
pid = spawn_link(fn -> Process.exit(self(), :normal) end)
assert_receive {:EXIT, ^pid, :normal}
Link to this macro

catch_throw(expression) View Source (macro)

Asserts expression will throw a value.

Returns the thrown value or fails otherwise.

Examples

assert catch_throw(throw 1) == 1
Link to this function

flunk(message \\ "Flunked!") View Source
flunk(String.t()) :: no_return()

Fails with a message.

Examples

flunk "This should raise an error"
Link to this macro

refute(assertion) View Source (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

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

Examples

refute true, "This will obviously fail"
Link to this function

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

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
Link to this macro

refute_receive(pattern, timeout \\ Application.fetch_env!(:ex_unit, :refute_receive_timeout), failure_message \\ nil) View Source (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
Link to this macro

refute_received(pattern, failure_message \\ nil) View Source (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