<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html xmlns:erl="http://erlang.org" 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 -- Code Coverage Analysis</title>
</head>
<body>
<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">
<div class="erlang-logo-wrapper"><a href="../../../../doc/index.html"><img alt="Erlang Logo" src="../../../../doc/erlang-logo.png" class="erlang-logo"></a></div>
<p class="section-title">Common Test</p>
<p class="section-subtitle">User's Guide</p>
<p class="section-version">Version 1.16.1</p>
<ul class="panel-sections">
<li><a href="users_guide.html">User's Guide</a></li>
<li><a href="index.html">Reference Manual</a></li>
<li><a href="release_notes.html">Release Notes</a></li>
<li><a href="../pdf/common_test-1.16.1.pdf">PDF</a></li>
<li><a href="../../../../doc/index.html">Top</a></li>
</ul>
<ul class="expand-collapse-items">
<li><a href="javascript:openAllFlips()">Expand All</a></li>
<li><a href="javascript:closeAllFlips()">Contract All</a></li>
</ul>
<h3>Chapters</h3>
<ul class="flipMenu" imagepath="../../../../doc/js/flipmenu">
<li id="no" title="Introduction" expanded="false">Introduction<ul>
<li><a href="introduction.html">
Top of chapter
</a></li>
<li title="Scope"><a href="introduction.html#scope">Scope</a></li>
<li title="Prerequisites"><a href="introduction.html#prerequisites">Prerequisites</a></li>
</ul>
</li>
<li id="no" title="Common Test Basics" expanded="false">Common Test Basics<ul>
<li><a href="basics_chapter.html">
Top of chapter
</a></li>
<li title="General"><a href="basics_chapter.html#general">General</a></li>
<li title="Test Suite Organisation"><a href="basics_chapter.html#test-suite-organisation">Test Suite Organisation</a></li>
<li title="Support Libraries"><a href="basics_chapter.html#support-libraries">Support Libraries</a></li>
<li title="Suites and Test Cases"><a href="basics_chapter.html#suites-and-test-cases">Suites and Test Cases</a></li>
<li title="External Interfaces"><a href="basics_chapter.html#external-interfaces">External Interfaces</a></li>
</ul>
</li>
<li id="no" title="Getting Started" expanded="false">Getting Started<ul>
<li><a href="getting_started_chapter.html">
Top of chapter
</a></li>
<li title="Introduction for Newcomers"><a href="getting_started_chapter.html#introduction-for-newcomers">Introduction for Newcomers</a></li>
<li title="Test Case Execution"><a href="getting_started_chapter.html#test-case-execution">Test Case Execution</a></li>
<li title="A Simple Test Suite"><a href="getting_started_chapter.html#a-simple-test-suite">A Simple Test Suite</a></li>
<li title="A Test Suite with Configuration Functions"><a href="getting_started_chapter.html#a-test-suite-with-configuration-functions">A Test Suite with Configuration Functions</a></li>
<li title="Questions and Answers"><a href="getting_started_chapter.html#questions-and-answers">Questions and Answers</a></li>
</ul>
</li>
<li id="no" title="Installation" expanded="false">Installation<ul>
<li><a href="install_chapter.html">
Top of chapter
</a></li>
<li title="General Information"><a href="install_chapter.html#general-information">General Information</a></li>
</ul>
</li>
<li id="no" title="Writing Test Suites" expanded="false">Writing Test Suites<ul>
<li><a href="write_test_chapter.html">
Top of chapter
</a></li>
<li title="Support for Test Suite Authors"><a href="write_test_chapter.html#support-for-test-suite-authors">Support for Test Suite Authors</a></li>
<li title="Test Suites"><a href="write_test_chapter.html#test-suites">Test Suites</a></li>
<li title="Init and End per Suite"><a href="write_test_chapter.html#init-and-end-per-suite">Init and End per Suite</a></li>
<li title="Init and End per Test Case"><a href="write_test_chapter.html#init-and-end-per-test-case">Init and End per Test Case</a></li>
<li title="Test Cases"><a href="write_test_chapter.html#test-cases">Test Cases</a></li>
<li title="Test Case Information Function"><a href="write_test_chapter.html#test-case-information-function">Test Case Information Function</a></li>
<li title="Test Suite Information Function"><a href="write_test_chapter.html#test-suite-information-function">Test Suite Information Function</a></li>
<li title="Test Case Groups"><a href="write_test_chapter.html#test-case-groups">Test Case Groups</a></li>
<li title="Parallel Property and Nested Groups"><a href="write_test_chapter.html#parallel-property-and-nested-groups">Parallel Property and Nested Groups</a></li>
<li title="Parallel Test Cases and I/O"><a href="write_test_chapter.html#parallel-test-cases-and-i-o">Parallel Test Cases and I/O</a></li>
<li title="Repeated Groups"><a href="write_test_chapter.html#repeated-groups">Repeated Groups</a></li>
<li title="Shuffled Test Case Order"><a href="write_test_chapter.html#shuffled-test-case-order">Shuffled Test Case Order</a></li>
<li title="Group Information Function"><a href="write_test_chapter.html#group-information-function">Group Information Function</a></li>
<li title="Information Functions for Init- and End-Configuration"><a href="write_test_chapter.html#information-functions-for-init--and-end-configuration">Information Functions for Init- and End-Configuration</a></li>
<li title="Data and Private Directories"><a href="write_test_chapter.html#data-and-private-directories">Data and Private Directories</a></li>
<li title="Execution Environment"><a href="write_test_chapter.html#execution-environment">Execution Environment</a></li>
<li title="Timetrap Time-Outs"><a href="write_test_chapter.html#timetrap-time-outs">Timetrap Time-Outs</a></li>
<li title="Logging - Categories and Verbosity Levels"><a href="write_test_chapter.html#logging---categories-and-verbosity-levels">Logging - Categories and Verbosity Levels</a></li>
<li title="Illegal Dependencies"><a href="write_test_chapter.html#illegal-dependencies">Illegal Dependencies</a></li>
</ul>
</li>
<li id="no" title="Test Structure" expanded="false">Test Structure<ul>
<li><a href="test_structure_chapter.html">
Top of chapter
</a></li>
<li title="General"><a href="test_structure_chapter.html#general">General</a></li>
<li title="Skipping Test Cases"><a href="test_structure_chapter.html#skipping-test-cases">Skipping Test Cases</a></li>
<li title="Definition of Terms"><a href="test_structure_chapter.html#definition-of-terms">Definition of Terms</a></li>
</ul>
</li>
<li id="no" title="Examples and Templates" expanded="false">Examples and Templates<ul>
<li><a href="example_chapter.html">
Top of chapter
</a></li>
<li title="Test Suite Example"><a href="example_chapter.html#test-suite-example">Test Suite Example</a></li>
<li title="Test Suite Templates"><a href="example_chapter.html#test-suite-templates">Test Suite Templates</a></li>
</ul>
</li>
<li id="no" title="Running Tests and Analyzing Results" expanded="false">Running Tests and Analyzing Results<ul>
<li><a href="run_test_chapter.html">
Top of chapter
</a></li>
<li title="Using the Common Test Framework"><a href="run_test_chapter.html#using-the-common-test-framework">Using the Common Test Framework</a></li>
<li title="Automatic Compilation of Test Suites and Help Modules"><a href="run_test_chapter.html#automatic-compilation-of-test-suites-and-help-modules">Automatic Compilation of Test Suites and Help Modules</a></li>
<li title="Running Tests from the OS Command Line"><a href="run_test_chapter.html#running-tests-from-the-os-command-line">Running Tests from the OS Command Line</a></li>
<li title="Running Tests from the Erlang Shell or from an Erlang Program"><a href="run_test_chapter.html#running-tests-from-the-erlang-shell-or-from-an-erlang-program">Running Tests from the Erlang Shell or from an Erlang Program</a></li>
<li title="Test Case Group Execution"><a href="run_test_chapter.html#test-case-group-execution">Test Case Group Execution</a></li>
<li title="Running the Interactive Shell Mode"><a href="run_test_chapter.html#running-the-interactive-shell-mode">Running the Interactive Shell Mode</a></li>
<li title="Step-by-Step Execution of Test Cases with the Erlang Debugger"><a href="run_test_chapter.html#step-by-step-execution-of-test-cases-with-the-erlang-debugger">Step-by-Step Execution of Test Cases with the Erlang Debugger</a></li>
<li title="Test Specifications"><a href="run_test_chapter.html#test-specifications">Test Specifications</a></li>
<li title="Running Tests from the Web-Based GUI"><a href="run_test_chapter.html#running-tests-from-the-web-based-gui">Running Tests from the Web-Based GUI</a></li>
<li title="Log Files"><a href="run_test_chapter.html#log-files">Log Files</a></li>
<li title="HTML Style Sheets"><a href="run_test_chapter.html#html-style-sheets">HTML Style Sheets</a></li>
<li title="Repeating Tests"><a href="run_test_chapter.html#repeating-tests">Repeating Tests</a></li>
<li title="Silent Connections"><a href="run_test_chapter.html#silent-connections">Silent Connections</a></li>
</ul>
</li>
<li id="no" title="External Configuration Data" expanded="false">External Configuration Data<ul>
<li><a href="config_file_chapter.html">
Top of chapter
</a></li>
<li title="General"><a href="config_file_chapter.html#general">General</a></li>
<li title="Syntax"><a href="config_file_chapter.html#syntax">Syntax</a></li>
<li title="Requiring and Reading Configuration Data"><a href="config_file_chapter.html#requiring-and-reading-configuration-data">Requiring and Reading Configuration Data</a></li>
<li title="Using Configuration Variables Defined in Multiple Files"><a href="config_file_chapter.html#using-configuration-variables-defined-in-multiple-files">Using Configuration Variables Defined in Multiple Files</a></li>
<li title="Encrypted Configuration Files"><a href="config_file_chapter.html#encrypted-configuration-files">Encrypted Configuration Files</a></li>
<li title="Opening Connections Using Configuration Data"><a href="config_file_chapter.html#opening-connections-using-configuration-data">Opening Connections Using Configuration Data</a></li>
<li title="User-Specific Configuration Data Formats"><a href="config_file_chapter.html#user-specific-configuration-data-formats">User-Specific Configuration Data Formats</a></li>
<li title="Examples of Configuration Data Handling"><a href="config_file_chapter.html#examples-of-configuration-data-handling">Examples of Configuration Data Handling</a></li>
<li title="Example of User-Specific Configuration Handler"><a href="config_file_chapter.html#example-of-user-specific-configuration-handler">Example of User-Specific Configuration Handler</a></li>
</ul>
</li>
<li id="loadscrollpos" title="Code Coverage Analysis" expanded="true">Code Coverage Analysis<ul>
<li><a href="cover_chapter.html">
Top of chapter
</a></li>
<li title="General"><a href="cover_chapter.html#general">General</a></li>
<li title="Use"><a href="cover_chapter.html#use">Use</a></li>
<li title="Stopping the Cover Tool When Tests Are Completed"><a href="cover_chapter.html#stopping-the-cover-tool-when-tests-are-completed">Stopping the Cover Tool When Tests Are Completed</a></li>
<li title="The Cover Specification File"><a href="cover_chapter.html#the-cover-specification-file">The Cover Specification File</a></li>
<li title="Cross Cover Analysis"><a href="cover_chapter.html#cross-cover-analysis">Cross Cover Analysis</a></li>
<li title="Logging"><a href="cover_chapter.html#logging">Logging</a></li>
</ul>
</li>
<li id="no" title="Using Common Test for Large-Scale Testing" expanded="false">Using Common Test for Large-Scale Testing<ul>
<li><a href="ct_master_chapter.html">
Top of chapter
</a></li>
<li title="General"><a href="ct_master_chapter.html#general">General</a></li>
<li title="Use"><a href="ct_master_chapter.html#use">Use</a></li>
<li title="Test Specifications"><a href="ct_master_chapter.html#test-specifications">Test Specifications</a></li>
<li title="Automatic Startup of Test Target Nodes"><a href="ct_master_chapter.html#automatic-startup-of-test-target-nodes">Automatic Startup of Test Target Nodes</a></li>
</ul>
</li>
<li id="no" title="Event Handling" expanded="false">Event Handling<ul>
<li><a href="event_handler_chapter.html">
Top of chapter
</a></li>
<li title="General"><a href="event_handler_chapter.html#general">General</a></li>
<li title="Use"><a href="event_handler_chapter.html#use">Use</a></li>
</ul>
</li>
<li id="no" title="Dependencies between Test Cases and Suites" expanded="false">Dependencies between Test Cases and Suites<ul>
<li><a href="dependencies_chapter.html">
Top of chapter
</a></li>
<li title="General"><a href="dependencies_chapter.html#general">General</a></li>
<li title="Saving Configuration Data"><a href="dependencies_chapter.html#saving-configuration-data">Saving Configuration Data</a></li>
<li title="Sequences"><a href="dependencies_chapter.html#sequences">Sequences</a></li>
</ul>
</li>
<li id="no" title="Common Test Hooks" expanded="false">Common Test Hooks<ul>
<li><a href="ct_hooks_chapter.html">
Top of chapter
</a></li>
<li title="General"><a href="ct_hooks_chapter.html#general">General</a></li>
<li title="Installing a CTH"><a href="ct_hooks_chapter.html#installing-a-cth">Installing a CTH</a></li>
<li title="CTH Scope"><a href="ct_hooks_chapter.html#cth-scope">CTH Scope</a></li>
<li title="Manipulating Tests"><a href="ct_hooks_chapter.html#manipulating-tests">Manipulating Tests</a></li>
<li title="Synchronizing External User Applications with Common Test"><a href="ct_hooks_chapter.html#synchronizing-external-user-applications-with-common-test">Synchronizing External User Applications with Common Test</a></li>
<li title="Example CTH"><a href="ct_hooks_chapter.html#example-cth">Example CTH</a></li>
<li title="Built-In CTHs"><a href="ct_hooks_chapter.html#built-in-cths">Built-In CTHs</a></li>
</ul>
</li>
<li id="no" title="Some Thoughts about Testing" expanded="false">Some Thoughts about Testing<ul>
<li><a href="why_test_chapter.html">
Top of chapter
</a></li>
<li title="Goals"><a href="why_test_chapter.html#goals">Goals</a></li>
<li title="What to Test"><a href="why_test_chapter.html#what-to-test">What to Test</a></li>
</ul>
</li>
</ul>
</div></div>
<div id="content">
<div class="innertube">
<h1>10 Code Coverage Analysis</h1>
<h3>
<a name="cover"></a><span onMouseOver="document.getElementById('ghlink-general-idm281472276515640').style.visibility = 'visible';" onMouseOut="document.getElementById('ghlink-general-idm281472276515640').style.visibility = 'hidden';"><span id="ghlink-general-idm281472276515640" class="ghlink"><a href="https://github.com/erlang/otp/edit/maint/lib/common_test/doc/src/cover_chapter.xml#L33" title="Found an issue with the documentation? Fix it by clicking here!"><span class="pencil"></span></a></span><a class="title_link" name="general" href="#general">10.1
General</a></span>
</h3>
<p>Although <span class="code">Common Test</span> was created primarily for
black-box testing, nothing prevents it from working perfectly as
a white-box testing tool as well. This is especially true when
the application to test is written in Erlang. Then the test
ports are easily realized with Erlang function calls.</p>
<p>When white-box testing an Erlang application, it is useful to
be able to measure the code coverage of the test. <span class="code">Common Test</span>
provides simple access to the OTP Cover tool for this
purpose. <span class="code">Common Test</span> handles all necessary communication with
the Cover tool (starting, compiling, analysing, and so on).
The <span class="code">Common Test</span> user only needs to specify the extent of the
code coverage analysis.</p>
<h3><span onMouseOver="document.getElementById('ghlink-use-idm281472276510648').style.visibility = 'visible';" onMouseOut="document.getElementById('ghlink-use-idm281472276510648').style.visibility = 'hidden';"><span id="ghlink-use-idm281472276510648" class="ghlink"><a href="https://github.com/erlang/otp/edit/maint/lib/common_test/doc/src/cover_chapter.xml#L51" title="Found an issue with the documentation? Fix it by clicking here!"><span class="pencil"></span></a></span><a class="title_link" name="use" href="#use">10.2
Use</a></span></h3>
<p>To specify the modules to be included in the code coverage test,
provide a cover specification file. With this file you can point
out specific modules or specify directories containing modules to be
included in the analysis. You can also specify modules to be excluded
from the analysis.</p>
<p>If you are testing a distributed Erlang application, it is
likely that code you want included in the code coverage analysis
gets executed on another Erlang node than the one <span class="code">Common Test</span>
is running on. If so, you must specify these other nodes in the
cover specification file or add them dynamically to the code coverage
set of nodes. For details on the latter, see module
<span class="bold_code bc-19"><a href="ct_cover.html"><span class="code">ct_cover</span></a></span>.</p>
<p>In the cover specification file you can also specify your
required level of the code coverage analysis; <span class="code">details</span> or
<span class="code">overview</span>. In detailed mode, you get a coverage overview
page, showing per module and total coverage percentages.
You also get an HTML file printed for each module included in the
analysis showing exactly what parts of the code have been
executed during the test. In overview mode, only the code
coverage overview page is printed.</p>
<p>You can choose to export and import code coverage data between
tests. If you specify the name of an export file in the cover
specification file, <span class="code">Common Test</span> exports collected coverage
data to this file at the end of the test. You can similarly
specify previously exported data to be imported and
included in the analysis for a test (multiple import files can be specified).
This way, the total code coverage can be analyzed without necessarily
running all tests at once.</p>
<p>To activate the code coverage support, specify the name of the cover
specification file as you start <span class="code">Common Test</span>.
Do this by using flag <span class="code">-cover</span> with
<span class="bold_code bc-19"><a href="ct_run.html"><span class="code">ct_run</span></a></span>,
for example:</p>
<div class="example"><pre>
$ ct_run -dir $TESTOBJS/db -cover $TESTOBJS/db/config/db.coverspec</pre></div>
<p>You can also pass the cover specification file name in a
call to <span class="bold_code bc-15"><a href="ct.html#run_test-1"><span class="code">ct:run_test/1</span></a></span>,
by adding a <span class="code">{cover,CoverSpec}</span> tuple to argument <span class="code">Opts</span>.</p>
<p>You can also enable code coverage in your test specifications (see section
<span class="bold_code bc-15"><a href="run_test_chapter.html#test_specifications">Test Specifications</a></span>
in section Running Tests and Analyzing Results).</p>
<h3>
<a name="cover_stop"></a><span onMouseOver="document.getElementById('ghlink-stopping-the-cover-tool-when-tests-are-completed-idm281472276497128').style.visibility = 'visible';" onMouseOut="document.getElementById('ghlink-stopping-the-cover-tool-when-tests-are-completed-idm281472276497128').style.visibility = 'hidden';"><span id="ghlink-stopping-the-cover-tool-when-tests-are-completed-idm281472276497128" class="ghlink"><a href="https://github.com/erlang/otp/edit/maint/lib/common_test/doc/src/cover_chapter.xml#L101" title="Found an issue with the documentation? Fix it by clicking here!"><span class="pencil"></span></a></span><a class="title_link" name="stopping-the-cover-tool-when-tests-are-completed" href="#stopping-the-cover-tool-when-tests-are-completed">10.3
Stopping the Cover Tool When Tests Are Completed</a></span>
</h3>
<p>By default, the Cover tool is automatically stopped when the
tests are completed. This causes the original (non-cover
compiled) modules to be loaded back into the test node. If a
process at this point still runs old code of any of the
modules that are cover compiled, meaning that it has not done
any fully qualified function call after the cover compilation,
the process is killed. To avoid this, set the value of option
<span class="code">cover_stop</span> to <span class="code">false</span>. This means that the
modules stay cover compiled. Therefore, this is only recommended
if the Erlang nodes under test are terminated after the test is
completed, or if cover can be manually stopped.</p>
<p>The option can be set by using flag <span class="code">-cover_stop</span> with
<span class="code">ct_run</span>, by adding <span class="code">{cover_stop,true|false}</span> to argument
<span class="code">Opts</span> to
<span class="bold_code bc-15"><a href="ct.html#run_test-1"><span class="code">ct:run_test/1</span></a></span>,
or by adding a <span class="code">cover_stop</span> term in the test specification (see section
<span class="bold_code bc-15"><a href="run_test_chapter.html#test_specifications">Test Specifications</a></span>
in section Running Tests and Analyzing Results).</p>
<h3><span onMouseOver="document.getElementById('ghlink-the-cover-specification-file-idm281472276488968').style.visibility = 'visible';" onMouseOut="document.getElementById('ghlink-the-cover-specification-file-idm281472276488968').style.visibility = 'hidden';"><span id="ghlink-the-cover-specification-file-idm281472276488968" class="ghlink"><a href="https://github.com/erlang/otp/edit/maint/lib/common_test/doc/src/cover_chapter.xml#L126" title="Found an issue with the documentation? Fix it by clicking here!"><span class="pencil"></span></a></span><a class="title_link" name="the-cover-specification-file" href="#the-cover-specification-file">10.4
The Cover Specification File</a></span></h3>
<p>The following terms are allowed in a cover specification file:</p>
<div class="example"><pre>
%% List of Nodes on which cover will be active during test.
%% Nodes = [atom()]
{nodes, Nodes}.
%% Files with previously exported cover data to include in analysis.
%% CoverDataFiles = [string()]
{import, CoverDataFiles}.
%% Cover data file to export from this session.
%% CoverDataFile = string()
{export, CoverDataFile}.
%% Cover analysis level.
%% Level = details | overview
{level, Level}.
%% Directories to include in cover.
%% Dirs = [string()]
{incl_dirs, Dirs}.
%% Directories, including subdirectories, to include.
{incl_dirs_r, Dirs}.
%% Specific modules to include in cover.
%% Mods = [atom()]
{incl_mods, Mods}.
%% Directories to exclude in cover.
{excl_dirs, Dirs}.
%% Directories, including subdirectories, to exclude.
{excl_dirs_r, Dirs}.
%% Specific modules to exclude in cover.
{excl_mods, Mods}.
%% Cross cover compilation
%% Tag = atom(), an identifier for a test run
%% Mod = [atom()], modules to compile for accumulated analysis
{cross,[{Tag,Mods}]}.</pre></div>
<p>The terms <span class="code">incl_dirs_r</span> and <span class="code">excl_dirs_r</span> tell <span class="code">Common
Test</span> to search the specified directories recursively and include
or exclude any module found during the search. The terms
<span class="code">incl_dirs</span> and <span class="code">excl_dirs</span> result in a
non-recursive search for modules (that is, only modules found in
the specified directories are included or excluded).</p>
<div class="note">
<div class="label">Note</div>
<div class="content"><p><p>Directories containing Erlang modules to be included in a code
coverage test must exist in the code server path. Otherwise,
the Cover tool fails to recompile the modules. It is not sufficient to
specify these directories in the cover specification file for
<span class="code">Common Test</span>.</p></p></div>
</div>
<h3>
<a name="cross_cover"></a><span onMouseOver="document.getElementById('ghlink-cross-cover-analysis-idm281472276482616').style.visibility = 'visible';" onMouseOut="document.getElementById('ghlink-cross-cover-analysis-idm281472276482616').style.visibility = 'hidden';"><span id="ghlink-cross-cover-analysis-idm281472276482616" class="ghlink"><a href="https://github.com/erlang/otp/edit/maint/lib/common_test/doc/src/cover_chapter.xml#L185" title="Found an issue with the documentation? Fix it by clicking here!"><span class="pencil"></span></a></span><a class="title_link" name="cross-cover-analysis" href="#cross-cover-analysis">10.5
Cross Cover Analysis</a></span>
</h3>
<p>The cross cover mechanism allows cover analysis of modules
across multiple tests. It is useful if some code, for example, a
library module, is used by many different tests and the accumulated
cover result is desirable.</p>
<p>This can also be achieved in a more customized way by
using parameter <span class="code">export</span> in the cover specification and
analysing the result off line. However, the cross cover mechanism is a
built-in solution that also provides logging.</p>
<p>The mechanism is easiest explained by an example:</p>
<p>Assume that there are two systems, <span class="code">s1</span> and <span class="code">s2</span>,
that are tested in separate test runs. System <span class="code">s1</span> contains
a library module <span class="code">m1</span> tested by test run <span class="code">s1</span> and
is included in the cover specification of <span class="code">s1</span> as follows:</p>
<div class="example"><pre> s1.cover:
{incl_mods,[m1]}.</pre></div>
<p>When analysing code coverage, the result for <span class="code">m1</span> can be
seen in the cover log in the <span class="code">s1</span> test result.</p>
<p>Now, imagine that as <span class="code">m1</span> is a library module, it
is also often used by system <span class="code">s2</span>. Test run <span class="code">s2</span>
does not specifically test <span class="code">m1</span>, but it can still be
interesting to see which parts of <span class="code">m1</span> that are covered
by the <span class="code">s2</span> tests. To do this, <span class="code">m1</span> can be included also
in the cover specification of <span class="code">s2</span> as follows:</p>
<div class="example"><pre> s2.cover:
{incl_mods,[m1]}.</pre></div>
<p>This gives an entry for <span class="code">m1</span> also in the cover log
for test run <span class="code">s2</span>. The problem is that this only
reflects the coverage by <span class="code">s2</span> tests, not the accumulated
result over <span class="code">s1</span> and <span class="code">s2</span>. This is where the cross
cover mechanism comes in handy.</p>
<p>If instead the cover specification for <span class="code">s2</span> is like
the following:</p>
<div class="example"><pre> s2.cover:
{cross,[{s1,[m1]}]}.</pre></div>
<p>Then <span class="code">m1</span> is cover compiled in test run <span class="code">s2</span>,
but not shown in the coverage log. Instead, if
<span class="bold_code bc-15"><a href="ct_cover.html#cross_cover_analyse-2"><span class="code">ct_cover:cross_cover_analyse/2</span></a></span>
is called after both <span class="code">s1</span> and <span class="code">s2</span> test runs are completed,
the accumulated result for <span class="code">m1</span> is available in the cross cover
log for test run <span class="code">s1</span>.</p>
<p>The call to the analyze function must be as follows:</p>
<div class="example"><pre> ct_cover:cross_cover_analyse(Level, [{s1,S1LogDir},{s2,S2LogDir}]).</pre></div>
<p>Here, <span class="code">S1LogDir</span> and <span class="code">S2LogDir</span> are the directories
named <span class="code"><TestName>.logs</span> for each test respectively.</p>
<p>Notice the tags <span class="code">s1</span> and <span class="code">s2</span>, which are used in the
cover specification file and in the call to
<span class="code">ct_cover:cross_cover_analyse/2</span>. The purpose of these is only
to map the modules specified in the cover specification to the log
directory specified in the call to the analyze function. The tag name
has no meaning beyond this.</p>
<h3><span onMouseOver="document.getElementById('ghlink-logging-idm281472276454440').style.visibility = 'visible';" onMouseOut="document.getElementById('ghlink-logging-idm281472276454440').style.visibility = 'hidden';"><span id="ghlink-logging-idm281472276454440" class="ghlink"><a href="https://github.com/erlang/otp/edit/maint/lib/common_test/doc/src/cover_chapter.xml#L260" title="Found an issue with the documentation? Fix it by clicking here!"><span class="pencil"></span></a></span><a class="title_link" name="logging" href="#logging">10.6
Logging</a></span></h3>
<p>To view the result of a code coverage test, click the button
labeled "COVER LOG" in the top-level index page for the test run.</p>
<p>Before Erlang/OTP 17.1, if your test run consisted of
multiple tests, cover would be started and stopped for each test
within the test run. Separate logs would be available through the
"Coverage log" link on the test suite result pages. These links
are still available, but now they all point to the same page as
the button on the top-level index page. The log contains the
accumulated results for the complete test run. For details about
this change, see the release notes.</p>
<p>The button takes you to the code coverage overview page. If you
have successfully performed a detailed coverage analysis,
links to each individual module coverage page are found here.</p>
<p>If cross cover analysis is performed, and there are
accumulated coverage results for the current test, the link
"Coverdata collected over all tests" takes you to these
results.</p>
</div>
<div class="footer">
<hr>
<p>Copyright © 2003-2019 Ericsson AB. All Rights Reserved.</p>
</div>
</div>
</div>
<script type="text/javascript">window.__otpTopDocDir = '../../../../doc/js/';</script><script type="text/javascript" src="../../../../doc/js/highlight.js"></script>
</body>
</html>
