# `ExUnit.Assertions`
[🔗](https://github.com/elixir-lang/elixir/blob/v1.20.0-rc.4/lib/ex_unit/lib/ex_unit/assertions.ex#L82)

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.

# `assert`
*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]
    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`.

If you need more complex pattern matching using guards, you
need to use `match?/2`:

    assert match?([%{id: id} | _] when is_integer(id), records)

# `assert`

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, _}"

# `assert_in_delta`

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`

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

# `assert_raise`

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 / 0
    end

    assert_raise RuntimeError, ~r/^today's lucky number is 0\.\d+!$/, fn ->
      raise "today's lucky number is #{:rand.uniform()}!"
    end

# `assert_receive`
*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 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.
If a message matches, it is also removed from the process mailbox.

## 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`
*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.
If a message matches, it is also removed from the process mailbox.

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, _}

# `catch_error`
*macro* 

Asserts `expression` will cause an error.

Returns the error or fails otherwise.

## Examples

    assert catch_error(error(1)) == 1

# `catch_exit`
*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_receive/2`.

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

# `catch_throw`
*macro* 

Asserts `expression` will throw a value.

Returns the thrown value or fails otherwise.

## Examples

    assert catch_throw(throw(1)) == 1

# `flunk`

```elixir
@spec flunk(String.t()) :: no_return()
```

Fails with a message.

## Examples

    flunk("This should raise an error")

# `refute`
*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 `match?/2`:

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

## Examples

    refute age < 0

# `refute`

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

## Examples

    refute true, "This will obviously fail"

# `refute_in_delta`

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`
*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`
*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!

---

*Consult [api-reference.md](api-reference.md) for complete listing*