ExUnit.Assertions — ExUnit v1.16.3

Search documentation of ExUnit

# View Source ExUnit.Assertions (ExUnit v1.16.3)

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

assert(assertion)

Asserts its argument is a truthy value.

assert(value, message)

Asserts `value` is truthy, 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.

assert_receive(pattern, timeout \\ nil, failure_message \\ nil)

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

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.

catch_exit(expression)

Asserts `expression` will exit.

catch_throw(expression)

Asserts `expression` will throw a value.

flunk(message \\ "Flunked!")

Fails with a message.

refute(assertion)

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

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

refute_receive(pattern, timeout \\ nil, failure_message \\ nil)

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

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

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]
    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`.

Link to this function

# assert(value, message)

View Source

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

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

    assert_raise RuntimeError, fn ->
      raise "assertion will pass due to this raise"
    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\.\d+!$/, fn ->
      raise "today's lucky number is #{:rand.uniform()}!"
    end

Link to this macro

# 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 :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!

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_receive/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

    @spec 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 `match?/2`:

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

## Examples

    refute age < 0

Link to this function

# refute(value, message)

View Source

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 \\ 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 :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!