AssertEventually v1.0.0 AssertEventually View Source

AssertEventually allows to use standard ExUnit assertions along with expressions that may fail several times until they eventually succeed.

In order to use macros from this module, you first need to use AssertEventually in you test case. On-use, you can provide two options:

timeout - default time after which your assertions will stop ignoring errors (can be set individually for each assert)
interval - time before retring your expression after previous one fails

All provided times are milliseconds.

Examples:

 defmodule MyApp.SomeTest do
   use ExUnit.Case, async: true

   # Fail after 50ms of retrying with time between attempts 5ms
   use AssertEventually, timeout: 50, interval: 5

   test "my test with" do
     assert_eventually {:ok, %{some: value}} = {:ok, %{some: :real_value, other: :value}}
   end
 end

Link to this section Summary

Functions

assert_eventually(expr, timeout \\ nil)

Equivalent to: eventually(assert(expr), timeout)

eventually(assert_expr, timeout \\ nil)

This macro should be used with other ExUnit macros to allow the original assert_expr to fail for a given period of time (timeout).

Link to this section Functions

assert_eventually(expr, timeout \\ nil)

(macro)

Equivalent to: eventually(assert(expr), timeout)

eventually(assert_expr, timeout \\ nil)

(macro)

This macro should be used with other ExUnit macros to allow the original assert_expr to fail for a given period of time (timeout).

First argument should always be a ExUnit assert-like macro call with all its arguments, while second argument is optional timeout (default 1000ms). For more details on default timeout value and other available options, please refer to module docs.

Usage use-case / example:

Let's say, you have complex system that can be started with start_supervised(ComplexSystem). ComplexSystem has some things to take care of before it's fully operational and can actually return something meaningful with ComplexSystem.get_value(). eventually/2 allows to verify the return value when you don't really care how much time exactly it took the ComplexSystem to start as long this time is "resonable". To implement such test, you can do the following:

test "get meaningful value" do
  {:ok, _pid} = start_supervised(ComplexSystem)

  eventually assert {:ok, value} = ComplexSystem.get_value()
  assert value == 42
end

The code above will try running the given expression (match in this case) for some time (1000ms here - default). If it's successful within the given time, the behaviour will be the same as normal assert macro. If the expression will fail for at least the time given as timeout, the behaviour will also be the same as normal assert macro.

This macro can be used with any ExUnit assert-like macro:

test "get meaningful value" do
  {:ok, _pid} = start_supervised(ComplexSystem)

  eventually assert_in_delta 42, elem(ComplexSystem.get_value(), 1), 0
end