View Source ExUnit.Assertions (ExUnit v1.18.0-dev)
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.
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 > 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]
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
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 configurable timeout.
The default timeout duration is determined by the assert_receive_timeout
option,
which can be set using ExUnit.configure/1
. This option defaults to 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}
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)) == 1
To 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
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
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!