cover(3)



cover(3erl)                Erlang Module Definition                cover(3erl)

NAME
       cover - A Coverage Analysis Tool for Erlang

DESCRIPTION
       The  module  cover provides a set of functions for coverage analysis of
       Erlang programs, counting how many times each executable line  of  code
       is executed when a program is run.
       An  executable line contains an Erlang expression such as a matching or
       a function call. A blank line or a line containing a comment,  function
       head or pattern in a case- or receive statement is not executable.

       Coverage  analysis  can  be  used to verify test cases, making sure all
       relevant code is covered, and may also be helpful when looking for bot-
       tlenecks in the code.

       Before  any analysis can take place, the involved modules must be Cover
       compiled. This means that some extra information is added to the module
       before  it  is  compiled into a binary which then is loaded. The source
       file of the module is not affected and no .beam file is created.

       Each time a function in a Cover compiled module is called,  information
       about  the call is added to an internal database of Cover. The coverage
       analysis is performed by examining the contents of the Cover  database.
       The output Answer is determined by two parameters, Level and Analysis.

         * Level = module

           Answer = {Module,Value}, where Module is the module name.

         * Level = function

           Answer  =  [{Function,Value}],  one  tuple for each function in the
           module. A function is specified by its module name M, function name
           F and arity A as a tuple {M,F,A}.

         * Level = clause

           Answer = [{Clause,Value}], one tuple for each clause in the module.
           A clause is specified by its module name M, function name F,  arity
           A and position in the function definition C as a tuple {M,F,A,C}.

         * Level = line

           Answer  = [{Line,Value}], one tuple for each executable line in the
           module. A line is specified by its module name M and line number in
           the source file N as a tuple {M,N}.

         * Analysis = coverage

           Value = {Cov,NotCov} where Cov is the number of executable lines in
           the module, function, clause or line that  have  been  executed  at
           least  once  and NotCov is the number of executable lines that have
           not been executed.

         * Analysis = calls

           Value = Calls which is the number of times the module, function, or
           clause  has  been called. In the case of line level analysis, Calls
           is the number of times the line has been executed.

       Distribution

       Cover can be used in a distributed Erlang system. One of the  nodes  in
       the  system  must then be selected as the main node, and all Cover com-
       mands must be executed from this node. The error  reason  not_main_node
       is  returned  if  an  interface function is called on one of the remote
       nodes.

       Use cover:start/1 and cover:stop/1 to add or  remove  nodes.  The  same
       Cover compiled code will be loaded on each node, and analysis will col-
       lect and sum up coverage data results from all nodes.

       To only collect data from remote nodes without stopping cover on  those
       nodes, use cover:flush/1

       If  the  connection to a remote node goes down, the main node will mark
       it as lost. If the node comes back it will be added again. If  the  re-
       mote  node  was  alive during the disconnected periode, cover data from
       before and during this periode will be included in the analysis.

EXPORTS
       start() -> {ok,Pid} | {error,Reason}

              Types:

                 Pid = pid()
                 Reason = {already_started,Pid}

              Starts the Cover server which owns the Cover internal  database.
              This  function is called automatically by the other functions in
              the module.

       local_only() -> ok | {error,too_late}

              Only support running Cover on the local node. This function must
              be  called  before  any  modules have been compiled or any nodes
              added. When running in this mode, modules will be Cover compiled
              in  a  more efficient way, but the resulting code will only work
              on the same node they were compiled on.

       start(Nodes) -> {ok,StartedNodes} | {error,not_main_node} |  {error,lo-
       cal_only}

              Types:

                 Nodes = StartedNodes = [atom()]

              Starts  a Cover server on the each of given nodes, and loads all
              cover  compiled  modules.  This  call  will  fail  if  cover:lo-
              cal_only/0 has been called.

       compile(ModFiles) -> Result | [Result]
       compile(ModFiles, Options) -> Result | [Result]
       compile_module(ModFiles) -> Result | [Result]
       compile_module(ModFiles, Options) -> Result | [Result]

              Types:

                 ModFiles = ModFile | [ModFile]
                 ModFile = Module | File
                  Module = atom()
                  File = string()
                 Options = [Option]
                  Option = {i,Dir} | {d,Macro} | {d,Macro,Value} | export_all
                   See compile:file/2.
                 Result = {ok,Module} | {error,File} | {error,not_main_node}

              Compiles a module for Cover analysis. The module is given by its
              module name Module or by its file name File. The .erl  extension
              may  be  omitted. If the module is located in another directory,
              the path has to be specified.

              Options is a list of compiler options which defaults to []. Only
              options  defining include file directories and macros are passed
              to compile:file/2, everything else is ignored.

              If the module is successfully Cover compiled, the  function  re-
              turns  {ok,Module}. Otherwise the function returns {error,File}.
              Errors and warnings are printed as they occur.

              If a list of ModFiles is given as input, a list of  Result  will
              be returned. The order of the returned list is undefined.

              Note  that  the  internal  database is (re-)initiated during the
              compilation, meaning any previously collected coverage data  for
              the module will be lost.

       compile_directory() -> [Result] | {error,Reason}
       compile_directory(Dir) -> [Result] | {error,Reason}
       compile_directory(Dir, Options) -> [Result] | {error,Reason}

              Types:

                 Dir = string()
                 Options = [Option]
                   See compile_module/1,2
                 Result = {ok,Module} | {error,File} | {error,not_main_node}
                   See compile_module/1,2
                 Reason = eacces | enoent

              Compiles  all  modules (.erl files) in a directory Dir for Cover
              analysis the same way as compile_module/1,2 and returns  a  list
              with the return values.

              Dir defaults to the current working directory.

              The  function  returns  {error,eacces}  if  the directory is not
              readable or {error,enoent} if the directory does not exist.

       compile_beam(ModFiles) -> Result | [Result]

              Types:

                 ModFiles = ModFile | [ModFile]
                 ModFile = Module | BeamFile
                  Module = atom()
                  BeamFile = string()
                 Result = {ok,Module} | {error,BeamFile} | {error,Reason}
                  Reason = non_existing | {no_abstract_code,BeamFile}  |  {en-
                 crypted_abstract_code,BeamFile}     |     {already_cover_com-
                 piled,no_beam_found,Module} | not_main_node

              Does the same as compile/1,2, but uses an existing .beam file as
              base,  i.e.  the  module  is not compiled from source. Thus com-
              pile_beam/1 is faster than compile/1,2.

              Note that the existing .beam file must  contain  abstract  code,
              i.e.  it  must have been compiled with the debug_info option. If
              not, the error reason {no_abstract_code,BeamFile}  is  returned.
              If  the  abstract code is encrypted, and no key is available for
              decrypting it, the error  reason  {encrypted_abstract_code,Beam-
              File} is returned.

              If  only  the  module  name (i.e. not the full name of the .beam
              file) is given to this function, the  .beam  file  is  found  by
              calling code:which(Module). If no .beam file is found, the error
              reason non_existing is returned. If the module is already  cover
              compiled with compile_beam/1, the .beam file will be picked from
              the same location as the first time it was compiled. If the mod-
              ule  is already cover compiled with compile/1,2, there is no way
              to find the  correct  .beam  file,  so  the  error  reason  {al-
              ready_cover_compiled,no_beam_found,Module} is returned.

              {error,BeamFile}  is  returned  if  the  compiled code cannot be
              loaded on the node.

              If a list of ModFiles is given as input, a list of  Result  will
              be returned. The order of the returned list is undefined.

       compile_beam_directory() -> [Result] | {error,Reason}
       compile_beam_directory(Dir) -> [Result] | {error,Reason}

              Types:

                 Dir = string()
                 Result = See compile_beam/1
                 Reason = eacces | enoent

              Compiles  all modules (.beam files) in a directory Dir for Cover
              analysis the same way as compile_beam/1 and returns a list  with
              the return values.

              Dir defaults to the current working directory.

              The  function  returns  {error,eacces}  if  the directory is not
              readable or {error,enoent} if the directory does not exist.

       analyse() -> {result,Ok,Fail} | {error,not_main_node}
       analyse(Modules)   ->   OneResult    |    {result,Ok,Fail}    |    {er-
       ror,not_main_node}
       analyse(Analysis) -> {result,Ok,Fail} | {error,not_main_node}
       analyse(Level) -> {result,Ok,Fail} | {error,not_main_node}
       analyse(Modules,  Analysis)  ->  OneResult  |  {result,Ok,Fail}  | {er-
       ror,not_main_node}
       analyse(Modules,  Level)  ->  OneResult  |  {result,Ok,Fail}   |   {er-
       ror,not_main_node}
       analyse(Analysis, Level) -> {result,Ok,Fail} | {error,not_main_node}
       analyse(Modules,  Analysis,  Level)  ->  OneResult | {result,Ok,Fail} |
       {error,not_main_node}

              Types:

                 Modules = Module | [Module]
                 Module = atom()
                 Analysis = coverage | calls
                 Level = line | clause | function | module
                 OneResult = {ok,{Module,Value}} | {ok,[{Item,Value}]} |  {er-
                 ror, Error}
                  Item = Line | Clause | Function
                  Line = {M,N}
                  Clause = {M,F,A,C}
                  Function = {M,F,A}
                  M = F = atom()
                  N = A = C = integer()
                  Value = {Cov,NotCov} | Calls
                  Cov = NotCov = Calls = integer()
                  Error = {not_cover_compiled,Module}
                 Ok = [{Module,Value}] | [{Item,Value}]
                 Fail = [Error]

              Performs  analysis  of  one  or  more Cover compiled modules, as
              specified by Analysis and Level (see above),  by  examining  the
              contents of the internal database.

              Analysis defaults to coverage and Level defaults to function.

              If  Modules  is  an atom (one module), the return will be OneRe-
              sult, else the return will be {result,Ok,Fail}.

              If Modules is not given, all modules that have data in the cover
              data  table,  are  analysed.  Note that this includes both cover
              compiled modules and imported modules.

              If a given module is not Cover compiled, this  is  indicated  by
              the error reason {not_cover_compiled,Module}.

       analyse_to_file() -> {result,Ok,Fail} | {error,not_main_node}
       analyse_to_file(Modules)   ->   Answer   |   {result,Ok,Fail}   |  {er-
       ror,not_main_node}
       analyse_to_file(Options) -> {result,Ok,Fail} | {error,not_main_node}
       analyse_to_file(Modules,Options) -> Answer |  {result,Ok,Fail}  |  {er-
       ror,not_main_node}

              Types:

                 Modules = Module | [Module]
                 Module = atom()
                 OutFile = OutDir = string()
                 Options = [Option]
                 Option = html | {outfile,OutFile} | {outdir,OutDir}
                 Answer = {ok,OutFile} | {error,Error}
                 Ok = [OutFile]
                 Fail = [Error]
                 Error  =  {not_cover_compiled,Module}  | {file,File,Reason} |
                 {no_source_code_found,Module}
                  File = string()
                  Reason = term()

              Makes copies of the source file for the given modules, where  it
              for each executable line is specified how many times it has been
              executed.

              The output file OutFile defaults to  Module.COVER.out,  or  Mod-
              ule.COVER.html if the option html was used.

              If  Modules  is an atom (one module), the return will be Answer,
              else the return will be a list, {result,Ok,Fail}.

              If Modules is not given, all modules that have data in the cover
              data  table,  are  analysed.  Note that this includes both cover
              compiled modules and imported modules.

              If a module is not Cover compiled, this is indicated by the  er-
              ror reason {not_cover_compiled,Module}.

              If the source file and/or the output file cannot be opened using
              file:open/2,  the  function  returns  {error,{file,File,Reason}}
              where File is the file name and Reason is the error reason.

              If  a  module was cover compiled from the .beam file, i.e. using
              compile_beam/1 or compile_beam_directory/0,1, it is assumed that
              the  source code can be found in the same directory as the .beam
              file, in ../src relative to that directory, or using the  source
              path  in Module:module_info(compile). When using the latter, two
              paths are examined: first the one constructed by joining  ../src
              and  the  tail  of the compiled path below a trailing src compo-
              nent, then the compiled path itself. If no source code is found,
              this is indicated by the error reason {no_source_code_found,Mod-
              ule}.

       async_analyse_to_file(Module) ->
       async_analyse_to_file(Module,Options) ->
       async_analyse_to_file(Module, OutFile) ->
       async_analyse_to_file(Module, OutFile, Options) -> pid()

              Types:

                 Module = atom()
                 OutFile = string()
                 Options = [Option]
                 Option = html
                 Error = {not_cover_compiled,Module}  |  {file,File,Reason}  |
                 {no_source_code_found,Module} | not_main_node
                  File = string()
                  Reason = term()

              This  function works exactly the same way as analyse_to_file ex-
              cept that it is asynchronous instead of synchronous. The spawned
              process  will link with the caller when created. If an Error oc-
              curs while doing the cover analysis the process will crash  with
              the same error reason as analyse_to_file would return.

       modules() -> [Module] | {error,not_main_node}

              Types:

                 Module = atom()

              Returns  a  list  with all modules that are currently Cover com-
              piled.

       imported_modules() -> [Module] | {error,not_main_node}

              Types:

                 Module = atom()

              Returns a list with all modules for  which  there  are  imported
              data.

       imported() -> [File] | {error,not_main_node}

              Types:

                 File = string()

              Returns a list with all imported files.

       which_nodes() -> [Node] | {error,not_main_node}

              Types:

                 Node = atom()

              Returns  a  list  with  all  nodes that are part of the coverage
              analysis. Note that the current node is not returned. This  node
              is always part of the analysis.

       is_compiled(Module) -> {file,File} | false | {error,not_main_node}

              Types:

                 Module = atom()
                 Beam = string()

              Returns  {file,File}  if the module Module is Cover compiled, or
              false otherwise. File  is  the  .erl  file  used  by  cover:com-
              pile_module/1,2 or the .beam file used by compile_beam/1.

       reset(Module) ->
       reset() -> ok | {error,not_main_node}

              Types:

                 Module = atom()

              Resets  all  coverage data for a Cover compiled module Module in
              the Cover database on all nodes. If the argument is omitted, the
              coverage data will be reset for all modules known by Cover.

              If  Module  is  not  Cover  compiled,  the function returns {er-
              ror,{not_cover_compiled,Module}}.

       export(ExportFile)
       export(ExportFile,Module) -> ok | {error,Reason}

              Types:

                 ExportFile = string()
                 Module = atom()
                 Reason =  {not_cover_compiled,Module}  |  {cant_open_file,Ex-
                 portFile,Reason} | not_main_node

              Exports the current coverage data for Module to the file Export-
              File. It is recommended to name the ExportFile with  the  exten-
              sion .coverdata, since other filenames cannot be read by the web
              based interface to cover.

              If Module is not given, data for all Cover compiled  or  earlier
              imported modules is exported.

              This  function is useful if coverage data from different systems
              is to be merged.

              See also cover:import/1

       import(ExportFile) -> ok | {error,Reason}

              Types:

                 ExportFile = string()
                 Reason = {cant_open_file,ExportFile,Reason} | not_main_node

              Imports coverage data from  the  file  ExportFile  created  with
              cover:export/1,2. Any analysis performed after this will include
              the imported data.

              Note that when compiling a module all existing coverage data  is
              removed,  including  imported  data. If a module is already com-
              piled when data is imported, the imported data is added  to  the
              existing coverage data.

              Coverage data from several export files can be imported into one
              system. The coverage data is then added up when analysing.

              Coverage data for a module cannot be imported from the same file
              twice unless the module is first reset or compiled. The check is
              based on the filename, so you can easily fool the system by  re-
              naming your export file.

              See also cover:export/1,2

       stop() -> ok | {error,not_main_node}

              Stops the Cover server and unloads all Cover compiled code.

       stop(Nodes) -> ok | {error,not_main_node}

              Types:

                 Nodes = [atom()]

              Stops  the  Cover  server and unloads all Cover compiled code on
              the given nodes. Data stored in the Cover database on the remote
              nodes is fetched and stored on the main node.

       flush(Nodes) -> ok | {error,not_main_node}

              Types:

                 Nodes = [atom()]

              Fetch  data  from  the  Cover  database  on the remote nodes and
              stored on the main node.

SEE ALSO
       code(3erl), compile(3erl)

Ericsson AB                        tools 3.4                       cover(3erl)

Man(1) output converted with man2html
list of all man pages