Assertions v0.8.0 Assertions View Source

Helpful assertions with great error messages to help you write better tests.

Link to this section Summary

Functions

Asserts that all maps, structs or keyword lists in list have the same value for key

Asserts that the file at path is changed to match comparison after executing expr

Asserts that the file at path is created after executing expr

Asserts that the file at path is deleted after executing expr

Asserts that two lists contain the same elements without asserting they are in the same order

Asserts that two lists contain the same elements without asserting they are in the same order

Asserts that two lists contain the same elements without asserting they are in the same order

Asserts that a map with the same values for the given keys is in the list

Asserts that the values in left and right are the same for the keys

Tests that a message matching the given pattern, and only that message, is received before the given timeout, specified in milliseconds

Asserts that a struct with certain values is present in the list

Asserts that the values in struct left and struct right are the same for the given keys

Link to this section Types

Link to this type comparison() View Source
comparison() :: (any(), any() -> boolean())

Link to this section Functions

Link to this macro assert_all_have_value(list, key, value) View Source (macro)
assert_all_have_value([map() | struct() | Keyword.t()], any(), any()) ::
  true | no_return()

Asserts that all maps, structs or keyword lists in list have the same value for key.

iex> assert_all_have_value([%{key: :value}, %{key: :value, other: :key}], :key, :value)
true

iex> assert_all_have_value([[key: :value], [key: :value, other: :key]], :key, :value)
true

iex> assert_all_have_value([[key: :value], %{key: :value, other: :key}], :key, :value)
true
Link to this macro assert_changes_file(path, comparison, full) View Source (macro)
assert_changes_file(Path.t(), String.t() | Regex.t(), Macro.expr()) ::
  true | no_return()

Asserts that the file at path is changed to match comparison after executing expr.

If the file matches comparison before executing expr, this assertion will fail. The file does not have to exist before executing expr in order for this assertion to pass.

iex> path = Path.expand("../tmp/file.txt", __DIR__)
iex> result = assert_changes_file(path, "hi") do
iex>   File.mkdir_p!(Path.dirname(path))
iex>   File.write(path, "hi")
iex> end
iex> File.rm_rf!(Path.dirname(path))
iex> result
true
Link to this macro assert_creates_file(path, full) View Source (macro)
assert_creates_file(Path.t(), Macro.expr()) :: true | no_return()

Asserts that the file at path is created after executing expr.

iex> path = Path.expand("../tmp/file.txt", __DIR__)
iex> File.mkdir_p!(Path.dirname(path))
iex> result = assert_creates_file path do
iex>   File.write(path, "hi")
iex> end
iex> File.rm_rf!(Path.dirname(path))
iex> result
true
Link to this macro assert_deletes_file(path, full) View Source (macro)
assert_deletes_file(Path.t(), Macro.expr()) :: true | no_return()

Asserts that the file at path is deleted after executing expr.

iex> path = Path.expand("../tmp/file.txt", __DIR__)
iex> File.mkdir_p!(Path.dirname(path))
iex> File.write(path, "hi")
iex> assert_deletes_file path do
iex>   File.rm_rf!(Path.dirname(path))
iex> end
true
Link to this macro assert_lists_equal(left, right) View Source (macro)
assert_lists_equal(list(), list()) :: true | no_return()

Asserts that two lists contain the same elements without asserting they are in the same order.

iex> assert_lists_equal([1, 2, 3], [1, 3, 2])
true
Link to this macro assert_lists_equal(left, right, message_or_comparison) View Source (macro)
assert_lists_equal(list(), list(), comparison() | String.t()) ::
  true | no_return()

Asserts that two lists contain the same elements without asserting they are in the same order.

The third argument can either be a custom failure message, or a function used to compare elements in the lists.

iex> assert_lists_equal([1, 2, 3], [1, 3, 2], "NOT A MATCH")
true

iex> assert_lists_equal(["dog"], ["cat"], &(String.length(&1) == String.length(&2)))
true
Link to this macro assert_lists_equal(left, right, comparison, message) View Source (macro)
assert_lists_equal(list(), list(), comparison(), String.t()) ::
  true | no_return()

Asserts that two lists contain the same elements without asserting they are in the same order.

If the comparison fails, the given message is used as the failure message.

iex> assert_lists_equal(
iex>   ["dog"],
iex>   ["cat"],
iex>   &(String.length(&1) == String.length(&2)),
iex>   "FAILED WITH CUSTOM MESSAGE"
iex> )
true
Link to this macro assert_map_in_list(map, list, keys) View Source (macro)
assert_map_in_list(map(), [map()], [any()]) :: true | no_return()

Asserts that a map with the same values for the given keys is in the list.

iex> list = [%{first: :first, second: :second, third: :third}]
iex> assert_map_in_list(%{first: :first, second: :second}, list, [:first, :second])
true
Link to this macro assert_maps_equal(left, right, keys) View Source (macro)
assert_maps_equal(map(), map(), [any()]) :: true | no_return()

Asserts that the values in left and right are the same for the keys

iex> left = %{first: :first, second: :second, third: :third}
iex> right = %{first: :first, second: :second, third: :fourth}
iex> assert_maps_equal(left, right, [:first, :second])
true
Link to this macro assert_receive_only(pattern, timeout \\ 100) View Source (macro)
assert_receive_only(Macro.expr(), non_neg_integer()) :: any() | no_return()

Tests that a message matching the given pattern, and only that message, is received before the given timeout, specified in milliseconds.

The optional second argument is a timeout for the receive to wait for the expected message, and defaults to 100ms.

If you want to check that no message was received before the expected message, and that no message is received for a given time after calling receive_only?/2, you can combine received_only?/2 with ExUnit.Assertions.refute_receive/3.

assert_receive_only(:hello)
refute_receive _, 100

Examples

iex> send(self(), :hello)
iex> assert_receive_only(:hello)
true

iex> send(self(), [:hello])
iex> assert_receive_only([_])
true

iex> a = :hello
iex> send(self(), :hello)
iex> assert_receive_only(^a)
true

iex> send(self(), :hello)
iex> assert_receive_only(a when is_atom(a))
iex> a
:hello

iex> send(self(), %{key: :value})
iex> assert_receive_only(%{key: value} when is_atom(value))
iex> value
:value

If a message is received after the function has matched a message to the given pattern, but the second message is received before the timeout, that second message is ignored and the function returns true.

This assertion only tests that the message that matches the given pattern was the first message in the process inbox, and that nothing was sent between the sending the message that matches the pattern and when receive_only?/2 was called.

iex> Process.send_after(self(), :hello, 20)
iex> Process.send_after(self(), :hello_again, 50)
iex> assert_receive_only(:hello, 100)
true
Link to this macro assert_struct_in_list(struct_or_map, keys_or_type, list) View Source (macro)
assert_struct_in_list(struct(), [any()], [struct()]) :: true | no_return()
assert_struct_in_list(map(), module(), [struct()]) :: true | no_return()

Asserts that a struct with certain values is present in the list.

There are two ways to make this comparison.

First is to pass a struct, a list of keys to use to compare that struct to the structs in the list, and a list of structs.

iex> list = [DateTime.utc_now(), Date.utc_today()]
iex> assert_struct_in_list(DateTime.utc_now(), [:year, :month, :day, :second], list)
true

The second way to use this assertion is to pass a map of keys and values that you expect to be in the struct, a module representing the type of struct you are expecting, and a list of structs.

iex> list = [DateTime.utc_now(), Date.utc_today()]
iex> year = DateTime.utc_now().year
iex> assert_struct_in_list(%{year: year}, DateTime, list)
true
Link to this macro assert_structs_equal(left, right, keys) View Source (macro)
assert_structs_equal(struct(), struct(), [any()]) :: true | no_return()

Asserts that the values in struct left and struct right are the same for the given keys

iex> assert_structs_equal(DateTime.utc_now(), DateTime.utc_now(), [:year, :minute])
true