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

NAME

DESCRIPTION

EXPORTS

SEE ALSO