1cover(3) Erlang Module Definition cover(3)
2
6 cover - A Coverage Analysis Tool for Erlang
7
9 The module cover provides a set of functions for coverage analysis of
10 Erlang programs, counting how many times each executable line of code
11 is executed when a program is run.
12 An executable line contains an Erlang expression such as a matching or
13 a function call. A blank line or a line containing a comment, function
14 head or pattern in a case- or receive statement is not executable.
15 Coverage analysis can be used to verify test cases, making sure all
17 relevant code is covered, and may also be helpful when looking for bot‐
18 tlenecks in the code.
19 Before any analysis can take place, the involved modules must be Cover
21 compiled. This means that some extra information is added to the module
22 before it is compiled into a binary which then is loaded. The source
23 file of the module is not affected and no .beam file is created.
24 Each time a function in a Cover compiled module is called, information
26 about the call is added to an internal database of Cover. The coverage
27 analysis is performed by examining the contents of the Cover database.
28 The output Answer is determined by two parameters, Level and Analysis.
29 * Level = module
31 Answer = {Module,Value}, where Module is the module name.
33 * Level = function
35 Answer = [{Function,Value}], one tuple for each function in the
37 module. A function is specified by its module name M, function name
38 F and arity A as a tuple {M,F,A}.
39 * Level = clause
41 Answer = [{Clause,Value}], one tuple for each clause in the module.
43 A clause is specified by its module name M, function name F, arity
44 A and position in the function definition C as a tuple {M,F,A,C}.
45 * Level = line
47 Answer = [{Line,Value}], one tuple for each executable line in the
49 module. A line is specified by its module name M and line number in
50 the source file N as a tuple {M,N}.
51 * Analysis = coverage
53 Value = {Cov,NotCov} where Cov is the number of executable lines in
55 the module, function, clause or line that have been executed at
56 least once and NotCov is the number of executable lines that have
57 not been executed.
58 * Analysis = calls
60 Value = Calls which is the number of times the module, function, or
62 clause has been called. In the case of line level analysis, Calls
63 is the number of times the line has been executed.
64 Distribution
66 Cover can be used in a distributed Erlang system. One of the nodes in
68 the system must then be selected as the main node, and all Cover com‐
69 mands must be executed from this node. The error reason not_main_node
70 is returned if an interface function is called on one of the remote
71 nodes.
72 Use cover:start/1 and cover:stop/1 to add or remove nodes. The same
74 Cover compiled code will be loaded on each node, and analysis will col‐
75 lect and sum up coverage data results from all nodes.
76 To only collect data from remote nodes without stopping cover on those
78 nodes, use cover:flush/1
79 If the connection to a remote node goes down, the main node will mark
81 it as lost. If the node comes back it will be added again. If the re‐
82 mote node was alive during the disconnected periode, cover data from
83 before and during this periode will be included in the analysis.
84
86 start() -> {ok, pid()} | {error, Reason}
87 Types:
89 Reason = {already_started, pid()} | term()
91 Starts the Cover server which owns the Cover internal database.
93 This function is called automatically by the other functions in
94 the module.
95 local_only() -> ok | {error, too_late}
97 Only support running Cover on the local node. This function must
99 be called before any modules have been compiled or any nodes
100 added. When running in this mode, modules will be Cover compiled
101 in a more efficient way, but the resulting code will only work
102 on the same node they were compiled on.
103 start(Nodes) ->
105 {ok, StartedNodes} |
106 {error, not_main_node} |
107 {error, local_only}
108 Types:
110 Nodes = node() | [node()]
112 StartedNodes = [node()]
113 Starts a Cover server on the each of given nodes, and loads all
115 cover compiled modules. This call will fail if cover:lo‐
116 cal_only/0 has been called.
117 compile(ModFiles) -> Result | [Result]
119 compile(ModFiles, Options) -> Result | [Result]
121 compile_module(ModFiles) -> Result | [Result]
123 compile_module(ModFiles, Options) -> Result | [Result]
125 Types:
127 ModFiles = mod_files()
129 Options = [option()]
130 Result = compile_result()
131 mod_files() = mod_file() | [mod_file()]
132 mod_file() = (Module :: module()) | (File :: file:filename())
133 option() =
134 {i, Dir :: file:filename()} |
135 {d, Macro :: atom()} |
136 {d, Macro :: atom(), Value :: term()} |
137 export_all
138 See compile:file/2.
139 compile_result() =
140 {ok, Module :: module()} |
141 {error, file:filename()} |
142 {error, not_main_node}
143 Compiles a module for Cover analysis. The module is given by its
145 module name Module or by its file name File. The .erl extension
146 may be omitted. If the module is located in another directory,
147 the path has to be specified.
148 Options is a list of compiler options which defaults to []. Only
150 options defining include file directories and macros are passed
151 to compile:file/2, everything else is ignored.
152 If the module is successfully Cover compiled, the function re‐
154 turns {ok, Module}. Otherwise the function returns {error,
155 File}. Errors and warnings are printed as they occur.
156 If a list of ModFiles is given as input, a list of Result will
158 be returned. The order of the returned list is undefined.
159 Note that the internal database is (re-)initiated during the
161 compilation, meaning any previously collected coverage data for
162 the module will be lost.
163 compile_directory() -> [Result] | {error, Reason}
165 compile_directory(Dir) -> [Result] | {error, Reason}
167 compile_directory(Dir, Options) -> [Result] | {error, Reason}
169 Types:
171 Dir = file:filename()
173 Options = [option()]
174 Reason = file_error()
175 Result = compile_result()
176 option() =
177 {i, Dir :: file:filename()} |
178 {d, Macro :: atom()} |
179 {d, Macro :: atom(), Value :: term()} |
180 export_all
181 See compile:file/2.
182 file_error() = eacces | enoent
183 compile_result() =
184 {ok, Module :: module()} |
185 {error, file:filename()} |
186 {error, not_main_node}
187 Compiles all modules (.erl files) in a directory Dir for Cover
189 analysis the same way as compile_module/1,2 and returns a list
190 with the return values.
191 Dir defaults to the current working directory.
193 The function returns {error, eacces} if the directory is not
195 readable or {error, enoent} if the directory does not exist.
196 compile_beam(ModFiles) -> Result | [Result]
198 Types:
200 ModFiles = beam_mod_files()
202 Result = compile_beam_result()
203 beam_mod_files() = beam_mod_file() | [beam_mod_file()]
204 beam_mod_file() =
205 (Module :: module()) | (BeamFile :: file:filename())
206 compile_beam_result() =
207 {ok, module()} |
208 {error, BeamFile :: file:filename()} |
209 {error, Reason :: compile_beam_rsn()}
210 compile_beam_rsn() =
211 non_existing |
212 {no_abstract_code, BeamFile :: file:filename()} |
213 {encrypted_abstract_code, BeamFile :: file:filename()} |
214 {already_cover_compiled, no_beam_found, module()} |
215 {{missing_backend, module()}, BeamFile :: file:filename()} |
216 {no_file_attribute, BeamFile :: file:filename()} |
217 not_main_node
218 Does the same as compile/1,2, but uses an existing .beam file as
220 base, that is, the module is not compiled from source. Thus com‐
221 pile_beam/1 is faster than compile/1,2.
222 Note that the existing .beam file must contain abstract code,
224 that is, it must have been compiled with the debug_info option.
225 If not, the error reason {no_abstract_code, BeamFile} is re‐
226 turned. If the abstract code is encrypted, and no key is avail‐
227 able for decrypting it, the error reason {encrypted_ab‐
228 stract_code, BeamFile} is returned.
229 If only the module name (that is, not the full name of the .beam
231 file) is given to this function, the .beam file is found by
232 calling code:which(Module). If no .beam file is found, the error
233 reason non_existing is returned. If the module is already cover
234 compiled with compile_beam/1, the .beam file will be picked from
235 the same location as the first time it was compiled. If the mod‐
236 ule is already cover compiled with compile/1,2, there is no way
237 to find the correct .beam file, so the error reason {al‐
238 ready_cover_compiled, no_beam_found, Module} is returned.
239 {error, BeamFile} is returned if the compiled code cannot be
241 loaded on the node.
242 If a list of ModFiles is given as input, a list of Result will
244 be returned. The order of the returned list is undefined.
245 compile_beam_directory() -> [Result] | {error, Reason}
247 compile_beam_directory(Dir) -> [Result] | {error, Reason}
249 Types:
251 Dir = file:filename()
253 Reason = file_error()
254 Result = compile_beam_result()
255 compile_beam_result() =
256 {ok, module()} |
257 {error, BeamFile :: file:filename()} |
258 {error, Reason :: compile_beam_rsn()}
259 compile_beam_rsn() =
260 non_existing |
261 {no_abstract_code, BeamFile :: file:filename()} |
262 {encrypted_abstract_code, BeamFile :: file:filename()} |
263 {already_cover_compiled, no_beam_found, module()} |
264 {{missing_backend, module()}, BeamFile :: file:filename()} |
265 {no_file_attribute, BeamFile :: file:filename()} |
266 not_main_node
267 file_error() = eacces | enoent
268 Compiles all modules (.beam files) in a directory Dir for Cover
270 analysis the same way as compile_beam/1 and returns a list with
271 the return values.
272 Dir defaults to the current working directory.
274 The function returns {error, eacces} if the directory is not
276 readable or {error, enoent} if the directory does not exist.
277 analyse() ->
279 {result, analyse_ok(), analyse_fail()} |
280 {error, not_main_node}
281 analyse(Analysis) ->
283 {result, analyse_ok(), analyse_fail()} |
284 {error, not_main_node}
285 analyse(Level) ->
287 {result, analyse_ok(), analyse_fail()} |
288 {error, not_main_node}
289 analyse(Modules) ->
291 OneResult |
292 {result, analyse_ok(), analyse_fail()} |
293 {error, not_main_node}
294 analyse(Analysis, Level) ->
296 {result, analyse_ok(), analyse_fail()} |
297 {error, not_main_node}
298 analyse(Modules, Analysis) ->
300 OneResult |
301 {result, analyse_ok(), analyse_fail()} |
302 {error, not_main_node}
303 analyse(Modules, Level) ->
305 OneResult |
306 {result, analyse_ok(), analyse_fail()} |
307 {error, not_main_node}
308 analyse(Modules, Analysis, Level) ->
310 OneResult |
311 {result, analyse_ok(), analyse_fail()} |
312 {error, not_main_node}
313 Types:
315 Analysis = analysis()
317 Level = level()
318 Modules = modules()
319 OneResult = one_result()
320 analysis() = coverage | calls
321 level() = line | clause | function | module
322 modules() = module() | [module()]
323 one_result() =
324 {ok, {Module :: module(), Value :: analyse_value()}} |
325 {ok, [{Item :: analyse_item(), Value :: analyse_value()}]} |
326 {error, {not_cover_compiled, module()}}
327 analyse_fail() = [{not_cover_compiled, module()}]
328 analyse_ok() =
329 [{Module :: module(), Value :: analyse_value()}] |
330 [{Item :: analyse_item(), Value :: analyse_value()}]
331 analyse_value() =
332 {Cov :: integer() >= 0, NotCov :: integer() >= 0} |
333 (Calls :: integer() >= 0)
334 analyse_item() =
335 (Line :: {M :: module(), N :: integer() >= 0}) |
336 (Clause ::
337 {M :: module(),
338 F :: atom(),
339 A :: arity(),
340 C :: integer() >= 0}) |
341 (Function :: {M :: module(), F :: atom(), A :: arity()})
342 Performs analysis of one or more Cover compiled modules, as
344 specified by Analysis and Level (see above), by examining the
345 contents of the internal database.
346 Analysis defaults to coverage and Level defaults to function.
348 If Modules is an atom (one module), the return will be OneRe‐
350 sult, else the return will be {result, Ok, Fail}.
351 If Modules is not given, all modules that have data in the cover
353 data table, are analysed. Note that this includes both cover
354 compiled modules and imported modules.
355 If a given module is not Cover compiled, this is indicated by
357 the error reason {not_cover_compiled, Module}.
358 analyse_to_file() ->
360 {result,
361 analyse_file_ok(),
362 analyse_file_fail()} |
363 {error, not_main_node}
364 analyse_to_file(Modules) ->
366 Answer |
367 {result,
368 analyse_file_ok(),
369 analyse_file_fail()} |
370 {error, not_main_node}
371 analyse_to_file(Options) ->
373 {result,
374 analyse_file_ok(),
375 analyse_file_fail()} |
376 {error, not_main_node}
377 analyse_to_file(Modules, Options) ->
379 Answer |
380 {result,
381 analyse_file_ok(),
382 analyse_file_fail()} |
383 {error, not_main_node}
384 Types:
386 Modules = modules()
388 Options = [analyse_option()]
389 Answer = analyse_answer()
390 modules() = module() | [module()]
391 analyse_option() =
392 html |
393 {outfile, OutFile :: file:filename()} |
394 {outdir, OutDir :: file:filename()}
395 analyse_answer() =
396 {ok, OutFile :: file:filename()} | {error, analyse_rsn()}
397 analyse_file_ok() = [OutFile :: file:filename()]
398 analyse_file_fail() = [analyse_rsn()]
399 analyse_rsn() =
400 {not_cover_compiled, Module :: module()} |
401 {file, File :: file:filename(), Reason :: term()} |
402 {no_source_code_found, Module :: module()}
403 Makes copies of the source file for the given modules, where it
405 for each executable line is specified how many times it has been
406 executed.
407 The output file OutFile defaults to Module.COVER.out, or Mod‐
409 ule.COVER.html if the option html was used.
410 If Modules is an atom (one module), the return will be Answer,
412 else the return will be a list, {result, Ok, Fail}.
413 If Modules is not given, all modules that have da ta in the
415 cover data table, are analysed. Note that this includes both
416 cover compiled modules and imported modules.
417 If a module is not Cover compiled, this is indicated by the er‐
419 ror reason {not_cover_compiled, Module}.
420 If the source file and/or the output file cannot be opened using
422 file:open/2, the function returns {error, {file, File, Reason}}
423 where File is the file name and Reason is the error reason.
424 If a module was cover compiled from the .beam file, that is, us‐
426 ing compile_beam/1 or compile_beam_directory/0,1,it is assumed
427 that the source code can be found in the same directory as the
428 .beam file, in ../src relative to that directory, or using the
429 source path in Module:module_info(compile). When using the lat‐
430 ter, two paths are examined: first the one constructed by join‐
431 ing ../src and the tail of the compiled path below a trailing
432 src component, then the compiled path itself. If no source code
433 is found, this is indicated by the error reason
434 {no_source_code_found, Module}.
435 async_analyse_to_file(Module) -> pid()
437 async_analyse_to_file(Module, OutFile) -> pid()
439 async_analyse_to_file(Module, Options) -> pid()
441 async_analyse_to_file(Module, OutFile, Options) -> pid()
443 Types:
445 Module = module()
447 OutFile = file:filename()
448 Options = [Option]
449 Option = html
450 analyse_rsn() =
451 {not_cover_compiled, Module :: module()} |
452 {file, File :: file:filename(), Reason :: term()} |
453 {no_source_code_found, Module :: module()}
454 This function works exactly the same way as analyse_to_file ex‐
456 cept that it is asynchronous instead of synchronous. The spawned
457 process will link with the caller when created. If an error of
458 type analyse_rsn() occurs while doing the cover analysis the
459 process will crash with the same error reason as analyse_to_file
460 would return.
461 modules() -> [module()] | {error, not_main_node}
463 Returns a list with all modules that are currently Cover com‐
465 piled.
466 imported_modules() -> [module()] | {error, not_main_node}
468 Returns a list with all modules for which there are imported
470 data.
471 imported() -> [file:filename()] | {error, not_main_node}
473 Returns a list with all imported files.
475 which_nodes() -> [node()]
477 Returns a list with all nodes that are part of the coverage
479 analysis. Note that the current node is not returned. This node
480 is always part of the analysis.
481 is_compiled(Module) ->
483 {file, File :: file:filename()} |
484 false |
485 {error, not_main_node}
486 Types:
488 Module = module()
490 Returns {file, File} if the module Module is Cover compiled, or
492 false otherwise. File is the .erl file used by compile_mod‐
493 ule/1,2 or the .beam file used by compile_beam/1.
494 reset() -> ok | {error, not_main_node}
496 reset(Module) ->
498 ok |
499 {error, not_main_node} |
500 {error, {not_cover_compiled, Module}}
501 Types:
503 Module = module()
505 Resets all coverage data for a Cover compiled module Module in
507 the Cover database on all nodes. If the argument is omitted, the
508 coverage data will be reset for all modules known by Cover.
509 If Module is not Cover compiled, the function returns {error,
511 {not_cover_compiled, Module}}.
512 export(File) -> ok | {error, Reason}
514 export(File, Module) -> ok | {error, Reason}
516 Types:
518 File = file:filename()
520 Module = module()
521 Reason = export_reason()
522 export_reason() =
523 {not_cover_compiled, Module :: module()} |
524 {cant_open_file,
525 ExportFile :: file:filename(),
526 FileReason :: term()} |
527 not_main_node
528 Exports the current coverage data for Module to the file Export‐
530 File. It is recommended to name the ExportFile with the exten‐
531 sion .coverdata, since other filenames cannot be read by the web
532 based interface to cover.
533 If Module is not given, data for all Cover compiled or earlier
535 imported modules is exported.
536 This function is useful if coverage data from different systems
538 is to be merged.
539 See also import/1.
541 import(ExportFile) -> ok | {error, Reason}
543 Types:
545 ExportFile = file:filename()
547 Reason =
548 {cant_open_file, ExportFile, FileReason :: term()} |
549 not_main_node
550 Imports coverage data from the file ExportFile created with ex‐
552 port/1,2. Any analysis performed after this will include the im‐
553 ported data.
554 Note that when compiling a module all existing coverage data is
556 removed, including imported data. If a module is already com‐
557 piled when data is imported, the imported data is added to the
558 existing coverage data.
559 Coverage data from several export files can be imported into one
561 system. The coverage data is then added up when analysing.
562 Coverage data for a module cannot be imported from the same file
564 twice unless the module is first reset or compiled. The check is
565 based on the filename, so you can easily fool the system by re‐
566 naming your export file.
567 See also export/1,2.
569 stop() -> ok | {error, not_main_node}
571 Stops the Cover server and unloads all Cover compiled code.
573 stop(Nodes) -> ok | {error, not_main_node}
575 Types:
577 Nodes = node() | [node()]
579 Stops the Cover server and unloads all Cover compiled code on
581 the given nodes. Data stored in the Cover database on the remote
582 nodes is fetched and stored on the main node.
583 flush(Nodes) -> ok | {error, not_main_node}
585 Types:
587 Nodes = node() | [node()]
589 Fetch data from the Cover database on the remote nodes and
591 stored on the main node.
592
594 code(3), compile(3)
595Ericsson AB tools 3.5.1 cover(3)