Erlang: build and test

We know how to use scalars, atoms, tuples and lists; we know how to define functions via rudimental pattern matching. Now it's time to take a more rigorous approach and develop some testing capabilities before going on.

Test-Driven Development

TDD is not a language-specific technique, although some strategies (outside-in development focused on mocks) is more applicable to object-oriented programming than to a functional language. However, test-driving functions is actually how TDD is commonly taught, so we will start to explore EUnit with this example.

Building

We can add a single-step build process to our Erlang project, capable of compiling our source files and running the tests.
Let's create an Emakefile (the equivalent of a Makefile in C/C++ projects):

{['src/*'], [{outdir, "bin/"}]}.

The tuple defined by the Emakefile is composed of two arguments.

The first argument is a list of patterns to search for files to compile. In this case we can put everything we want to compile (not scripts for escript) in src/.

The second argument is a list of tuples, each representing an option. Each option starts with an atom defining what it is and adds as many values as that option requires; in this case, we are telling Erlang's make implementation to put the compiled .beam files.

If we now run:

mkdir bin/
erl -make

we will have a rudimental build process.

You can also add:

bin/*.beam

to your .gitignore or svn:ignore properties to avoid versioning compiled files.

Tests

Let's define a module, one of the basic organizations unit in Erlang. This module will contain a series of tests that we will write and run to get acquainted with EUnit.

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

simple_test() ->
    ?_assert(1 == 1).

This is the simplest test we can write: we define the module (which could be a production code module, not just one containing tests) and include EUnit. EUnit imports a series of ?_assert() macros that we can pass expressions returning booleans to; it will also automatically export and run any function whose name ends in 'test()'.

We are now ready to run our first test:

erl -make
cd bin
erl -noshell -eval 'eunit:test([{dir, "."}], [verbose])' -s init stop

erl -make compiles the files defined by the Emakefile; afterwards we move into bin/. Then we run erl with particular options:

• noshell avoids user interaction with the system, allowing us to pipe the output or filter it with other commands.
• eval makes the shell evaluate the expression, which is EUnit's exported function.
• s makes the shell call init:stop() once finished the evaluation. Without this, the shell would stay open after the tests have finished running, waiting for input.

If you put these three commands into a build.sh file, you will now be ready to run our suite with the push of a button.

Assertions

Writing test methods in xUnit tools is akin to writing ordinary methods, except for the asserting part. Each tool must provide a set of assertions that can be called to decide if the test has failed or passed, and EUnit is no different.

Here are some examples:

simple_test() ->
    ?assert(1 == 1),
    ?assertNot(1 == 0),
    ?assertMatch({number, _Var}, {number, 42}),
    ?assertEqual(1, 1),
    ?assertError(undef, lists:append()).

In the first couple of methods, we are simply asserting on a boolean.

With ?assertMatch(), we try to match the second argument to the first one, which should be a pattern like one you use in defining functions. ?assertEqual() is simpler to write than explicit comparisons.

Finally, ?assertError verifies that an error is raised while calling the expression passed as a second argument. In this case, lists:append/0 is undefined, while lists:append/2 wouldn't be.

Note that assertions in EUnit are not really functions but macros, so they will be substituted with different code during compilation. This means that it is possible for EUnit to show you the expression that generated a boolean (basically everything that you write inside ?assert() variations):

numbers_test_03: simple_test (module 'numbers_test_03')...*failed*
::error:{assertion_failed,[{module,numbers_test_03},
                         {line,5},
                         {expression,"1 == 0"},
                         {expected,true},
                         {value,false}]}

A failing test looks like this:

======================== EUnit ========================
directory "."
  numbers_test_03: simple_test (module 'numbers_test_03')...*failed*
::error:{assertEqual_failed,[{module,numbers_test_03},
                           {line,8},
                           {expression,"0"},
                           {expected,1},
                           {value,0}]}
  in function numbers_test_03:'-simple_test/0-fun-3-'/1


  [done in 0.006 s]
=======================================================
  Failed: 1.  Skipped: 0.  Passed: 0.

While a passing one shows no output other than the green bar (which is not colored here).

======================== EUnit ========================
directory "."
  numbers_test_03: simple_test (module 'numbers_test_03')...ok
  [done in 0.006 s]
=======================================================
  Test passed.

 

Conclusions

I hope I have shown you enough to get from some .erl files to a running test suite, all with the push of a button. If you need a big picture or some code to start from, take a look at the Github repository for this series.