View Source Efx (Efx v0.1.6)

Testing with side-effects is often hard. Various solutions exist to work around the difficulties, e.g. mocking. This library offers a very easy way to achieve testable code by mocking. Instead of mocking we talk about binding effects to another implementation. Efx offers a declarative way to mark effectful functions and bind them in tests.

Rationale

Efx is a small library that does one thing and one thing only very well: Make code that contains side effects testable.

Existing mock libraries often set up mocks in non declarative ways: configs need to be adapted & mock need to be initialized. In source code there are intrusive instructions to set up mockable code. Efx is very unintrusive in both, source code and test code. It offers a convenient and declarative syntax. Instead of mocking we talk about binding effects.

Efx follows the following principles:

  • Implementing and binding effects should be as simple and declarative as possible.
  • Modules contain groups of effects that can only be bound as a set.
  • We want to run as much tests async as possible. Thus, we traverse the supervision tree to find rebound effects in the ancest test processes, in an isolated manner.
  • Effects by default execute their default implemenation in tests, and thus, must be explicitly bound.
  • Effects can only be bound in tests, but not in production. In production always the default implementation is executed.
  • We want zero performance overhead in production.

Usage

Defining Effects

An effect is a function that executes side effects and thus is hard to test or even untestable. With the effects abstraction we can define mockable effect-functions comfortably.

Since effects are used on a module level utilizing the use-macro, all effect-functions defined inside build a group. We can later either bind all or none of this functions.

This module provides macros for implementing effects that are expanded into a mockable behaviour, e.g.

defmodule MyEffect do
  use Efx

  @spec read_numbers(String.t()) :: integer()
  defeffect read_numbers(id) do
    ... 
  end

  @spec write_numbers(String.t(), integer()) :: :ok
  defeffect read_numbers(id, numbers) do
    ...
  end
end

The above example generates a behaviour with the callbacks

      @callback read_numbers(String.t()) :: integer()
      @callback write_numbers(String.t(), integer()) :: :ok

By using the defeffect-macro, we define an effect-function as well as provide a default-implementation in its body. For more detail see the moduledoc in the Efx-module.

Binding Effects in Tests

To bind effects one simply has to use EfxCase-Module and call bind functions. Lets say we have the following effects implementation:

defmodule MyModule do
  use Common.Effects 

  @spec get() :: list()
  defeffect get() do
     ...
  end
end

The following shows code that binds the effect to a different implementation in tests:

defmodule SomeTest do
  use Common.EffectsCase

  test "test something" do
    bind(MyModule, :get, fn -> [1,2,3] end)
    ...
  end
end

Instead of returning the value of the default implementation, MyModule.get/0 returns [1,2,3].

For more details see the EfxCase-module.

Summary

Functions

Link to this function

already_exists?(module, name, arity)

View Source
@spec already_exists?(module(), atom(), arity()) :: boolean()
Link to this macro

defeffect(fun, do_block)

View Source (macro)