cover

MODULE

cover

MODULE SUMMARY

Coverage Analysis Tool

DESCRIPTION

The module cover provides a set of functions for coverage analysis of an Erlang program.

Coverage analysis consists of monitoring executing programs and observing how frequently each line of code is executed. Statistics gained from the monitoring process can be used for various purposes.

The module(s) must be prepared before the coverage analysis can be performed . Preparation implies transformation of source code, compilation and loading. Statistics will then be logged during execution. A counter for each statement in the module(s) is incremented every time the particular statement is evaluated. The program must therefore execute with reasonable test data before any coverage data can be obtained.

NOTE! This module is obsolete. Use the coast module instead.

EXPORTS

file(ModuleName) -> Result
file(ModuleName, Options) -> Result

Types:
ModuleName = atom() | string()
Options = [CompilerOptions]
CompilerOptions = {i, IncludeDir} | {d, Def}
Result = {module, Module} | compilation_failed | transformation_failed | {error, Reason}
Module = atom()

Prepares a module for coverage analysis. If ModuleName in file/1 is an atom, the source is searched for in the following order:

• In the current directory.
  
• In the directory ../src, relative to where the object file is found (using the search path returned from code:get_path/0).
  
• In the directory ../src/e_src, relative to where the object file is found (using the search path returned from code:get_path/0).
  

If ModuleName is a string, it is assumed to be the full path to the source file for the module. file/2 always treats ModuleName as a full path file name even if the input is an atom. The file extension .erl may be omitted.

When the form file/2 is used, the Options make it possible to pass several {i, IncludeDir} and/or {d, Def} tuples to the compiler. If file/1 is used with an atom as an argument, cover tries to reconstruct the include and define options from information found in the original object file.

The return value Result is one of the following:

{module, Module}

Compilation and loading succeeded. Module is prepared for coverage analysis.


compilation_failed

Compilation failed due to errors in the original code of the module.


transformation_failed

The original source code could not be transformed for coverage analysis.


{error,Reason}

Other errors. Reason indicates the type of error. The reasons are the same as returned from compile:file/2.


The function creates <File>.COVER.erl and <File>.beam in current directory. <File>.COVER.erl is a transformed version of the original <File>.erl, and <File>.beam contains the compiled <File>.COVER.erl.

<File>.COVER.erl and <File>.beam must not be renamed or moved until the coverage analysis is completed.

all_files(Dir)
all_files(Dir, Options)

all_files/1 evaluates file/1 for all .erl files found in the directory Dir.

all_files/2 evaluates file/2 for all .erl files found in the directory Dir.

quick_analyse(Module) -> Result

Types:
Module = atom()
Result = ok | module_is_not_compiled_for_coverage_analysis

Performs a quick analysis of the coverage data in Module. Prints out a summary of total coverage and function coverage for Module.

Example:

 
1> cover:quick_analyse(io_lib).
          
COVERAGE ANALYSIS (QUICK) FOR MODULE io_lib
*** 22 PERCENT *** of the statements are covered
NOT COVERED:85 COVERED: 24 TOTAL NUMBER OF STATEMENTS: 109
          
COVERAGE FOR FUNCTIONS IN MODULE io_lib
*** NOT CALLED *** 
collect_chars/3 scan/2 scan/1 write_char/1 print/1 write_string/1
indentation/2 char_list/1 nl/0 collect_line/2 collect_chars1/3 
write_char/3 write_string1/2 write_string/2 collect_line1/2 
scan/3 write/3 printable_list/1 print/4 reserved_word/1 fread/3 
fread/2 
*** 28 PERCENT COVERED *** 
write/2 
*** 43 PERCENT COVERED *** 
quote_atom/1 
*** 50 PERCENT COVERED *** 
write_tail/2 
*** 60 PERCENT COVERED *** 
quote_atom/2 
*** 75 PERCENT COVERED *** 
write_atom/1 
*** 80 PERCENT COVERED *** 
deep_char_list/2 
*** 100 PERCENT COVERED *** 
write/1 deep_char_list/1 format/2 fwrite/2 
 
ok
          

As shown, the printout contains the total coverage for Module in both number of statements and percentage. The coverage for functions is presented as a grouped and sorted list of increasing coverage, from 0 percent (NOT CALLED) to 100 percent.

quick_analyse_as_term(Module) -> AnalysisData

Types:
Module = atom()
AnalysisData = {Module, [ FuncCoverage ], NotCovered, Covered, PercentCovered} | module_is_not_compiled_for_coverage_analysis
FuncCoverage = {{Function, Arity}, NotCovered, Covered, PercentCovered}
NotCovered = Covered = PercentCovered = Arity = integer()
Function = atom()

Performs a quick analysis of the coverage data for Module and returns AnalysisData as an Erlang term. The FuncCoverage items are sorted in ascending order with PercentCovered as key.

Example:

4> cover:quick_analyse_as_term(io_lib).
{io_lib,[{{indentation,2},1,0,0},
{{scan,2},1,0,0},
{{write_string1,2},2,0,0},
{{collect_line,2},2,0,0},
{{fread,3},1,0,0},
{{print,1},1,0,0},
{{collect_chars,3},2,0,0},
...
{{write,2},13,5,28},
{{write_tail,2},2,2,50},
{{quote_atom,1},3,4,57},
{{quote_atom,2},2,3,60},
{{write_atom,1},1,3,75},
{{deep_char_list,2},1,4,80},
{{deep_char_list,1},0,1,100},
{{fwrite,2},0,1,100},
{{write,1},0,1,100},
{{format,2},0,1,100}],
83,
26,
24}
        

analyse(Module) -> Result

Types:
Module = atom()
Result = coverage_server_not_running| module_is_not_compiled_for_coverage_analysis

Performs detailed coverage analysis of all functions in Module. Output is stored in the file <File>.COVER.erl.out.

The output file contains the source code for those functions in Module which contain at least one statement which is never executed. The number of times a statement has been executed is included in the listing. The annotation **Not covered** indicates that the following statement has never been executed. The function returns:

coverage_server_not_running

An attempt to analyse Module is made before the code is actually executed.


module_is_not_compiled_for_coverage_analysis

Module is not prepared for coverage analysis.

check(Module) -> bool()

Types:
Module = atom()

Tests if Module is compiled for coverage analysis and is currently loaded.

all_covered() -> Modules

Types:
Modules = [Module]
Module = atom()

Returns a list of all modules available for coverage analysis.

most_called(Module) -> void()

Types:
Module = atom()

Prints out a sorted list of the functions in Module. The list is ordered by number of statement executions in the function. The output also includes percentage of total statement executions and cumulative percentage of statement executions.

The output from most_called/1 indicates the "cost" of evaluating a specific function.

most_called() -> void()

Evaluates most_called/1 for all modules returned by all_covered/0.

zero(Module) -> void()

Discards all collected coverage data for Module.

zero() -> void()

Discards all collected coverage data.

Note

This module is obsolete. Use the coast module instead.

AUTHORS

Joe Armstrong - support@erlang.ericsson.se
Kenneth Lundin - support@erlang.ericsson.se