<!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 -- Code Coverage Analysis</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/common_test-1.4.7.pdf">PDF</a><br><a href="../../../../doc/index.html">Top</a></small><p><strong>Common Test</strong><br><strong>User's Guide</strong><br><small>Version 1.4.7</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="no" title="Common Test Basics" expanded="false">Common Test Basics<ul> <li><a href="basics_chapter.html"> Top of chapter </a></li> <li title="Introduction"><a href="basics_chapter.html#id2257382">Introduction</a></li> <li title="Test Suite Organisation"><a href="basics_chapter.html#id2262699">Test Suite Organisation</a></li> <li title="Support Libraries"><a href="basics_chapter.html#id2262725">Support Libraries</a></li> <li title="Suites and Test Cases"><a href="basics_chapter.html#id2252225">Suites and Test Cases</a></li> <li title="External Interfaces"><a href="basics_chapter.html#id2252025">External Interfaces</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#id2259791">General information</a></li> <li title="Unix/Linux"><a href="install_chapter.html#id2259969">Unix/Linux</a></li> <li title="Windows"><a href="install_chapter.html#id2252127">Windows</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#id2263189">Support for test suite authors</a></li> <li title="Test suites"><a href="write_test_chapter.html#id2263446">Test suites</a></li> <li title="Init and end per suite"><a href="write_test_chapter.html#id2252033">Init and end per suite</a></li> <li title="Init and end per test case"><a href="write_test_chapter.html#id2263397">Init and end per test case</a></li> <li title="Test cases"><a href="write_test_chapter.html#id2252705">Test cases</a></li> <li title="Test case info function"><a href="write_test_chapter.html#id2252952">Test case info function</a></li> <li title="Test suite info function"><a href="write_test_chapter.html#id2264301">Test suite info function</a></li> <li title="Test case groups"><a href="write_test_chapter.html#id2264393">Test case groups</a></li> <li title="The parallel property and nested groups"><a href="write_test_chapter.html#id2264666">The parallel property and nested groups</a></li> <li title="Repeated groups"><a href="write_test_chapter.html#id2264711">Repeated groups</a></li> <li title="Shuffled test case order"><a href="write_test_chapter.html#id2264872">Shuffled test case order</a></li> <li title="Data and Private Directories"><a href="write_test_chapter.html#id2264941">Data and Private Directories</a></li> <li title="Execution environment"><a href="write_test_chapter.html#id2265020">Execution environment</a></li> <li title="Illegal dependencies"><a href="write_test_chapter.html#id2265070">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="Test structure"><a href="test_structure_chapter.html#id2265289">Test structure</a></li> <li title="Skipping test cases"><a href="test_structure_chapter.html#id2265306">Skipping test cases</a></li> <li title="Definition of terms"><a href="test_structure_chapter.html#id2265390">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#id2266177">Test suite example</a></li> <li title="Test suite templates"><a href="example_chapter.html#id2266264">Test suite templates</a></li> </ul> </li> <li id="no" title="Running Test Suites" expanded="false">Running Test Suites<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#id2266562">Using the Common Test Framework</a></li> <li title="Automatic compilation of test suites and help modules"><a href="run_test_chapter.html#id2266607">Automatic compilation of test suites and help modules</a></li> <li title="Running tests from the UNIX command line"><a href="run_test_chapter.html#id2266741">Running tests from the UNIX command line</a></li> <li title="Running tests from the Web based GUI"><a href="run_test_chapter.html#id2267056">Running tests from the Web based GUI</a></li> <li title="Running tests from the Erlang shell or from an Erlang program"><a href="run_test_chapter.html#id2267143">Running tests from the Erlang shell or from an Erlang program</a></li> <li title="Running the interactive shell mode"><a href="run_test_chapter.html#id2267199">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#id2267375">Step by step execution of test cases with the Erlang Debugger</a></li> <li title="Using test specifications"><a href="run_test_chapter.html#id2267476">Using test specifications</a></li> <li title="Log files"><a href="run_test_chapter.html#id2267715">Log files</a></li> <li title="HTML Style Sheets"><a href="run_test_chapter.html#id2267921">HTML Style Sheets</a></li> <li title="Repeating tests"><a href="run_test_chapter.html#id2268107">Repeating tests</a></li> <li title="Silent Connections"><a href="run_test_chapter.html#id2268354">Silent Connections</a></li> </ul> </li> <li id="no" title="Config Files" expanded="false">Config Files<ul> <li><a href="config_file_chapter.html"> Top of chapter </a></li> <li title="General"><a href="config_file_chapter.html#id2268593">General</a></li> <li title="Syntax"><a href="config_file_chapter.html#id2268633">Syntax</a></li> <li title="Requiring and reading configuration data"><a href="config_file_chapter.html#id2268657">Requiring and reading configuration data</a></li> <li title="Using configuration variables defined in multiple files"><a href="config_file_chapter.html#id2268807">Using configuration variables defined in multiple files</a></li> <li title="Encrypted configuration files"><a href="config_file_chapter.html#id2268839">Encrypted configuration files</a></li> <li title="Opening connections by using configuration data"><a href="config_file_chapter.html#id2268904">Opening connections by using configuration data</a></li> <li title="Examples"><a href="config_file_chapter.html#id2268977">Examples</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#id2269096">General</a></li> <li title="Usage"><a href="cover_chapter.html#id2269123">Usage</a></li> <li title="The cover specification file"><a href="cover_chapter.html#id2269250">The cover specification file</a></li> <li title="Logging"><a href="cover_chapter.html#id2269317">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#id2269392">General</a></li> <li title="Usage"><a href="ct_master_chapter.html#id2269436">Usage</a></li> <li title="Test Specifications"><a href="ct_master_chapter.html#id2269594">Test Specifications</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#id2269865">General</a></li> <li title="Usage"><a href="event_handler_chapter.html#id2269911">Usage</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#id2270845">General</a></li> <li title="Saving configuration data"><a href="dependencies_chapter.html#id2271007">Saving configuration data</a></li> <li title="Sequences"><a href="dependencies_chapter.html#id2271201">Sequences</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#id2271413">Goals</a></li> <li title="What to test?"><a href="why_test_chapter.html#id2271438">What to test?</a></li> </ul> </li> </ul> </div></div> <div id="content"> <div class="innertube"> <h1>8 Code Coverage Analysis</h1> <h3><a name="id2269096">8.1 General</a></h3> <a name="cover"></a> <p>Although Common Test was created primarly for the purpose of 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 by means of 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. Common Test provides simple access to the OTP Cover tool for this purpose. Common Test handles all necessary communication with the Cover tool (starting, compiling, analysing, etc). All the Common Test user needs to do is to specify the extent of the code coverage analysis.</p> <h3><a name="id2269123">8.2 Usage</a></h3> <p>To specify what modules should be included in the code coverage test, you provide a cover specification file. Using this file you can point out specific modules or specify directories that contain modules which should all be included in the analysis. You can also, in the same fashion, specify modules that should 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 an Erlang node other than the one Common Test is running on. If this is the case you need to specify these other nodes in the cover specification file or add them dynamically to the code coverage set of nodes. See the <span class="code">ct_cover</span> page in the reference manual for details on the latter.</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 you per module and total coverage percentages, as well as one HTML file printed for each module included in the analysis that shows exactly what parts of the code have been executed during the test. In overview mode, only the code coverage overview page gets printed.</p> <p><strong>Note:</strong> Currently, for Common Test to be able to print code coverage HTML files for the modules included in the analysis, the source code files of these modules must be located in the same directory as the corresponding <span class="code">.beam</span> files. This is a limitation that will be removed later.</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, Common Test will export collected coverage data to this file at the end of the test. You may similarly specify that previously exported data should be imported and included in the analysis for a test (you can specify multiple import files). This way it is possible to analyse total code coverage without necessarily running all tests at once. Note that even if you run separate tests in one test run, code coverage data will not be passed on from one test to another unless you specify an export file for Common Test to use for this purpose.</p> <p>To activate the code coverage support, you simply specify the name of the cover specification file as you start Common Test. This you do either by using the <span class="code">-cover</span> flag with <span class="code">run_test</span>. Example:</p> <p><span class="code">$ run_test -dir $TESTOBJS/db -cover $TESTOBJS/db/config/db.coverspec</span></p> <p>You may also pass the cover specification file name in a call to <span class="code">ct:run_test/1</span>, by adding a <span class="code">{cover,CoverSpec}</span> tuple to the <span class="code">Opts</span> argument. Also, you can of course enable code coverage in your test specifications (read more in the chapter about <span class="bold_code"><a href="run_test_chapter.html#test_specifications">using test specifications</a></span>).</p> <h3><a name="id2269250">8.3 The cover specification file</a></h3> <p>These are the terms 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}. </pre></div> <p>The <span class="code">incl_dirs_r</span> and <span class="code">excl_dirs_r</span> terms tell Common Test to search the given directories recursively and include or exclude any module found during the search. The <span class="code">incl_dirs</span> and <span class="code">excl_dirs</span> terms result in a non-recursive search for modules (i.e. only modules found in the given directories are included or excluded).</p> <p><strong>Note:</strong> Directories containing Erlang modules that are to be included in a code coverage test must exist in the code server path, or the cover tool will fail to recompile the modules. (It is not sufficient to specify these directories in the cover specification file for Common Test).</p> <h3><a name="id2269317">8.4 Logging</a></h3> <p>To view the result of a code coverage test, follow the "Coverage log" link on the test suite results page. This takes you to the code coverage overview page. If you have successfully performed a detailed coverage analysis, you find links to each individual module coverage page here.</p> </div> <div class="footer"> <hr> <p>Copyright © 2003-2010 Ericsson AB. All Rights Reserved.</p> </div> </div> </div></body> </html>