Apama 10.15.0 | Deploying and Managing Apama Applications | Correlator Utilities Reference | Generating code coverage information about EPL files | Creating code coverage reports
 
Creating code coverage reports
The epl_coverage tool takes one or more coverage files that have been output by the correlator's code coverage feature, merges them together to create a new combined .eplcoverage file (which can be used as input for the tool), and creates a CSV, XML and HTML report of the coverage of each source EPL file. The executable for this tool is located in the bin directory of the Apama installation.
Synopsis
To create code coverage reports, run the following command:
epl_coverage [ options ] file1.eplcoverage [ file2.eplcoverage ... ]
Example (for Windows):
epl_coverage --output c:\mycoverage --source "%APAMA_WORK%\projects\myproject"
--exclude "**/Apama/**/*.mon" *.eplcoverage
When you run this command with the –h option, the usage message for this command is shown.
Description
The --output argument specifies the directory into which the tool writes the output files. If not specified, the current directory is used.
The output includes the following files:
*merged.eplcoverage. A single file containing the combined EPL code coverage information from all the input files. This can be used as input to another invocation of the epl_coverage tool.
*coverage_summary.csv. A summary of the percentage of lines and instructions covered in each source file in the standard comma-separated values text format (in the operating system's local character encoding). This file may be useful for reviewing coverage information in a spreadsheet, or as input for an automated tool that records coverage information as part of a continuous integration build/test system. The file starts with a header line beginning with the hash (#) character which identifies the columns used in the rest of the file. It is recommended that any tool that reads this file should use the header line to identify the contents of each column; this is helpful in case columns are added or reordered in a later release.
*epl_coverage.xml. An XML representation of the combined code coverage information for all the input files. This file is written in a widely-used coverage file format that can be read by many third-party tools (the file format that was popularized by Cobertura, which is a code coverage utility for Java; see also https://cobertura.github.io/cobertura/).
*index.html (and associated .css and .html files). An HTML summary of coverage information, including annotated copies of the source files showing which executable lines are covered.
The HTML report needs to be able to locate the original EPL source files in order to show an annotated view of them. In most cases, the absolute path of each file is provided when the source file is injected and these files will be found automatically by the tool, provided they were not deleted since the injection. In some cases, however, the full path will not be available, for example, if a source file was injected as part of a CDP (correlator deployment package) file. In such cases, you should use the --source option to specify the directories containing the source files. It will recursively search these directories for file names that match the ones which were injected. You should avoid having multiple files with the same names in different directories, else the --source searching may find the wrong file.
You can apply filters that remove information about unwanted EPL files from all of the output files (including merged.eplcoverage). The --include and --exclude options can each be specified multiple times. They specify file patterns to include or exclude (for example **/foo/Bar*.mon). These patterns use the following characters:
*forward slashes (/) to indicate directory separators (on all platforms),
*a single asterisk (*) to indicate any number of non-directory separator characters,
*two asterisks (**) to indicate any number of characters potentially including directory separators, and
*a question mark (?) to indicate a single character.
If no --include argument is provided, the default is to include all file paths, except those that are removed by --exclude arguments. These patterns are matched against the absolute paths of the files that were injected into the correlator, and are not affected by the --source argument.
When the number of coverage input files is large, you can avoid an extremely long command line (which some operating systems do not support) by putting the coverage file list into a newline-delimited UTF-8 text file and providing the path to that file on the command line instead, prefixed with an @ symbol. For example:
epl_coverage "@c:\mypath\coverage_file_list.txt"
Options
The epl_coverage tool takes the following options:
Option
Description
-h | --help
Displays usage information.
-V | --version
Displays version information for the epl_coverage tool.
-o dir | --output dir
Specifies the directory into which the tool writes the output files. If not specified, the current directory is used.
-i pattern | --include pattern
Filtering option which specifies the EPL source files to include (defaults to **). This option can be specified multiple times.
-x pattern | --exclude pattern
Filtering option which specifies the EPL source files to exclude (for example, **/foo/Bar*.mon). This option can be specified multiple times.
-s dir | --source dir
HTML report option which specifies the search directories for locating any source files that were injected without specifying an absolute path. This option can be specified multiple times.
If supplied, this option is also used by the XML report for normalizing/fixing up paths to source files, allowing them to be located by third-party tools.
--title str
HTML report option which specifies the title to write into the HTML file.