A RetroSearch Logo

Home - News ( United States | United Kingdom | Italy | Germany ) - Football scores

Search Query:

Showing content from http://www.erlang.org/doc/apps/eunit/chapter below:

a Lightweight Unit Testing Framework for Erlang — eunit v2.10

EUnit - a Lightweight Unit Testing Framework for Erlang View Source

EUnit is a unit testing framework for Erlang. It is very powerful and flexible, is easy to use, and has small syntactical overhead.

EUnit builds on ideas from the family of unit testing frameworks for Object Oriented languages that originated with JUnit by Beck and Gamma (and Beck's previous framework SUnit for Smalltalk). However, EUnit uses techniques more adapted to functional and concurrent programming, and is typically less verbose than its relatives.

Although EUnit uses many preprocessor macros, they have been designed to be as nonintrusive as possible, and should not cause conflicts with existing code. Adding EUnit tests to a module should thus not normally require changing existing code. Furthermore, tests that only exercise the exported functions of a module can always be placed in a completely separate module, avoiding any conflicts entirely.

Unit testing

Unit Testing is testing of individual program "units" in relative isolation. There is no particular size requirement: a unit can be a function, a module, a process, or even a whole application, but the most typical testing units are individual functions or modules. In order to test a unit, you specify a set of individual tests, set up the smallest necessary environment for being able to run those tests (often, you don't need to do any setup at all), you run the tests and collect the results, and finally you do any necessary cleanup so that the test can be run again later. A Unit Testing Framework tries to help you in each stage of this process, so that it is easy to write tests, easy to run them, and easy to see which tests failed (so you can fix the bugs).

Advantages of unit testing Terminology Getting started

The simplest way to use EUnit in an Erlang module is to add the following line at the beginning of the module (after the -module declaration, but before any function definitions):

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

This will have the following effect:

Note: For -include_lib(...) to work, the Erlang module search path must contain a directory whose name ends in eunit/ebin (pointing to the ebin subdirectory of the EUnit installation directory). If EUnit is installed as lib/eunit under your Erlang/OTP system directory, its ebin subdirectory will be automatically added to the search path when Erlang starts. Otherwise, you need to add the directory explicitly, by passing a -pa flag to the erl or erlc command. For example, a Makefile could contain the following action for compiling .erl files:

   erlc -pa "path/to/eunit/ebin" $(ERL_COMPILE_FLAGS) -o$(EBIN) $<

or if you want Eunit to always be available when you run Erlang interactively, you can add a line like the following to your $HOME/.erlang file:

   code:add_path("/path/to/eunit/ebin").
Writing simple test functions

The EUnit framework makes it extremely easy to write unit tests in Erlang. There are a few different ways of writing them, though, so we start with the simplest:

A function with a name ending in ..._test() is recognized by EUnit as a simple test function - it takes no arguments, and its execution either succeeds (returning some arbitrary value that EUnit will throw away), or fails by throwing an exception of some kind (or by not terminating, in which case it will be aborted after a while).

An example of a simple test function could be the following:

   reverse_test() -> lists:reverse([1,2,3]).

This just tests that the function lists:reverse(List) does not crash when List is [1,2,3]. It is not a great test, but many people write simple functions like this one to test the basic functionality of their code, and those tests can be used directly by EUnit, without changes, as long as their function names match.

Use exceptions to signal failure To write more interesting tests, we need to make them crash (throw an exception) when they don't get the result they expect. A simple way of doing this is to use pattern matching with =, as in the following examples:

   reverse_nil_test() -> [] = lists:reverse([]).
   reverse_one_test() -> [1] = lists:reverse([1]).
   reverse_two_test() -> [2,1] = lists:reverse([1,2]).

If there was some bug in lists:reverse/1 that made it return something other than [2,1] when it got [1,2] as input, then the last test above would throw a badmatch error. The first two (we assume they do not get a badmatch) would simply return [] and [1], respectively, so both succeed. (Note that EUnit is not psychic: if you write a test that returns a value, even if it is the wrong value, EUnit will consider it a success. You must make sure that the test is written so that it causes a crash if the result is not what it should be.)

Using assert macros If you want to use Boolean operators for your tests, the assert macro comes in handy (see EUnit macros for details):

   length_test() -> ?assert(length([1,2,3]) =:= 3).

The ?assert(Expression) macro will evaluate Expression, and if that does not evaluate to true, it will throw an exception; otherwise it just returns ok. In the above example, the test will thus fail if the call to length does not return 3.

Running EUnit

If you have added the declaration -include_lib("eunit/include/eunit.hrl") to your module, as described above, you only need to compile the module, and run the automatically exported function test(). For example, if your module was named m, then calling \m:test() will run EUnit on all the tests defined in the module. You do not need to write -export declarations for the test functions. This is all done by magic.

You can also use the function eunit:test/1 to run arbitrary tests, for example to try out some more advanced test descriptors (see EUnit test representation). For example, running eunit:test(m) does the same thing as the auto-generated function \m:test(), while eunit:test({inparallel, m}) runs the same test cases but executes them all in parallel.

Putting tests in separate modules

If you want to separate your test code from your normal code (at least for testing the exported functions), you can simply write the test functions in a module named m_tests (note: not m_test), if your module is named m. Then, whenever you ask EUnit to test the module m, it will also look for the module m_tests and run those tests as well. See ModuleName in the section Primitives for details.

EUnit captures standard output

If your test code writes to the standard output, you may be surprised to see that the text does not appear on the console when the tests are running. This is because EUnit captures all standard output from test functions (this also includes setup and cleanup functions, but not generator functions), so that it can be included in the test report if errors occur. To bypass EUnit and print text directly to the console while testing, you can write to the user output stream, as in io:format(user, "~w", [Term]). The recommended way of doing this is to use the EUnit Debugging macros, which make it much simpler.

For checking the output produced by the unit under test, see Macros for checking output.

Writing test generating functions

A drawback of simple test functions is that you must write a separate function (with a separate name) for each test case. A more compact way of writing tests (and much more flexible, as we shall see), is to write functions that return tests, instead of being tests.

A function with a name ending in ..._test_() (note the final underscore) is recognized by EUnit as a test generator function. Test generators return a representation of a set of tests to be executed by EUnit.

Representing a test as data The most basic representation of a test is a single fun-expression that takes no arguments. For example, the following test generator:

   basic_test_() ->
       fun () -> ?assert(1 + 1 =:= 2) end.

will have the same effect as the following simple test:

   simple_test() ->
       ?assert(1 + 1 =:= 2).

(in fact, EUnit will handle all simple tests just like it handles fun-expressions: it will put them in a list, and run them one by one).

Using macros to write tests To make tests more compact and readable, as well as automatically add information about the line number in the source code where a test occurred (and reduce the number of characters you have to type), you can use the _test macro (note the initial underscore character), like this:

   basic_test_() ->
       ?_test(?assert(1 + 1 =:= 2)).

The _test macro takes any expression (the "body") as argument, and places it within a fun-expression (along with some extra information). The body can be any kind of test expression, just like the body of a simple test function.

Underscore-prefixed macros create test objects But this example can be made even shorter! Most test macros, such as the family of assert macros, have a corresponding form with an initial underscore character, which automatically adds a ?_test(...) wrapper. The above example can then simply be written:

   basic_test_() ->
       ?_assert(1 + 1 =:= 2).

which has exactly the same meaning (note the _assert instead of assert). You can think of the initial underscore as signalling test object.

An example

Sometimes, an example says more than a thousand words. The following small Erlang module shows how EUnit can be used in practice.

   -module(fib).
   -export([fib/1]).
   -include_lib("eunit/include/eunit.hrl").

   fib(0) -> 1;
   fib(1) -> 1;
   fib(N) when N > 1 -> fib(N-1) + fib(N-2).

   fib_test_() ->
       [?_assert(fib(0) =:= 1),
	?_assert(fib(1) =:= 1),
	?_assert(fib(2) =:= 2),
	?_assert(fib(3) =:= 3),
	?_assert(fib(4) =:= 5),
	?_assert(fib(5) =:= 8),
	?_assertException(error, function_clause, fib(-1)),
	?_assert(fib(31) =:= 2178309)
       ].

(Author's note: When I first wrote this example, I happened to write a * instead of + in the fib function. Of course, this showed up immediately when I ran the tests.)

See EUnit test representation for a full list of all the ways you can specify test sets in EUnit.

Disabling testing

Testing can be turned off by defining the NOTEST macro when compiling, for example as an option to erlc, as in:

   erlc -DNOTEST my_module.erl

or by adding a macro definition to the code, before the EUnit header file is included:

   -define(NOTEST, 1).

(the value is not important, but should typically be 1 or true). Note that unless the EUNIT_NOAUTO macro is defined, disabling testing will also automatically strip all test functions from the code, except for any that are explicitly declared as exported.

For instance, to use EUnit in your application, but with testing turned off by default, put the following lines in a header file:

   -define(NOTEST, true).
   -include_lib("eunit/include/eunit.hrl").

and then make sure that every module of your application includes that header file. This means that you have a single place to modify in order to change the default setting for testing. To override the NOTEST setting without modifying the code, you can define TEST in a compiler option, like this:

   erlc -DTEST my_module.erl

See Compilation control macros for details about these macros.

Avoiding compile-time dependency on EUnit

If you are distributing the source code for your application for other people to compile and run, you probably want to ensure that the code compiles even if EUnit is not available. Like the example in the previous section, you can put the following lines in a common header file:

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

and, of course, also make sure that you place all test code that uses EUnit macros within -ifdef(TEST) or -ifdef(EUNIT) sections.

EUnit macros

Although all the functionality of EUnit is available even without the use of preprocessor macros, the EUnit header file defines a number of such macros in order to make it as easy as possible to write unit tests as compactly as possible and without getting too many details in the way.

Except where explicitly stated, using EUnit macros will never introduce run-time dependencies on the EUnit library code, regardless of whether your code is compiled with testing enabled or disabled.

Basic macros Compilation control macros Utility macros

The following macros can make tests more compact and readable:

Assert macros

(Note that these macros also have corresponding forms which start with an "_" (underscore) character, as in ?_assert(BoolExpr), that create a "test object" instead of performing the test immediately. This is equivalent to writing ?_test(assert(BoolExpr)), etc.)

If the macro NOASSERT is defined before the EUnit header file is included, these macros have no effect when testing is also disabled; see Compilation control macros for details.

Macros for checking output

The following macro can be used within a test case to retrieve the output written to standard output.

Macros for running external commands

Keep in mind that external commands are highly dependent on the operating system. You can use the standard library function os:type() in test generator functions, to produce different sets of tests depending on the current operating system.

Note: these macros introduce a run-time dependency on the EUnit library code, if compiled with testing enabled.

Debugging macros

To help with debugging, EUnit defines several useful macros for printing messages directly to the console (rather than to the standard output). Furthermore, these macros all use the same basic format, which includes the file and line number where they occur, making it possible in some development environments (e.g., when running Erlang in an Emacs buffer) to simply click on the message and jump directly to the corresponding line in the code.

If the macro NODEBUG is defined before the EUnit header file is included, these macros have no effect; see Compilation control macros for details.

EUnit test representation

The way EUnit represents tests and test sets as data is flexible, powerful, and concise. This section describes the representation in detail.

Simple test objects

A simple test object is one of the following:

In brief, a simple test object consists of a single function that takes no arguments (possibly annotated with some additional metadata, i.e., a line number). Evaluation of the function either succeeds, by returning some value (which is ignored), or fails, by throwing an exception.

Test sets and deep lists

A test set can be easily created by placing a sequence of test objects in a list. If T_1, ..., T_N are individual test objects, then [T_1, ..., T_N] is a test set consisting of those objects (in that order).

Test sets can be joined in the same way: if S_1, ..., S_K are test sets, then [S_1, ..., S_K] is also a test set, where the tests of S_i are ordered before those of S_(i+1), for each subset S_i.

Thus, the main representation of test sets is deep lists, and a simple test object can be viewed as a test set containing only a single test; there is no difference between T and [T].

A module can also be used to represent a test set; see ModuleName under Primitives below.

Titles

Any test or test set T can be annotated with a title, by wrapping it in a pair {Title, T}, where Title is a string. For convenience, any test which is normally represented using a tuple can simply be given a title string as the first element, i.e., writing {"The Title", ...} instead of adding an extra tuple wrapper as in {"The Title", {...}}.

Primitives

The following are primitives, which do not contain other test sets as arguments:

Control

The following representations control how and where tests are executed:

Fixtures

A "fixture" is some state that is necessary for a particular set of tests to run. EUnit's support for fixtures makes it easy to set up such state locally for a test set, and automatically tear it down again when the test set is finished, regardless of the outcome (success, failures, timeouts, etc.).

To make the descriptions simpler, we first list some definitions:

| Setup | () -> (R::any()) | | -------------- | ------------------------------- | ---------------------------------------------- | ---------------------- | | SetupX | (X::any()) -> (R::any()) | | Cleanup | (R::any()) -> any() | | CleanupX | (X::any(), R::any()) -> any() | | Instantiator | ((R::any()) -> Tests) | {with, [AbstractTestFun::((any()) -> any())]} | | Where | local | spawn | {spawn, Node::atom()} |

(these are explained in more detail further below.)

The following representations specify fixture handling for test sets:

A Setup function is executed just before any of the specified tests are run, and a Cleanup function is executed when no more of the specified tests will be run, regardless of the reason. A Setup function takes no argument, and returns some value which will be passed as it is to the Cleanup function. A Cleanup function should do whatever necessary and return some arbitrary value, such as the atom ok. (SetupX and CleanupX functions are similar, but receive one additional argument: some value X, which depends on the context.) When no Cleanup function is specified, a dummy function is used which has no effect.

An Instantiator function receives the same value as the Cleanup function, i.e., the value returned by the Setup function. It should then behave much like a generator (see Primitives), and return a test set whose tests have been instantiated with the given value. A special case is the syntax {with, [AbstractTestFun]} which represents an instantiator function that distributes the value over a list of unary functions; see Primitives: {with, X, [...]} for more details.

A Where term controls how the specified tests are executed. The default is spawn, which means that the current process handles the setup and teardown, while the tests are executed in a subprocess. {spawn, Node} is like spawn, but runs the subprocess on the specified node. local means that the current process will handle both setup/teardown and running the tests - the drawback is that if a test times out so that the process is killed, the cleanup will not be performed; hence, avoid this for persistent fixtures such as file operations. In general, local should only be used when:

Lazy generators

Sometimes, it can be convenient not to produce the whole set of test descriptions before the testing begins; for example, if you want to generate a huge amount of tests that would take up too much space to keep in memory all at once.

It is fairly easy to write a generator which, each time it is called, either produces an empty list if it is done, or otherwise produces a list containing a single test case plus a new generator which will produce the rest of the tests. This demonstrates the basic pattern:

   lazy_test_() ->
       lazy_gen(10000).

   lazy_gen(N) ->
       {generator,
        fun () ->
            if N > 0 ->
                   [?_test(...)
                    | lazy_gen(N-1)];
               true ->
                   []
            end
        end}.

When EUnit traverses the test representation in order to run the tests, the new generator will not be called to produce the next test until the previous test has been executed.

Note that it is easiest to write this kind of recursive generator using a help function, like the lazy_gen/1 function above. It can also be written using a recursive fun, if you prefer to not clutter your function namespace and are comfortable with writing that kind of code.

RetroSearch is an open source project built by @garambo | Open a GitHub Issue

Search and Browse the WWW like it's 1997 | Search results from DuckDuckGo

HTML: 3.2 | Encoding: UTF-8 | Version: 0.7.4