Skip to content
Tutorials Center
My learning

Topics

Lesson 33 of 48 ยท Real-World Elixir

Testing with ExUnit

Write Elixir tests with ExUnit: assert and refute, describe and setup, doctests, async tests, mocks through behaviours, and an intro to property testing.

Elixir ships with its own test framework, ExUnit, and mix test runs it with no extra setup. Tests are ordinary Elixir modules, and because most of your code is made of small pure functions, they are quick to write and quick to run. Tests that do not share state can even run in parallel.

This lesson covers assert and refute, grouping with describe, preparing data with setup, doctests, async tests, replacing dependencies with behaviours (the basis of mocking in Elixir) and a first look at property-based testing. You should know Mix projects and protocols and behaviours.

Elixir cannot run on this site, so the ExUnit code is read-only. The JavaScript examples are small stand-ins that mimic how a test runner and a setup block work.

Your first test

A new Mix project has a test/ folder and a test/test_helper.exs file that contains one line, ExUnit.start(). Test files end in _test.exs.

ELIXIR
# lib/calculator.ex
defmodule Calculator do
  def add(a, b), do: a + b
  def divide(_a, 0), do: {:error, :division_by_zero}
  def divide(a, b), do: {:ok, a / b}
end
ELIXIR
# test/calculator_test.exs
defmodule CalculatorTest do
  use ExUnit.Case, async: true

  test "adds two numbers" do
    assert Calculator.add(2, 3) == 5
  end

  test "division by zero is an error tuple" do
    assert Calculator.divide(1, 0) == {:error, :division_by_zero}
  end
end

Run everything with mix test, one file with mix test test/calculator_test.exs, or a single test by line number with mix test test/calculator_test.exs:9.

assert is a macro. When an assertion fails, ExUnit shows the expression, the left and right sides and a diff, which is why you write assert a == b rather than a helper like assert_equal. Its companion refute expects a falsy value.

Assertions you will use daily

ELIXIR
assert 1 + 1 == 2
refute Enum.empty?([1])

# Pattern match assertion: binds variables you can use afterwards
assert {:ok, user} = Accounts.fetch_user(1)
assert user.name == "Ada"

# Expecting an exception
assert_raise ArgumentError, fn -> String.to_integer("abc") end

# Floats: compare with a tolerance
assert_in_delta 0.1 + 0.2, 0.3, 0.0001

# Messages sent to the test process
send(self(), {:done, 42})
assert_receive {:done, 42}
refute_received :never_sent

assert_receive waits up to 100 ms by default for a message to arrive in the test process mailbox (the timeout is configurable). It is how you test code that runs in other processes. assert_received checks the mailbox right now without waiting.

A test file at a glance

use ExUnit.Case Adds test, describe, setup and assertions.
test A named block that must not raise.
assert Fails with a clear diff when false.
refute Fails when the value is truthy.
1 / 2

describe, setup and context

describe groups tests and prefixes their names. setup runs before every test in its scope and returns data that is merged into the context, a map that each test can receive as an argument:

ELIXIR
defmodule ShoppingCartTest do
  use ExUnit.Case, async: true

  setup do
    cart = ShoppingCart.new() |> ShoppingCart.add("book", 20)
    {:ok, cart: cart}
  end

  describe "total/1" do
    test "sums item prices", %{cart: cart} do
      assert ShoppingCart.total(cart) == 20
    end

    test "is zero for a new cart" do
      assert ShoppingCart.total(ShoppingCart.new()) == 0
    end
  end

  describe "add/3" do
    setup %{cart: cart} do
      {:ok, bigger: ShoppingCart.add(cart, "pen", 5)}
    end

    test "increases the total", %{bigger: bigger} do
      assert ShoppingCart.total(bigger) == 25
    end
  end
end

A setup inside describe runs after the module-level one and sees its context. Use setup_all for expensive work that should run once per module (the data must not be mutated by tests). For cleanup, call on_exit/1; it runs even if the test fails:

ELIXIR
setup do
  path = Path.join(System.tmp_dir!(), "test.txt")
  File.write!(path, "hello")
  on_exit(fn -> File.rm(path) end)
  {:ok, path: path}
end

Tags are a way to select tests: @tag :slow before a test lets you run mix test --only slow or --exclude slow.

A tiny test runner in JavaScript

To see the idea, here is a stand-in that runs named tests, builds a context in setup and reports failures:

JS A mini test runner with setup

Press Run (or Ctrl + Enter) to see the console output here.

No output.

Doctests

Documentation examples can double as tests. Write an iex> example in a @doc, and one line in the test file runs it:

ELIXIR
defmodule Stats do
  @doc """
  Returns the average of a list of numbers.

      iex> Stats.average([2, 4, 6])
      4.0

      iex> Stats.average([])
      nil
  """
  def average([]), do: nil
  def average(list), do: Enum.sum(list) / length(list)
end
ELIXIR
defmodule StatsTest do
  use ExUnit.Case, async: true
  doctest Stats
end

If the documentation drifts from the behavior, the test fails. Doctests are best for short, pure examples; they are not a replacement for real tests with edge cases. More on documentation in Typespecs, Dialyzer and Documentation.

Async tests

use ExUnit.Case, async: true lets a test module run in parallel with other async modules. Tests inside one module always run one at a time. Async is safe when tests do not share global state. Do not use it when tests touch things that are global to the node: named processes, Application.put_env, ETS tables with fixed names, the same database rows (unless the sandbox handles it) or the file system in a shared path.

If a test module is not async, it runs alone after the async ones finish. Prefer async for pure code, and design code to take its collaborators as arguments so tests do not collide.

Mocks through behaviours

Elixir culture avoids replacing functions at runtime. The common approach is: define a behaviour for the outside dependency, write a real module and a fake one, and choose which one to use through configuration.

ELIXIR
defmodule Weather.Client do
  @callback temperature(city :: String.t()) :: {:ok, number()} | {:error, term()}
end

defmodule Weather.HTTPClient do
  @behaviour Weather.Client
  def temperature(city), do: # real HTTP request
end
ELIXIR
# test/support/fake_weather.ex
defmodule FakeWeather do
  @behaviour Weather.Client
  def temperature("Oslo"), do: {:ok, -3}
  def temperature(_), do: {:error, :unknown_city}
end
ELIXIR
defmodule Weather do
  def describe(city) do
    case client().temperature(city) do
      {:ok, t} when t < 0 -> "freezing"
      {:ok, _} -> "mild"
      {:error, _} -> "unknown"
    end
  end

  defp client, do: Application.get_env(:my_app, :weather_client, Weather.HTTPClient)
end

In config/test.exs you set config :my_app, weather_client: FakeWeather. The popular library Mox builds on this idea. It generates mock modules from behaviours and lets each test set expectations (expect/3), verified at the end of the test. It is a dependency you add in mix.exs, not part of Elixir itself.

Property-based testing, briefly

Example-based tests check the cases you thought of. Property-based tests state a rule that must hold for any input, and the library generates hundreds of inputs, shrinking a failure to a small counterexample. The StreamData library (also a dependency) provides this:

ELIXIR
defmodule ReverseTest do
  use ExUnit.Case, async: true
  use ExUnitProperties

  property "reversing twice gives the original list" do
    check all list <- list_of(integer()) do
      assert Enum.reverse(Enum.reverse(list)) == list
    end
  end
end

Good properties are round trips (encode then decode), invariants (a sorted list stays the same length) and comparisons with a slow, obviously correct version.

Habits for good tests

  • Name tests after behavior: "returns an error for an unknown city", not "test 1".
  • Test public functions; private (defp) functions are covered through them.
  • Match on the shape you care about, not on the whole result, when parts are irrelevant.
  • Keep tests independent. A test must pass alone and in any order.
  • Use capture_io/1 (from ExUnit.CaptureIO) to assert on printed output.

Check your understanding

Quick check ยท 5 questions

of 5 answered You scored / 5 ยท perfect!

  1. 1. Which file name does mix test pick up by default?

    Mix looks in test/ for files ending in _test.exs.
  2. 2. What does a setup block return so tests can use the data?

    setup returns {:ok, keyword_or_map}. The data joins the context, which a test can receive with %{key: value}.
  3. 3. When is it unsafe to mark a test module async: true?

    Async modules run at the same time as other modules, so shared global state causes flaky tests.
  4. 4. What is the idiomatic way to replace an external service in tests?

    A behaviour describes the contract, so a fake or Mox mock can stand in for the real client.
  5. 5. What does a doctest verify?

    doctest Module runs each iex> example and compares the output with the line that follows.

Summary

  • ExUnit tests live in test/*_test.exs; mix test runs them, with file and line filters.
  • assert shows diffs; use refute, assert_raise, assert_in_delta and assert_receive for other checks.
  • describe groups tests; setup builds a context map; on_exit cleans up.
  • Doctests turn iex> documentation examples into tests.
  • async: true runs modules in parallel; avoid it with shared global state.
  • Mock through behaviours and configuration (Mox is the common helper); StreamData adds property-based tests.

Next: reading and writing data in Files, JSON and Serialization.