aboutsummaryrefslogtreecommitdiffstats
path: root/guide/eunit.html
blob: 2bbeecdf78259a49cd7cda7b5de468b00cdb5983 (plain) (blame)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="utf-8"/>
<title>Erlang.mk User Guide</title>
<style type="text/css"><!--
body{background:white;color:black;font-family:"Open Sans", "Helvetica Neue", Helvetica, Arial, sans-serif;justify-content:center;margin:0 auto;padding:0;width:600px}
header {align-items:center;display:flex;justify-content:center}
header nav.left{text-align:right;width:150px}
header nav.right{text-align:left;width:150px}
header nav a{display:block;margin:1.5em 1em}
main{margin-top:2em;text-align:justify}
main h2, main h3{margin-top:2em}
main h1, main div.chapter>div.titlepage h2{font-size:2em;margin-top:.67em}
a{color:#d9230f;text-decoration:none}
a:hover{text-decoration:underline}
a.xref{display:none}
h1, h2, h3{font-weight:normal}
div.navfooter{margin-bottom:1em}
--></style>
</head>
<body>
<header>
	<nav class="left">
		<a href="index.html">User guide</a>
		<a href="getting_started.html">Tutorials</a>
	</nav>
	<a href="/" class="logo"><img src="../res/logo-small.png" alt="Erlang.mk" title="Erlang.mk: A build tool for Erlang that just works" height="200" width="206"/></a>
	<nav class="right">
		<a href="https://github.com/ninenines/erlang.mk/tree/master/index">470+ packages</a>
		<a href="https://github.com/ninenines/erlang.mk/issues">Issues?</a>
	</nav>
</header>
<main>

<div class="navheader"><table width="100%" summary="Navigation header"><tr><td width="20%" align="left"><a accesskey="p" href="shell.html">Prev</a> </td><th width="60%" align="center"> </th><td width="20%" align="right"> <a accesskey="n" href="ct.html">Next</a></td></tr></table><hr /></div><div class="chapter"><div class="titlepage"><div><div><h2 class="title"><a id="eunit"></a>Chapter 15. EUnit</h2></div></div></div><p>EUnit is the tool of choice for unit testing. Erlang.mk
automates a few things on top of EUnit, including the
discovery and running of unit tests.</p><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="_writing_tests"></a>15.1. Writing tests</h2></div></div></div><p>The <a class="ulink" href="http://www.erlang.org/doc/apps/eunit/chapter.html" target="_top">EUnit user guide</a>
is the best place to learn how to write tests. Of note is
that all functions ending with <code class="literal">_test</code> or <code class="literal">_test_</code> will be
picked up as EUnit test cases.</p><p>Erlang.mk will automatically pick up tests found in any of
the Erlang modules of your application. It will also pick up
tests located in the <span class="emphasis"><em>$(TEST_DIR)</em></span> directory, which defaults
to <span class="emphasis"><em>test/</em></span>.</p><p>It is generally a good practice to hide test code from
the code you ship to production. With Erlang.mk, you can
do this thanks to the <code class="literal">TEST</code> macro. It is only defined
when running tests:</p><pre class="programlisting">-ifdef(TEST).

%% Insert tests here.

-endif.</pre><p>Be careful, however, if you include the EUnit header file,
as it also defines the <code class="literal">TEST</code> macro. Make sure to only include
it inside an <code class="literal">ifdef</code> block, otherwise tests will always be
compiled.</p><pre class="programlisting">-ifdef(TEST).

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

%% Insert tests here.

-endif.</pre><p>Erlang.mk will automatically recompile your code when you
perform a normal build after running tests, and vice versa.</p></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="_configuration_5"></a>15.2. Configuration</h2></div></div></div><p>The <code class="literal">EUNIT_OPTS</code> variable allows you to specify additional
EUnit options. Options are documented in the
<a class="ulink" href="http://www.erlang.org/doc/man/eunit.html#test-2" target="_top">EUnit manual</a>.
At the time of writing, the only available option is <code class="literal">verbose</code>:</p><pre class="programlisting">EUNIT_OPTS = verbose</pre><p>The <code class="literal">EUNIT_ERL_OPTS</code> variable allows you to specify options
to be passed to <code class="literal">erl</code> when running EUnit tests. For example,
you can load the <span class="emphasis"><em>vm.args</em></span> and <span class="emphasis"><em>sys.config</em></span> files:</p><pre class="programlisting">EUNIT_ERL_OPTS = -args_file rel/vm.args -config rel/sys.config</pre></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="_usage_4"></a>15.3. Usage</h2></div></div></div><p>To run all tests (including EUnit):</p><pre class="programlisting">$ make tests</pre><p>To run all tests and static checks (including EUnit):</p><pre class="programlisting">$ make check</pre><p>You can also run EUnit separately:</p><pre class="programlisting">$ make eunit</pre><p>EUnit will be quiet by default, only outputting errors.
You can easily make it verbose for a single invocation:</p><pre class="programlisting">$ make eunit EUNIT_OPTS=verbose</pre><p>Erlang.mk allows you to run all tests from a specific
module, or a specific test case from that module, using
the variable <code class="literal">t</code>.</p><p>For example, to run all tests from the <code class="literal">cow_http_hd</code>
module (instead of all tests from the entire project),
one could write:</p><pre class="programlisting">$ make eunit t=cow_http_hd</pre><p>Similarly, to run a specific test case:</p><pre class="programlisting">$ make eunit t=cow_http_hd:parse_accept_test_</pre><p>To do the same against a multi-application repository,
you can use the <code class="literal">-C</code> option:</p><pre class="programlisting">$ make -C apps/my_app eunit t=my_module:hello_test</pre><p>Note that this also applies to dependencies. From Cowboy,
you can run the following directly:</p><pre class="programlisting">$ make -C deps/cowlib eunit t=cow_http_hd</pre><p>Finally, <a class="link" href="coverage.html" title="Chapter 17. Code coverage">code coverage</a>
<a class="xref" href="coverage.html" title="Chapter 17. Code coverage">Chapter 17, <em>Code coverage</em></a> is available,
but covered in its own chapter.</p></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="shell.html">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="tests.html">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="ct.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top"> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right" valign="top"> </td></tr></table></div>
</main>
</body>
</html>