<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html xmlns:fn="http://www.w3.org/2005/02/xpath-functions">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
<link rel="stylesheet" href="../../../../doc/otp_doc.css" type="text/css">
<title>Erlang -- cover</title>
</head>
<body bgcolor="white" text="#000000" link="#0000ff" vlink="#ff00ff" alink="#ff0000"><div id="container">
<script id="js" type="text/javascript" language="JavaScript" src="../../../../doc/js/flipmenu/flipmenu.js"></script><script id="js2" type="text/javascript" src="../../../../doc/js/erlresolvelinks.js"></script><script language="JavaScript" type="text/javascript">
<!--
function getWinHeight() {
var myHeight = 0;
if( typeof( window.innerHeight ) == 'number' ) {
//Non-IE
myHeight = window.innerHeight;
} else if( document.documentElement && ( document.documentElement.clientWidth ||
document.documentElement.clientHeight ) ) {
//IE 6+ in 'standards compliant mode'
myHeight = document.documentElement.clientHeight;
} else if( document.body && ( document.body.clientWidth || document.body.clientHeight ) ) {
//IE 4 compatible
myHeight = document.body.clientHeight;
}
return myHeight;
}
function setscrollpos() {
var objf=document.getElementById('loadscrollpos');
document.getElementById("leftnav").scrollTop = objf.offsetTop - getWinHeight()/2;
}
function addEvent(obj, evType, fn){
if (obj.addEventListener){
obj.addEventListener(evType, fn, true);
return true;
} else if (obj.attachEvent){
var r = obj.attachEvent("on"+evType, fn);
return r;
} else {
return false;
}
}
addEvent(window, 'load', setscrollpos);
//--></script><div id="leftnav"><div class="innertube">
<img alt="Erlang logo" src="../../../../doc/erlang-logo.png"><br><small><a href="users_guide.html">User's Guide</a><br><a href="index.html">Reference Manual</a><br><a href="release_notes.html">Release Notes</a><br><a href="../pdf/tools-2.6.8.pdf">PDF</a><br><a href="../../../../doc/index.html">Top</a></small><p><strong>Tools</strong><br><strong>User's Guide</strong><br><small>Version 2.6.8</small></p>
<br><a href="javascript:openAllFlips()">Expand All</a><br><a href="javascript:closeAllFlips()">Contract All</a><p><small><strong>Chapters</strong></small></p>
<ul class="flipMenu" imagepath="../../../../doc/js/flipmenu">
<li id="loadscrollpos" title="cover" expanded="true">cover<ul>
<li><a href="cover_chapter.html">
Top of chapter
</a></li>
<li title="Introduction"><a href="cover_chapter.html#id64809">Introduction</a></li>
<li title="Getting Started With Cover"><a href="cover_chapter.html#id62638">Getting Started With Cover</a></li>
<li title="Miscellaneous"><a href="cover_chapter.html#id60749">Miscellaneous</a></li>
<li title="Using the Web Based User Interface to Cover"><a href="cover_chapter.html#id63969">Using the Web Based User Interface to Cover</a></li>
</ul>
</li>
<li id="no" title="cprof - The Call Count Profiler" expanded="false">cprof - The Call Count Profiler<ul>
<li><a href="cprof_chapter.html">
Top of chapter
</a></li>
<li title="Example: Background work"><a href="cprof_chapter.html#id62155">Example: Background work</a></li>
<li title="Example: One module"><a href="cprof_chapter.html#id62215">Example: One module</a></li>
<li title="Example: In the code"><a href="cprof_chapter.html#id62262">Example: In the code</a></li>
</ul>
</li>
<li id="no" title="The Erlang mode for Emacs" expanded="false">The Erlang mode for Emacs<ul>
<li><a href="erlang_mode_chapter.html">
Top of chapter
</a></li>
<li title="Purpose"><a href="erlang_mode_chapter.html#id64082">Purpose</a></li>
<li title="Pre-requisites"><a href="erlang_mode_chapter.html#id64101">Pre-requisites</a></li>
<li title="Elisp"><a href="erlang_mode_chapter.html#id64113">Elisp</a></li>
<li title="Setup on UNIX"><a href="erlang_mode_chapter.html#id64126">Setup on UNIX</a></li>
<li title="Setup on Windows "><a href="erlang_mode_chapter.html#id64160">Setup on Windows </a></li>
<li title="Indentation"><a href="erlang_mode_chapter.html#id64228">Indentation</a></li>
<li title="Editing"><a href="erlang_mode_chapter.html#id64277">Editing</a></li>
<li title="Syntax highlighting"><a href="erlang_mode_chapter.html#id64373">Syntax highlighting</a></li>
<li title="Tags"><a href="erlang_mode_chapter.html#id64396">Tags</a></li>
<li title="Etags"><a href="erlang_mode_chapter.html#id64430">Etags</a></li>
<li title="Shell"><a href="erlang_mode_chapter.html#id64528">Shell</a></li>
<li title="Compilation"><a href="erlang_mode_chapter.html#id64585">Compilation</a></li>
</ul>
</li>
<li id="no" title="fprof - The File Trace Profiler" expanded="false">fprof - The File Trace Profiler<ul>
<li><a href="fprof_chapter.html">
Top of chapter
</a></li>
<li title="Profiling from the source code"><a href="fprof_chapter.html#id64914">Profiling from the source code</a></li>
<li title="Profiling a function"><a href="fprof_chapter.html#id64995">Profiling a function</a></li>
<li title="Immediate profiling"><a href="fprof_chapter.html#id65025">Immediate profiling</a></li>
</ul>
</li>
<li id="no" title="lcnt - The Lock Profiler" expanded="false">lcnt - The Lock Profiler<ul>
<li><a href="lcnt_chapter.html">
Top of chapter
</a></li>
<li title=" Enabling lock-counting "><a href="lcnt_chapter.html#id65145"> Enabling lock-counting </a></li>
<li title="Getting started"><a href="lcnt_chapter.html#id65194">Getting started</a></li>
<li title=" Example of usage "><a href="lcnt_chapter.html#id65262"> Example of usage </a></li>
<li title=" Example with Mnesia Transaction Benchmark "><a href="lcnt_chapter.html#id65351"> Example with Mnesia Transaction Benchmark </a></li>
<li title=" Deciphering the output "><a href="lcnt_chapter.html#id65488"> Deciphering the output </a></li>
<li title="See Also"><a href="lcnt_chapter.html#id65506">See Also</a></li>
</ul>
</li>
<li id="no" title="Xref - The Cross Reference Tool" expanded="false">Xref - The Cross Reference Tool<ul>
<li><a href="xref_chapter.html">
Top of chapter
</a></li>
<li title="Module Check"><a href="xref_chapter.html#id65613">Module Check</a></li>
<li title="Predefined Analysis"><a href="xref_chapter.html#id65693">Predefined Analysis</a></li>
<li title="Expressions"><a href="xref_chapter.html#id65996">Expressions</a></li>
<li title="Graph Analysis"><a href="xref_chapter.html#id66325">Graph Analysis</a></li>
</ul>
</li>
</ul>
</div></div>
<div id="content">
<div class="innertube">
<h1>1 cover</h1>
<h3><a name="id64809">1.1
Introduction</a></h3>
<p>The module <span class="code">cover</span> provides a set of functions for coverage
analysis of Erlang programs, counting how many times each
<span class="bold_code"><a href="#lines">executable line</a></span> is executed.</p>
<p>Coverage analysis can be used to verify test cases, making sure all
relevant code is covered, and may be helpful when looking for
bottlenecks in the code.</p>
<h3><a name="id62638">1.2
Getting Started With Cover</a></h3>
<h4>Example</h4>
<p>Assume that a test case for the following program should be
verified:</p>
<div class="example"><pre>
-module(channel).
-behaviour(gen_server).
-export([start_link/0,stop/0]).
-export([alloc/0,free/1]). % client interface
-export([init/1,handle_call/3,terminate/2]). % callback functions
start_link() ->
gen_server:start_link({local,channel},channel,[],[]).
stop() ->
gen_server:call(channel,stop).
%%%-Client interface functions-------------------------------------------
alloc() ->
gen_server:call(channel,alloc).
free(Channel) ->
gen_server:call(channel,{free,Channel}).
%%%-gen_server callback functions----------------------------------------
init(_Arg) ->
{ok,channels()}.
handle_call(stop,Client,Channels) ->
{stop,normal,ok,Channels};
handle_call(alloc,Client,Channels) ->
{Ch,Channels2} = alloc(Channels),
{reply,{ok,Ch},Channels2};
handle_call({free,Channel},Client,Channels) ->
Channels2 = free(Channel,Channels),
{reply,ok,Channels2}.
terminate(_Reason,Channels) ->
ok.
%%%-Internal functions---------------------------------------------------
channels() ->
[ch1,ch2,ch3].
alloc([Channel|Channels]) ->
{Channel,Channels};
alloc([]) ->
false.
free(Channel,Channels) ->
[Channel|Channels].</pre></div>
<p>The test case is implemented as follows:</p>
<div class="example"><pre>
-module(test).
-export([s/0]).
s() ->
{ok,Pid} = channel:start_link(),
{ok,Ch1} = channel:alloc(),
ok = channel:free(Ch1),
ok = channel:stop().</pre></div>
<h4>Preparation</h4>
<p>First of all, Cover must be started. This spawns a process which
owns the Cover database where all coverage data will be stored.</p>
<div class="example"><pre>
1> <span class="bold_code">cover:start().</span>
{ok,<0.30.0>}</pre></div>
<p>To include other nodes in the coverage analysis, use
<span class="code">start/1</span>. All cover compiled modules will then be loaded
on all nodes, and data from all nodes will be summed up when
analysing. For simplicity this example only involves the
current node.</p>
<p>Before any analysis can take place, the involved modules must be
<strong>Cover compiled</strong>. This means that some extra information is
added to the module before it is compiled into a binary which then
is <span class="bold_code"><a href="#loading">loaded</a></span>. The source file of
the module is not affected and no <span class="code">.beam</span> file is created.</p>
<div class="example"><pre>
2> <span class="bold_code">cover:compile_module(channel).</span>
{ok,channel}</pre></div>
<p>Each time a function in the Cover compiled module <span class="code">channel</span>
is called, information about the call will be added to the Cover
database. Run the test case:</p>
<div class="example"><pre>
3> <span class="bold_code">test:s().</span>
ok</pre></div>
<p>Cover analysis is performed by examining the contents of the Cover
database. The output is determined by two parameters, <span class="code">Level</span>
and <span class="code">Analysis</span>. <span class="code">Analysis</span> is either <span class="code">coverage</span> or
<span class="code">calls</span> and determines the type of the analysis. <span class="code">Level</span>
is either <span class="code">module</span>, <span class="code">function</span>, <span class="code">clause</span>, or
<span class="code">line</span> and determines the level of the analysis.</p>
<h4>Coverage Analysis</h4>
<p>Analysis of type <span class="code">coverage</span> is used to find out how much of
the code has been executed and how much has not been executed.
Coverage is represented by a tuple <span class="code">{Cov,NotCov}</span>, where
<span class="code">Cov</span> is the number of executable lines that have been executed
at least once and <span class="code">NotCov</span> is the number of executable lines
that have not been executed.</p>
<p>If the analysis is made on module level, the result is given for
the entire module as a tuple <span class="code">{Module,{Cov,NotCov}}</span>:</p>
<div class="example"><pre>
4> <span class="bold_code">cover:analyse(channel,coverage,module).</span>
{ok,{channel,{14,1}}}</pre></div>
<p>For <span class="code">channel</span>, the result shows that 14 lines in the module
are covered but one line is not covered.</p>
<p>If the analysis is made on function level, the result is given as
a list of tuples <span class="code">{Function,{Cov,NotCov}}</span>, one for each
function in the module. A function is specified by its module name,
function name and arity:</p>
<div class="example"><pre>
5> <span class="bold_code">cover:analyse(channel,coverage,function).</span>
{ok,[{{channel,start_link,0},{1,0}},
{{channel,stop,0},{1,0}},
{{channel,alloc,0},{1,0}},
{{channel,free,1},{1,0}},
{{channel,init,1},{1,0}},
{{channel,handle_call,3},{5,0}},
{{channel,terminate,2},{1,0}},
{{channel,channels,0},{1,0}},
{{channel,alloc,1},{1,1}},
{{channel,free,2},{1,0}}]}</pre></div>
<p>For <span class="code">channel</span>, the result shows that the uncovered line is in
the function <span class="code">channel:alloc/1</span>.</p>
<p>If the analysis is made on clause level, the result is given as
a list of tuples <span class="code">{Clause,{Cov,NotCov}}</span>, one for each
function clause in the module. A clause is specified by its module
name, function name, arity and position within the function
definition:</p>
<div class="example"><pre>
6> <span class="bold_code">cover:analyse(channel,coverage,clause).</span>
{ok,[{{channel,start_link,0,1},{1,0}},
{{channel,stop,0,1},{1,0}},
{{channel,alloc,0,1},{1,0}},
{{channel,free,1,1},{1,0}},
{{channel,init,1,1},{1,0}},
{{channel,handle_call,3,1},{1,0}},
{{channel,handle_call,3,2},{2,0}},
{{channel,handle_call,3,3},{2,0}},
{{channel,terminate,2,1},{1,0}},
{{channel,channels,0,1},{1,0}},
{{channel,alloc,1,1},{1,0}},
{{channel,alloc,1,2},{0,1}},
{{channel,free,2,1},{1,0}}]}</pre></div>
<p>For <span class="code">channel</span>, the result shows that the uncovered line is in
the second clause of <span class="code">channel:alloc/1</span>.</p>
<p>Finally, if the analysis is made on line level, the result is given
as a list of tuples <span class="code">{Line,{Cov,NotCov}}</span>, one for each
executable line in the source code. A line is specified by its
module name and line number.</p>
<div class="example"><pre>
7> <span class="bold_code">cover:analyse(channel,coverage,line).</span>
{ok,[{{channel,9},{1,0}},
{{channel,12},{1,0}},
{{channel,17},{1,0}},
{{channel,20},{1,0}},
{{channel,25},{1,0}},
{{channel,28},{1,0}},
{{channel,31},{1,0}},
{{channel,32},{1,0}},
{{channel,35},{1,0}},
{{channel,36},{1,0}},
{{channel,39},{1,0}},
{{channel,44},{1,0}},
{{channel,47},{1,0}},
{{channel,49},{0,1}},
{{channel,52},{1,0}}]}</pre></div>
<p>For <span class="code">channel</span>, the result shows that the uncovered line is
line number 49.</p>
<h4>Call Statistics</h4>
<p>Analysis of type <span class="code">calls</span> is used to find out how many times
something has been called and is represented by an integer
<span class="code">Calls</span>.</p>
<p>If the analysis is made on module level, the result is given as a
tuple <span class="code">{Module,Calls}</span>. Here <span class="code">Calls</span> is the total number
of calls to functions in the module:</p>
<div class="example"><pre>
8> <span class="bold_code">cover:analyse(channel,calls,module).</span>
{ok,{channel,12}}</pre></div>
<p>For <span class="code">channel</span>, the result shows that a total of twelve calls
have been made to functions in the module.</p>
<p>If the analysis is made on function level, the result is given as
a list of tuples <span class="code">{Function,Calls}</span>. Here <span class="code">Calls</span> is
the number of calls to each function:</p>
<div class="example"><pre>
9> <span class="bold_code">cover:analyse(channel,calls,function).</span>
{ok,[{{channel,start_link,0},1},
{{channel,stop,0},1},
{{channel,alloc,0},1},
{{channel,free,1},1},
{{channel,init,1},1},
{{channel,handle_call,3},3},
{{channel,terminate,2},1},
{{channel,channels,0},1},
{{channel,alloc,1},1},
{{channel,free,2},1}]}</pre></div>
<p>For <span class="code">channel</span>, the result shows that <span class="code">handle_call/3</span> is
the most called function in the module (three calls). All other
functions have been called once.</p>
<p>If the analysis is made on clause level, the result is given as
a list of tuples <span class="code">{Clause,Calls}</span>. Here <span class="code">Calls</span> is
the number of calls to each function clause:</p>
<div class="example"><pre>
10> <span class="bold_code">cover:analyse(channel,calls,clause).</span>
{ok,[{{channel,start_link,0,1},1},
{{channel,stop,0,1},1},
{{channel,alloc,0,1},1},
{{channel,free,1,1},1},
{{channel,init,1,1},1},
{{channel,handle_call,3,1},1},
{{channel,handle_call,3,2},1},
{{channel,handle_call,3,3},1},
{{channel,terminate,2,1},1},
{{channel,channels,0,1},1},
{{channel,alloc,1,1},1},
{{channel,alloc,1,2},0},
{{channel,free,2,1},1}]}</pre></div>
<p>For <span class="code">channel</span>, the result shows that all clauses have been
called once, except the second clause of <span class="code">channel:alloc/1</span>
which has not been called at all.</p>
<p>Finally, if the analysis is made on line level, the result is given
as a list of tuples <span class="code">{Line,Calls}</span>. Here <span class="code">Calls</span> is
the number of times each line has been executed:</p>
<div class="example"><pre>
11> <span class="bold_code">cover:analyse(channel,calls,line).</span>
{ok,[{{channel,9},1},
{{channel,12},1},
{{channel,17},1},
{{channel,20},1},
{{channel,25},1},
{{channel,28},1},
{{channel,31},1},
{{channel,32},1},
{{channel,35},1},
{{channel,36},1},
{{channel,39},1},
{{channel,44},1},
{{channel,47},1},
{{channel,49},0},
{{channel,52},1}]}</pre></div>
<p>For <span class="code">channel</span>, the result shows that all lines have been
executed once, except line number 49 which has not been executed at
all.</p>
<h4>Analysis to File</h4>
<p>A line level calls analysis of <span class="code">channel</span> can be written to
a file using <span class="code">cover:analysis_to_file/1</span>:</p>
<div class="example"><pre>
12> <span class="bold_code">cover:analyse_to_file(channel).</span>
{ok,"channel.COVER.out"}</pre></div>
<p>The function creates a copy of <span class="code">channel.erl</span> where it for
each executable line is specified how many times that line has been
executed. The output file is called <span class="code">channel.COVER.out</span>.</p>
<div class="example"><pre>
File generated from channel.erl by COVER 2001-05-21 at 11:16:38
****************************************************************************
| -module(channel).
| -behaviour(gen_server).
|
| -export([start_link/0,stop/0]).
| -export([alloc/0,free/1]). % client interface
| -export([init/1,handle_call/3,terminate/2]). % callback functions
|
| start_link() ->
1..| gen_server:start_link({local,channel},channel,[],[]).
|
| stop() ->
1..| gen_server:call(channel,stop).
|
| %%%-Client interface functions------------------------------------
|
| alloc() ->
1..| gen_server:call(channel,alloc).
|
| free(Channel) ->
1..| gen_server:call(channel,{free,Channel}).
|
| %%%-gen_server callback functions---------------------------------
|
| init(_Arg) ->
1..| {ok,channels()}.
|
| handle_call(stop,Client,Channels) ->
1..| {stop,normal,ok,Channels};
|
| handle_call(alloc,Client,Channels) ->
1..| {Ch,Channels2} = alloc(Channels),
1..| {reply,{ok,Ch},Channels2};
|
| handle_call({free,Channel},Client,Channels) ->
1..| Channels2 = free(Channel,Channels),
1..| {reply,ok,Channels2}.
|
| terminate(_Reason,Channels) ->
1..| ok.
|
| %%%-Internal functions--------------------------------------------
|
| channels() ->
1..| [ch1,ch2,ch3].
|
| alloc([Channel|Channels]) ->
1..| {Channel,Channels};
| alloc([]) ->
0..| false.
|
| free(Channel,Channels) ->
1..| [Channel|Channels].</pre></div>
<h4>Conclusion</h4>
<p>By looking at the results from the analyses, it can be deducted
that the test case does not cover the case when all channels are
allocated and <span class="code">test.erl</span> should be extended accordingly. <br>
Incidentally, when the test case is corrected a bug in <span class="code">channel</span>
should indeed be discovered.</p>
<p>When the Cover analysis is ready, Cover is stopped and all Cover
compiled modules are <span class="bold_code"><a href="#loading">unloaded</a></span>.
The code for <span class="code">channel</span> is now loaded as usual from a
<span class="code">.beam</span> file in the current path.</p>
<div class="example"><pre>
13> <span class="bold_code">code:which(channel).</span>
cover_compiled
14> <span class="bold_code">cover:stop().</span>
ok
15> <span class="bold_code">code:which(channel).</span>
"./channel.beam"</pre></div>
<h3><a name="id60749">1.3
Miscellaneous</a></h3>
<h4>Performance</h4>
<p>Execution of code in Cover compiled modules is slower and more
memory consuming than for regularly compiled modules. As the Cover
database contains information about each executable line in each
Cover compiled module, performance decreases proportionally to
the size and number of the Cover compiled modules.</p>
<p>To improve performance when analysing cover results it is possible
to do multiple calls to <span class="bold_code"><a href="cover.html#analyse-1">analyse</a></span>
and <span class="bold_code"><a href="cover.html#analyse_to_file-1">analyse_to_file</a></span>
at once. You can also use the
<span class="bold_code"><a href="cover.html#async_analyse_to_file-1">async_analyse_to_file</a></span>
convenience function.
</p>
<h4>Executable Lines</h4>
<a name="lines"></a>
<p>Cover uses the concept of <strong>executable lines</strong>, which is lines
of code containing an executable expression such as a matching or
a function call. A blank line or a line containing a comment,
function head or pattern in a <span class="code">case</span>- or <span class="code">receive</span>
statement is not executable.</p>
<p>In the example below, lines number 2,4,6,8 and 11 are executable
lines:</p>
<p></p>
<div class="example"><pre>
1: is_loaded(Module,Compiled) ->
2: case get_file(Module,Compiled) of
3: {ok,File} ->
4: case code:which(Module) of
5: ?TAG ->
6: {loaded,File};
7: _ ->
8: unloaded
9: end;
10: false ->
11: false
12: end.</pre></div>
<h4>Code Loading Mechanism</h4>
<a name="loading"></a>
<p>When a module is Cover compiled, it is also loaded using the normal
code loading mechanism of Erlang. This means that if a Cover
compiled module is re-loaded during a Cover session, for example
using <span class="code">c(Module)</span>, it will no longer be Cover compiled.</p>
<p>Use <span class="code">cover:is_compiled/1</span> or <span class="code">code:which/1</span> to see if
a module is Cover compiled (and still loaded) or not.</p>
<p>When Cover is stopped, all Cover compiled modules are unloaded.</p>
<h3><a name="id63969">1.4
Using the Web Based User Interface to Cover</a></h3>
<h4>Introduction</h4>
<p>To ease the use of Cover there is a web based user interface
to Cover called WebCover. WebCover is designed to be started
and used via WebTool. It is possible to Cover compile Erlang
modules and to generate printable Cover and Call analyses via
the web based user interface.</p>
<h4>Start the Web Based User Interface to Cover</h4>
<p>To start WebCover you can either start WebTool, point a
browser to the start page of WebTool and start WebCover from
there, or you can use the <span class="code">start_webtool</span> script to start
Webtool, WebCover and a browser. See WebTool documentation for
further information.</p>
<p>Currently WebCover is only compatible
with Internet Explorer and Netscape Navigator 4.0 and higher.</p>
<h4>Navigating WebCover</h4>
<p>From the menu in the lefthand frame you can select the
<span class="code">Nodes</span>, <span class="code">Compile</span>, <span class="code">Import</span> or <span class="code">Result</span>
page.</p>
<p>From the <span class="code">Nodes</span> page you can add remote nodes to
participate in the coverage analysis. Coverage data from all
involved nodes will then be merged during analysis.</p>
<p>From the <span class="code">Compile</span> page you can Cover compile <span class="code">.erl</span>
or <span class="code">.beam</span> files.</p>
<p>From the <span class="code">Import</span> page you can import coverage data from
a previous analysis. Imported data will then be merged with
the current coverage data. <strong>Note</strong> that it is only possible to
import files with the extension <span class="code">.coverdata</span>.</p>
<p>From the <span class="code">Result</span> page you can analyse, reset or export
coverage data.</p>
<p>Please follow the instructions on each page.</p>
</div>
<div class="footer">
<hr>
<p>Copyright © 1997-2012 Ericsson AB. All Rights Reserved.</p>
</div>
</div>
</div></body>
</html>
distrib
>
Fedora
>
17
>
i386
>
media
>
updates
>
by-pkgid
>
675c8c8167236dfcf8d66da674f931e8
>
files
>
1506
