cover(3erl)

1cover(3)                   Erlang Module Definition                   cover(3)
2
3
4

NAME

6       cover - A Coverage Analysis Tool for Erlang
7

DESCRIPTION

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
16       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
20       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
25       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
30         * Level = module
31
32           Answer = {Module,Value}, where Module is the module name.
33
34         * Level = function
35
36           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
40         * Level = clause
41
42           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
46         * Level = line
47
48           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
52         * Analysis = coverage
53
54           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
59         * Analysis = calls
60
61           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
65       Distribution
66
67       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
73       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
77       To only collect data from remote nodes without stopping cover on  those
78       nodes, use cover:flush/1
79
80       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
82       remote  node was alive during the disconnected periode, cover data from
83       before and during this periode will be included in the analysis.
84

EXPORTS

86       start() -> {ok,Pid} | {error,Reason}
87
88              Types:
89
90                 Pid = pid()
91                 Reason = {already_started,Pid}
92
93              Starts the Cover server which owns the Cover internal  database.
94              This  function is called automatically by the other functions in
95              the module.
96
97       local_only() -> ok | {error,too_late}
98
99              Only support running Cover on the local node. This function must
100              be  called  before  any  modules have been compiled or any nodes
101              added. When running in this mode, modules will be Cover compiled
102              in  a  more efficient way, but the resulting code will only work
103              on the same node they were compiled on.
104
105       start(Nodes)   ->   {ok,StartedNodes}   |    {error,not_main_node}    |
106       {error,local_only}
107
108              Types:
109
110                 Nodes = StartedNodes = [atom()]
111
112              Starts  a Cover server on the each of given nodes, and loads all
113              cover   compiled   modules.   This    call    will    fail    if
114              cover:local_only/0 has been called.
115
116       compile(ModFiles) -> Result | [Result]
117       compile(ModFiles, Options) -> Result | [Result]
118       compile_module(ModFiles) -> Result | [Result]
119       compile_module(ModFiles, Options) -> Result | [Result]
120
121              Types:
122
123                 ModFiles = ModFile | [ModFile]
124                 ModFile = Module | File
125                  Module = atom()
126                  File = string()
127                 Options = [Option]
128                  Option = {i,Dir} | {d,Macro} | {d,Macro,Value} | export_all
129                   See compile:file/2.
130                 Result = {ok,Module} | {error,File} | {error,not_main_node}
131
132              Compiles a module for Cover analysis. The module is given by its
133              module name Module or by its file name File. The .erl  extension
134              may  be  omitted. If the module is located in another directory,
135              the path has to be specified.
136
137              Options is a list of compiler options which defaults to []. Only
138              options  defining include file directories and macros are passed
139              to compile:file/2, everything else is ignored.
140
141              If the module  is  successfully  Cover  compiled,  the  function
142              returns    {ok,Module}.    Otherwise    the   function   returns
143              {error,File}. Errors and warnings are printed as they occur.
144
145              If a list of ModFiles is given as input, a list of  Result  will
146              be returned. The order of the returned list is undefined.
147
148              Note  that  the  internal  database is (re-)initiated during the
149              compilation, meaning any previously collected coverage data  for
150              the module will be lost.
151
152       compile_directory() -> [Result] | {error,Reason}
153       compile_directory(Dir) -> [Result] | {error,Reason}
154       compile_directory(Dir, Options) -> [Result] | {error,Reason}
155
156              Types:
157
158                 Dir = string()
159                 Options = [Option]
160                   See compile_module/1,2
161                 Result = {ok,Module} | {error,File} | {error,not_main_node}
162                   See compile_module/1,2
163                 Reason = eacces | enoent
164
165              Compiles  all  modules (.erl files) in a directory Dir for Cover
166              analysis the same way as compile_module/1,2 and returns  a  list
167              with the return values.
168
169              Dir defaults to the current working directory.
170
171              The  function  returns  {error,eacces}  if  the directory is not
172              readable or {error,enoent} if the directory does not exist.
173
174       compile_beam(ModFiles) -> Result | [Result]
175
176              Types:
177
178                 ModFiles = ModFile | [ModFile]
179                 ModFile = Module | BeamFile
180                  Module = atom()
181                  BeamFile = string()
182                 Result = {ok,Module} | {error,BeamFile} | {error,Reason}
183                  Reason  =  non_existing  |   {no_abstract_code,BeamFile}   |
184                 {encrypted_abstract_code,BeamFile}    |   {already_cover_com‐
185                 piled,no_beam_found,Module} | not_main_node
186
187              Does the same as compile/1,2, but uses an existing .beam file as
188              base,  i.e.  the  module  is not compiled from source. Thus com‐
189              pile_beam/1 is faster than compile/1,2.
190
191              Note that the existing .beam file must  contain  abstract  code,
192              i.e.  it  must have been compiled with the debug_info option. If
193              not, the error reason {no_abstract_code,BeamFile}  is  returned.
194              If  the  abstract code is encrypted, and no key is available for
195              decrypting it, the error  reason  {encrypted_abstract_code,Beam‐
196              File} is returned.
197
198              If  only  the  module  name (i.e. not the full name of the .beam
199              file) is given to this function, the  .beam  file  is  found  by
200              calling code:which(Module). If no .beam file is found, the error
201              reason non_existing is returned. If the module is already  cover
202              compiled with compile_beam/1, the .beam file will be picked from
203              the same location as the first time it was compiled. If the mod‐
204              ule  is already cover compiled with compile/1,2, there is no way
205              to  find  the  correct  .beam  file,   so   the   error   reason
206              {already_cover_compiled,no_beam_found,Module} is returned.
207
208              {error,BeamFile}  is  returned  if  the  compiled code cannot be
209              loaded on the node.
210
211              If a list of ModFiles is given as input, a list of  Result  will
212              be returned. The order of the returned list is undefined.
213
214       compile_beam_directory() -> [Result] | {error,Reason}
215       compile_beam_directory(Dir) -> [Result] | {error,Reason}
216
217              Types:
218
219                 Dir = string()
220                 Result = See compile_beam/1
221                 Reason = eacces | enoent
222
223              Compiles  all modules (.beam files) in a directory Dir for Cover
224              analysis the same way as compile_beam/1 and returns a list  with
225              the return values.
226
227              Dir defaults to the current working directory.
228
229              The  function  returns  {error,eacces}  if  the directory is not
230              readable or {error,enoent} if the directory does not exist.
231
232       analyse() -> {result,Ok,Fail} | {error,not_main_node}
233       analyse(Modules)     ->     OneResult     |     {result,Ok,Fail}      |
234       {error,not_main_node}
235       analyse(Analysis) -> {result,Ok,Fail} | {error,not_main_node}
236       analyse(Level) -> {result,Ok,Fail} | {error,not_main_node}
237       analyse(Modules,   Analysis)   ->   OneResult   |   {result,Ok,Fail}  |
238       {error,not_main_node}
239       analyse(Modules,   Level)   ->   OneResult   |    {result,Ok,Fail}    |
240       {error,not_main_node}
241       analyse(Analysis, Level) -> {result,Ok,Fail} | {error,not_main_node}
242       analyse(Modules,  Analysis,  Level)  ->  OneResult | {result,Ok,Fail} |
243       {error,not_main_node}
244
245              Types:
246
247                 Modules = Module | [Module]
248                 Module = atom()
249                 Analysis = coverage | calls
250                 Level = line | clause | function | module
251                 OneResult  =  {ok,{Module,Value}}  |  {ok,[{Item,Value}]}   |
252                 {error, Error}
253                  Item = Line | Clause | Function
254                  Line = {M,N}
255                  Clause = {M,F,A,C}
256                  Function = {M,F,A}
257                  M = F = atom()
258                  N = A = C = integer()
259                  Value = {Cov,NotCov} | Calls
260                  Cov = NotCov = Calls = integer()
261                  Error = {not_cover_compiled,Module}
262                 Ok = [{Module,Value}] | [{Item,Value}]
263                 Fail = [Error]
264
265              Performs  analysis  of  one  or  more Cover compiled modules, as
266              specified by Analysis and Level (see above),  by  examining  the
267              contents of the internal database.
268
269              Analysis defaults to coverage and Level defaults to function.
270
271              If  Modules  is  an atom (one module), the return will be OneRe‐
272              sult, else the return will be {result,Ok,Fail}.
273
274              If Modules is not given, all modules that have data in the cover
275              data  table,  are  analysed.  Note that this includes both cover
276              compiled modules and imported modules.
277
278              If a given module is not Cover compiled, this  is  indicated  by
279              the error reason {not_cover_compiled,Module}.
280
281       analyse_to_file() -> {result,Ok,Fail} | {error,not_main_node}
282       analyse_to_file(Modules)     ->    Answer    |    {result,Ok,Fail}    |
283       {error,not_main_node}
284       analyse_to_file(Options) -> {result,Ok,Fail} | {error,not_main_node}
285       analyse_to_file(Modules,Options)  ->  Answer   |   {result,Ok,Fail}   |
286       {error,not_main_node}
287
288              Types:
289
290                 Modules = Module | [Module]
291                 Module = atom()
292                 OutFile = OutDir = string()
293                 Options = [Option]
294                 Option = html | {outfile,OutFile} | {outdir,OutDir}
295                 Answer = {ok,OutFile} | {error,Error}
296                 Ok = [OutFile]
297                 Fail = [Error]
298                 Error  =  {not_cover_compiled,Module}  | {file,File,Reason} |
299                 {no_source_code_found,Module}
300                  File = string()
301                  Reason = term()
302
303              Makes copies of the source file for the given modules, where  it
304              for each executable line is specified how many times it has been
305              executed.
306
307              The output file OutFile defaults to  Module.COVER.out,  or  Mod‐
308              ule.COVER.html if the option html was used.
309
310              If  Modules  is an atom (one module), the return will be Answer,
311              else the return will be a list, {result,Ok,Fail}.
312
313              If Modules is not given, all modules that have data in the cover
314              data  table,  are  analysed.  Note that this includes both cover
315              compiled modules and imported modules.
316
317              If a module is not Cover compiled,  this  is  indicated  by  the
318              error reason {not_cover_compiled,Module}.
319
320              If the source file and/or the output file cannot be opened using
321              file:open/2,  the  function  returns  {error,{file,File,Reason}}
322              where File is the file name and Reason is the error reason.
323
324              If  a  module was cover compiled from the .beam file, i.e. using
325              compile_beam/1 or compile_beam_directory/0,1, it is assumed that
326              the  source code can be found in the same directory as the .beam
327              file, in ../src relative to that directory, or using the  source
328              path  in Module:module_info(compile). When using the latter, two
329              paths are examined: first the one constructed by joining  ../src
330              and  the  tail  of the compiled path below a trailing src compo‐
331              nent, then the compiled path itself. If no source code is found,
332              this is indicated by the error reason {no_source_code_found,Mod‐
333              ule}.
334
335       async_analyse_to_file(Module) ->
336       async_analyse_to_file(Module,Options) ->
337       async_analyse_to_file(Module, OutFile) ->
338       async_analyse_to_file(Module, OutFile, Options) -> pid()
339
340              Types:
341
342                 Module = atom()
343                 OutFile = string()
344                 Options = [Option]
345                 Option = html
346                 Error = {not_cover_compiled,Module}  |  {file,File,Reason}  |
347                 {no_source_code_found,Module} | not_main_node
348                  File = string()
349                  Reason = term()
350
351              This  function  works  exactly  the  same way as analyse_to_file
352              except that it  is  asynchronous  instead  of  synchronous.  The
353              spawned  process  will  link with the caller when created. If an
354              Error occurs while doing the cover  analysis  the  process  will
355              crash  with  the  same  error  reason  as  analyse_to_file would
356              return.
357
358       modules() -> [Module] | {error,not_main_node}
359
360              Types:
361
362                 Module = atom()
363
364              Returns a list with all modules that are  currently  Cover  com‐
365              piled.
366
367       imported_modules() -> [Module] | {error,not_main_node}
368
369              Types:
370
371                 Module = atom()
372
373              Returns  a  list  with  all modules for which there are imported
374              data.
375
376       imported() -> [File] | {error,not_main_node}
377
378              Types:
379
380                 File = string()
381
382              Returns a list with all imported files.
383
384       which_nodes() -> [Node] | {error,not_main_node}
385
386              Types:
387
388                 Node = atom()
389
390              Returns a list with all nodes that  are  part  of  the  coverage
391              analysis.  Note that the current node is not returned. This node
392              is always part of the analysis.
393
394       is_compiled(Module) -> {file,File} | false | {error,not_main_node}
395
396              Types:
397
398                 Module = atom()
399                 Beam = string()
400
401              Returns {file,File} if the module Module is Cover  compiled,  or
402              false  otherwise.  File  is  the  .erl  file  used by cover:com‐
403              pile_module/1,2 or the .beam file used by compile_beam/1.
404
405       reset(Module) ->
406       reset() -> ok | {error,not_main_node}
407
408              Types:
409
410                 Module = atom()
411
412              Resets all coverage data for a Cover compiled module  Module  in
413              the Cover database on all nodes. If the argument is omitted, the
414              coverage data will be reset for all modules known by Cover.
415
416              If  Module  is  not  Cover  compiled,   the   function   returns
417              {error,{not_cover_compiled,Module}}.
418
419       export(ExportFile)
420       export(ExportFile,Module) -> ok | {error,Reason}
421
422              Types:
423
424                 ExportFile = string()
425                 Module = atom()
426                 Reason         =         {not_cover_compiled,Module}        |
427                 {cant_open_file,ExportFile,Reason} | not_main_node
428
429              Exports the current coverage data for Module to the file Export‐
430              File.  It  is recommended to name the ExportFile with the exten‐
431              sion .coverdata, since other filenames cannot be read by the web
432              based interface to cover.
433
434              If  Module  is not given, data for all Cover compiled or earlier
435              imported modules is exported.
436
437              This function is useful if coverage data from different  systems
438              is to be merged.
439
440              See also cover:import/1
441
442       import(ExportFile) -> ok | {error,Reason}
443
444              Types:
445
446                 ExportFile = string()
447                 Reason = {cant_open_file,ExportFile,Reason} | not_main_node
448
449              Imports  coverage  data  from  the  file ExportFile created with
450              cover:export/1,2. Any analysis performed after this will include
451              the imported data.
452
453              Note  that when compiling a module all existing coverage data is
454              removed, including imported data. If a module  is  already  com‐
455              piled  when  data is imported, the imported data is added to the
456              existing coverage data.
457
458              Coverage data from several export files can be imported into one
459              system. The coverage data is then added up when analysing.
460
461              Coverage data for a module cannot be imported from the same file
462              twice unless the module is first reset or compiled. The check is
463              based  on  the  filename,  so  you can easily fool the system by
464              renaming your export file.
465
466              See also cover:export/1,2
467
468       stop() -> ok | {error,not_main_node}
469
470              Stops the Cover server and unloads all Cover compiled code.
471
472       stop(Nodes) -> ok | {error,not_main_node}
473
474              Types:
475
476                 Nodes = [atom()]
477
478              Stops the Cover server and unloads all Cover  compiled  code  on
479              the given nodes. Data stored in the Cover database on the remote
480              nodes is fetched and stored on the main node.
481
482       flush(Nodes) -> ok | {error,not_main_node}
483
484              Types:
485
486                 Nodes = [atom()]
487
488              Fetch data from the Cover  database  on  the  remote  nodes  and
489              stored on the main node.
490

NAME

DESCRIPTION

EXPORTS

SEE ALSO