View Source ExUnit.Assertions (ExUnit v1.15.7)
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: 10This 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
Asserts its argument is a truthy value.
Asserts value is truthy, 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 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).
Functions
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 > 15will fail with the message:
Assertion with > failed
code: assert 1 + 2 + 3 + 4 > 15
left: 10
right: 15Similarly, 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]
left: [1]
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 ==/2 or match?/2.
Asserts value is truthy, displaying the given message otherwise.
Examples
assert false, "it will never be true"
assert x == :foo, "expected x to be foo"
assert match?({:ok, _}, x), "expected x to match {:ok, _}"
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
Asserts the exception is raised during function execution.
Returns the rescued exception, fails otherwise.
Examples
assert_raise ArithmeticError, fn ->
1 + "test"
end
assert_raise RuntimeError, fn ->
raise "assertion will pass due to this raise"
end
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\.\d+!$/, fn ->
raise "today's lucky number is #{:rand.uniform()}!"
end
assert_receive(pattern, timeout \\ nil, 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 :helloAsserts against a larger timeout:
assert_receive :hello, 20_000You can also match against specific patterns:
assert_receive {:hello, _}
x = 5
assert_receive {:count, ^x}
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!You can also match against specific patterns:
send(self(), {:hello, "world"})
assert_received {:hello, _}
Asserts expression will cause an error.
Returns the error or fails otherwise.
Examples
assert catch_error(error(1)) == 1
Asserts expression will exit.
Returns the exit status/message of the current process or fails otherwise.
Examples
assert catch_exit(exit(1)) == 1To assert exits from linked processes started from the test, trap exits
with Process.flag/2 and assert the exit message with assert_receive/2.
Process.flag(:trap_exit, true)
pid = spawn_link(fn -> Process.exit(self(), :normal) end)
assert_receive {:EXIT, ^pid, :normal}
Asserts expression will throw a value.
Returns the thrown value or fails otherwise.
Examples
assert catch_throw(throw(1)) == 1
Fails with a message.
Examples
flunk("This should raise an error")
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 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"
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 \\ nil, 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 :byeRefute received with an explicit timeout:
refute_receive :bye, 1000
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!