Apama 10.15.3 | 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. These files are always written in the UTF-8 encoding.
Where possible, you should always specify the directories of the .mon source files using the --source option. The coverage tool uses the source directories to identify the canonical location of each EPL file, which may not be the same as the path it was injected from, especially when initializing a correlator from a correlator deployment directory. This also makes it easier for third-party coverage tools to recognize the paths from the XML report and allows the HTML report to show the source code even when the .mon file was injected from a test output directory that no longer exists.
By default, EPL files are assumed to be in the UTF-8 (or ASCII) encoding. If your EPL files are in a different encoding, you can provide the --source-encoding local option, in which case the EPL files are read in the local encoding instead. Files with a UTF-8 byte-order marker are read in UTF-8 in either case. This affects both locating the correct source file in the provided --source directories, and correctly rendering the source code into the HTML reports.
You can apply filters that remove information about unwanted EPL files (such as test .mon files) from all of the output files, or to restrict which parts of the source directories are to be searched. 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.
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 for the coverage data and source directories which specifies the EPL files to include (defaults to **). This option can be specified multiple times. It matches against absolute paths, so filters should either start with an absolute path or with a **/ wildcard.
-x pattern | --exclude pattern
Filtering option for the coverage data and source directories which specifies the EPL files to exclude (for example, **/tests/ or c:/foo/Bar.mon). This is useful for avoiding unwanted coverage information for EPL files used in testing but not part of the application itself. This option can be specified multiple times. It matches against absolute paths, so filters should either start with an absolute path or with a **/ wildcard.
-s dir | --source dir
Specifies one or more directories which will be recursively searched for .mon files and used to identify the canonical location of EPL files regardless of what directories they were injected from during testing.
--title str
HTML report option which specifies the title to write into the HTML file.
--source-encoding [local|utf-8]
The encoding to assume for EPL files. All files with a byte-order marker will use that encoding. All other files are assumed to be the given encoding (local or UTF-8). The default is utf-8.