EUnit provides a detailed representation of tests, as well as a layer of macros making tests easier to write. It also provides a mechanism for gathering all the tests in a module, executing them all, and providing a report on the results. For a module to use EUnit it needs to include the eunit library:

-include_lib("eunit/include/eunit.hrl").

In EUnit, a single test is identified by a function named name_test; a test-generating function will be named name_test_ (i.e., with an _ at the end). We define test-generating functions in the section The EUnit Infrastructure.

With the EUnit header file included, compilation of the module (mod, say) will result in a function test/0 being exported, and all the tests within the module are run by calling mod:test().

It is possible to separate the test functions from the module (mod, say) into the module mod_tests.erl, which should also include the eunit.hrl header file. The tests are invoked in exactly the same way, using mod:test().

It may be that you want to use EUnit on your code—for example, to use the ?assert macro—but you don’t want to generate tests. In this case, you need to insert the following code before the line that includes the eunit.hrl library:

-define(NOTEST, true)

If this macro appears in a header file included by all modules in an application, it gives a single point controlling whether testing is enabled. Now we will illustrate how tests are written, using an example you’ve seen before.

In the section Serialization in Chapter 9, we looked at how a binary tree could be serialized as a list, and then reconstructed from the list. We presented an optimized version of this, but left the original version as an exercise. In this unoptimized version, the first element of the representation gives its size recursively through the tree?

treeToList({leaf,N}) ->
  [2,N];

treeToList({node,T1,T2}) ->
  TTL1 = treeToList(T1),
  [Size1|_] = TTL1,
  TTL2 = treeToList(T2),
  [Size2|_] = TTL2,
  [Size1+Size2+1|TTL1++TTL2].

listToTree([2,N]) ->
  {leaf,N};

listToTree([_|Code]) ->
  case Code of
    [M|_] ->
      {Code1,Code2} = lists:split(M,Code),
      {node,
        listToTree(Code1),
        listToTree(Code2)
       }
  end.

The function treeToList/1 converts the tree to a list, and listToTree/1 should convert that representation back to the original tree. We can now test the functions with some example trees:

tree0() ->
  {leaf, ant}.

tree1() ->
  {node,
    {node,
     {leaf,cat},
     {node,
      {leaf,dog},
      {leaf,emu}
     }
    },
    {leaf,fish}
   }.

We require that the two functions applied one after the other return the original value:

leaf_test() ->
  ?assertEqual(tree0() , listToTree(treeToList(tree0()))).
node_test() ->
  ?assertEqual(tree1() , listToTree(treeToList(tree1()))).

where we use the eunit macro assertEqual to test for equality between the value of two Erlang terms.

We can also test for particular values of the treeToList function:

leaf_value_test() ->
  ?assertEqual([2,ant] , treeToList(tree0())).
node_value_test() ->
  ?assertEqual([11,8,2,cat,5,2,dog,2,emu,2,fish] , treeToList(tree1())).

In testing listToTree, we do something different. This function is partial, and we can check that it is undefined outside the range of treeToList:

leaf_negative_test() ->
  ?assertError(badarg, listToTree([1,ant])).
node_negative_test() ->
  ?assertError(badarg, listToTree([8,6,2,cat,2,dog,emu,fish])).

These tests use the assertError macro, which captures a raised exception and checks that it is of the form specified by the first argument (here, a badarg).

With these tests included in the file, running the test/0 function in the shell gives the brief report that all tests are successful:

2> serial:test().
  All 6 tests successful.
ok

There is nothing more to say when tests are successful. Alas, not all tests are successful. What does EUnit report when tests fail? In true test-driven development style, as an illustration, we can regression-test the optimized version of serialization with the same test set and see what happens:

11> serial2:test().
serial2:leaf_negative_test...*failed*
::error:{assertException_failed,[{module,serial2},
                               {line,66},
                               {expression,"listToTree ( [ 1 , ant ] )"},
                               {expected,"{ error , badarg , [...] }"},
                               {unexpected_success,{leaf,ant}}]}
  in function serial2:'-leaf_negative_test/0-fun-0-'/0

serial2:node_value_test...*failed*
::error:{assertEqual_failed,[{module,serial2},
                           {line,72},
                           {expression,"treeToList ( tree1 ( ) )"},
                           {expected,[11,8,2,cat,5,2|...]},
                           {value,[8,6,2,cat,2|...]}]}
  in function serial2:'-node_value_test/0-fun-0-'/1

serial2:node_negative_test...*failed*
 ... details similar ...

=======================================================
  Failed: 3.  Aborted: 0.  Skipped: 0.  Succeeded: 3.
error

This report shows that three of the six tests have failed, and gives detailed feedback on the cause of failure. In the case of leaf_negative_test, it is that the particular function application succeeds unexpectedly, instead of raising a badarg exception. In the second case, the actual result was different from the actual value, both of which are printed in the report.

The failed tests either cover values for which the original functions failed, or are sensitive to changes in the new implementation, where the details of the list representation have changed. The first two tests that check that applying the functions one after the other returns the original argument, however, confirm that the crucial property still holds.

-module(serial_tests).
-include_lib("eunit/include/eunit.hrl").
-import(serial,
       [treeToList/1, listToTree/1
        tree0/0, tree1/0,]).

leaf_test() ->
  ?assertEqual(tree0() ,
               listToTree(treeToList(tree0()))).
... etc ...

The basic building block of EUnit is a single test, given by a ..._test() function. On the right side of the earlier code examples, we used assertEqual and assertError to check values and exceptions. Other assert macros include the following:

In the example, we used assertEqual(E, F) instead of assert(E =:= F) because assertEqual generates more informative messages when the test fails.

Beyond a single test, you can define test-generating functions that combine a number of tests into a single function. A test generator returns a representation of a set of tests to be executed by EUnit.

The simplest way to represent a test is as a fun expression that takes no arguments:

leaf_value_test_() ->
     fun () -> ?assertEqual([2,ant] , treeToList(tree0())) end.

In the preceding code, the differences from the definition of leaf_value_test are highlighted. The macro library allows you to write this more succinctly:

leaf_value_test_() ->
     ?_assertEqual([2,ant] , treeToList(tree0())).

In this code, the _assertEqual macro plays the same role as assertEqual, but for test representations rather than tests.

A test-generating function will, in general, return a set of tests. For instance, the following code encapsulates two tests into a single function:

tree_test_() ->
  [?_assertEqual(tree0() , listToTree(treeToList(tree0()))),
   ?_assertEqual(tree1() , listToTree(treeToList(tree1())))].

When EUnit runs this test, all the tests in the list are performed.

EUnit represents tests and test sets in a variety of different ways. Here is a list of the most useful; a full description is in the EUnit documentation. A test representation TestRep is run by calling eunit:test(TestRep):

It is characteristic of state-based systems that you can test particular properties only after you have set up the right configuration; once you’ve done this, the test can take place, but after that, you need to clean up the system to prepare for any further tests.

The first test we’ll write will test a lookup on an empty database after the tables are created with create_tables("UsrTabFile"):

?_assertMatch({error,instance}, lookup_id(1))

After the test is run, we clean up by removing the file UsrTabFile. This is implemented by writing a fixture: a test description that allows setup and cleanup. The simplest fixtures have the following form:

{setup, Setup, Tests}
{setup, Setup, Cleanup, Tests}

where, for some type T:

Setup   :: (() -> T)
Cleanup :: ((T) -> any())

the Setup function is executed before the Tests, returning a value X of type T. After the tests, Cleanup(X) is performed; this allows information from the setup—for example, about pids or tables—to be communicated to the cleanup phase.

For our example, we can write the following:

setup1_test_() ->
   {spawn,
    {setup,
     fun ()  -> create_tables("UsrTabFile") end,           % setup
     fun (_) -> ?cmd("rm UsrTabFile") end,                 % cleanup
     ?_assertMatch({error,instance}, lookup_id(1))
    }
   }.

Note in the cleanup that we can call an external Unix command to remove the file using the ?cmd macro, and that the test is executed by a call to eunit:test/1. To test that the database is functioning correctly, we need a rather more elaborate setup; on termination of the spawned process, the ETS tables constructed by the program will be destroyed:

setup2_test_() ->
  {spawn,
    {setup,
      fun ()  ->
        create_tables("UsrTabFile"),
        Seq = lists:seq(1,100000),
        Add = fun(Id) -> add_usr(#usr{msisdn = 700000000 + Id,
                                      id = Id,
                                      plan = prepay,
                                      services = [data, sms, lbs]})
              end,
        lists:foreach(Add, Seq)
      end,
      fun (_) -> ?cmd("rm UsrTabFile") end,
      ?_assertMatch({ok, #usr{status = enabled}} , lookup_msisdn(700000001) )
    }
  }.

We can run these two tests by calling Mod:test() or eunit:test(Mod), where Mod is the name of the module containing the tests.

Revisit the exercises in Chapter 3, and devise EUnit tests for your solutions: do your solutions pass all the tests? Is that because of faults in the solutions or in the way you have defined the tests?

Devise tests within EUnit for the echo process introduced in Chapter 4. How do you have to change the tests when the implementation is modified to register the process?

How would you define EUnit tests for a software upgrade in the db_server example given in Chapter 8?

Incorporate the test examples given in Chapter 12 into the EUnit framework.

Devise EUnit tests for the solutions to the exercises in Chapter 12.