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

NAME

DESCRIPTION

EXPORTS

SEE ALSO