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.
file(ModuleName) -> Result
file(ModuleName, Options) -> Result
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:
../src
, relative to where the object file is
found (using the search path returned from
code:get_path/0)
.
../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}
Module
is prepared for coverage analysis.
compilation_failed
transformation_failed
{error,Reason}
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
.
|
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
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
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}
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
Module
is made before the code is
actually executed.
module_is_not_compiled_for_coverage_analysis
Module
is not prepared for coverage analysis.
Module = atom()
Tests if Module
is compiled for coverage analysis
and is currently loaded.
Modules = [Module]
Module = atom()
Returns a list of all modules available for coverage analysis.
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.
Evaluates most_called/1
for all modules returned by
all_covered/0
.
Discards all collected coverage data for Module
.
Discards all collected coverage data.
This module is obsolete. Use the coast
module instead.