ExUnit.Assertions

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 provide 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
lhs:  13
rhs:  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(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

flunk(message \\ "Flunked!")

Fails with a message

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

Macros

assert(assertion)

Asserts its argument is a truthy value

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

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

refute(assertion)

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

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

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(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.

Examples

assert_in_delta 1.1, 1.5, 0.2
assert_in_delta 10, 15, 4

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.32230143131061423!"
end

flunk(message \\ "Flunked!")

flunk(String.t) :: no_return

Fails with a message.

Examples

flunk "This should raise an error"

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.

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

Macros

assert(assertion)

Asserts its argument is a truthy value.

assert instrospects the underlying expression and provide 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
lhs:  10
rhs:  15

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

assert [one] = [two]

you’ll see:

match (=) failed
code: [one] = [two]
rhs:  [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_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.

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)

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)

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

Examples

assert catch_error(error 1) == 1

catch_exit(expression)

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

Examples

assert catch_exit(exit 1) == 1

catch_throw(expression)

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

Examples

assert catch_throw(throw 1) == 1

refute(assertion)

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_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.

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)

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

© 2012–2017 Plataformatec
Licensed under the Apache License, Version 2.0.
https://hexdocs.pm/ex_unit/1.3.4/ExUnit.Assertions.html

在线笔记
App下载
App下载

扫描二维码

下载编程狮App

公众号
微信公众号

编程狮公众号

意见反馈
返回顶部