Skip to content
Tutorials Center
My learning

Topics

Lesson 31 of 36 ยท Tools and Testing

Testing Erlang: EUnit, Common Test and PropEr

Write Erlang tests with EUnit assertions and fixtures, run integration suites with Common Test, and find edge cases with property-based testing using PropEr.

Erlang ships with two test frameworks and has a third popular community one. EUnit is for fast unit tests next to the code. Common Test (CT) is for larger integration and system tests with set-up and tear-down, logs and distributed scenarios. PropEr (and its cousin QuickCheck) generate hundreds of random inputs to check properties that must always hold.

EUnit basics

Include the EUnit header in a module and write functions whose names end in _test. EUnit finds and exports them automatically.

ERLANG
-module(calc).
-export([add/2, divide/2]).

-ifdef(TEST).
-include_lib("eunit/include/eunit.hrl").
-endif.

add(A, B) -> A + B.

divide(_, 0) -> {error, divide_by_zero};
divide(A, B) -> {ok, A / B}.

-ifdef(TEST).
add_test() ->
    ?assertEqual(5, add(2, 3)),
    ?assertEqual(0, add(-1, 1)).

divide_test() ->
    ?assertEqual({ok, 2.5}, divide(5, 2)),
    ?assertMatch({error, _}, divide(1, 0)).
-endif.

Wrapping tests in -ifdef(TEST) keeps them out of production builds (rebar3 defines TEST for the test profile). Run them:

TEXT
$ rebar3 eunit
===> Performing EUnit tests...
..
Finished in 0.02 seconds
2 tests, 0 failures

Key assertion macros:

Macro Checks
?assert(Bool) the expression is true
?assertEqual(Expected, Expr) equality with =:= (note the order: expected first)
?assertNotEqual(A, B) inequality
?assertMatch(Pattern, Expr) the value matches a pattern, ignoring unbound parts
?assertError(Pattern, Expr) evaluating raises an error: matching Pattern
?assertThrow(Pattern, Expr) evaluating throws a matching value
?assertExit(Pattern, Expr) evaluating exits with a matching reason

Test generators and fixtures

A function ending in _test_() (with the underscore) is a generator: it returns test descriptions, which allows titles and tables of cases.

ERLANG
add_cases_test_() ->
    [{"zero is neutral", ?_assertEqual(7, add(7, 0))},
     {"negatives",       ?_assertEqual(-5, add(-2, -3))},
     {"floats",          ?_assertEqual(3.5, add(1.5, 2))}].

?_assert... forms are lazy: they build a test object instead of running now.

A fixture sets up and cleans up around tests, for example starting a gen_server:

ERLANG
kv_test_() ->
    {setup,
     fun() -> {ok, Pid} = kv:start_link(), Pid end,      % set up once
     fun(_Pid) -> kv:stop() end,                         % tear down
     fun(_Pid) ->
         [?_assertEqual(ok, kv:put(a, 1)),
          ?_assertEqual({ok, 1}, kv:get(a)),
          ?_assertEqual(error, kv:get(missing))]
     end}.

Use {foreach, Setup, Teardown, [Instantiators]} to repeat set-up for each test, and {timeout, Seconds, Test} for slow tests (the default limit is 5 seconds). Tests that need a process can also check messages with receive ... after.

Testing processes and messages

For a server, test through its public API, not its internals. To check that a process sends a message, make the test process the receiver:

ERLANG
echo_test() ->
    Pid = spawn(fun() -> receive {From, X} -> From ! {echo, X} end end),
    Pid ! {self(), hi},
    ?assertEqual({echo, hi}, receive M -> M after 1000 -> timeout end).

Always use a timeout; otherwise a missing message hangs the test run. For code that calls other modules, the meck library can replace a module with a mock in the test profile.

Common Test

CT suites live in test/*_SUITE.erl and are run with rebar3 ct. They suit scenarios with many steps, shared state and logs.

ERLANG
-module(kv_SUITE).
-include_lib("common_test/include/ct.hrl").
-export([all/0, init_per_suite/1, end_per_suite/1, store_and_fetch/1, missing_key/1]).

all() -> [store_and_fetch, missing_key].

init_per_suite(Config) ->
    {ok, _} = kv:start_link(),
    Config.

end_per_suite(_Config) ->
    kv:stop(),
    ok.

store_and_fetch(_Config) ->
    ok = kv:put(city, "Oslo"),
    {ok, "Oslo"} = kv:get(city).

missing_key(_Config) ->
    error = kv:get(nothing).

A test case passes if it returns normally and fails if it crashes. The matching = is the assertion: a failed match crashes with a clear report. CT produces HTML logs in _build/test/logs/, supports groups and test data directories, and can start multiple nodes to test distribution.

Property-based testing with PropEr

Instead of listing examples, state a rule and let the tool try random inputs; on failure it shrinks the input to a minimal counterexample.

ERLANG
-include_lib("proper/include/proper.hrl").

prop_add_commutes() ->
    ?FORALL({A, B}, {integer(), integer()}, calc:add(A, B) =:= calc:add(B, A)).

prop_reverse_twice() ->
    ?FORALL(L, list(integer()), lists:reverse(lists:reverse(L)) =:= L).

Run with the rebar3_proper plugin: rebar3 proper. Good properties describe invariants: "sorting is idempotent", "decode(encode(X)) =:= X", "the store never loses an inserted key". PropEr can even generate sequences of commands to test stateful servers against a model.

Which tool when

EUnit Fast unit tests next to the code
Common Test Integration, groups, logs, nodes
PropEr Random inputs, shrinking
meck Mock modules in tests

Most projects use all three at different levels.

1 / 2

Run it: a tiny test runner stand-in

This JavaScript stand-in is not EUnit. It mirrors ?assertEqual and generators so you can see the shape: tests are functions, an assertion raises, and the runner counts.

JS Stand-in: assertEqual and a runner

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

No output.

A property stand-in

The same idea for a property: generate random lists, test an invariant, and report a counterexample if one is found. A seeded generator keeps the run reproducible.

JS Stand-in: a property with random inputs

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

No output.

The second property fails, because JavaScript's default sort compares numbers as text, a bug that a handful of hand-picked examples might miss.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Which function name makes EUnit run a function automatically?

    Functions whose names end in _test (arity 0) are found and run. Ending in test makes a generator.
  2. 2. What is a test generator in EUnit?

    Generators return lists or tuples of tests, allowing titles, fixtures and tables of cases.
  3. 3. When does a Common Test case fail?

    A case passes if it returns normally; a bad match or exception marks it as failed.
  4. 4. What does shrinking mean in property-based testing?

    After finding a failure, the tool simplifies the input to make the cause easier to see.

Summary

  • EUnit: _test() functions and ?assert* macros; generators (_test_()) and fixtures (setup, foreach) add structure.
  • Common Test suites in test/*_SUITE.erl run integration scenarios with logs and set-up callbacks.
  • PropEr tests invariants against random input and shrinks failures.
  • Test processes through their API, with timeouts on every receive.
  • rebar3 eunit, rebar3 ct and rebar3 proper run them.

Next: Debugging and the Observer