Interpreting the HTML code coverage reports
Many lines in an EPL file do not contain any executable instructions, for example, comments, event definitions (except where they contain actions) and event expressions used to declare listeners. These lines are not marked up by the epl_coverage tool.
Lines that do contain executable code may have one or more executable elements (instructions), and the epl_coverage tool reports whether all or only some of those instructions have been executed. It may therefore be useful to split complex EPL constructs (such as multi-part if statements) over multiple lines as much as possible to make the output clearer as to what is covered. The exact details of how many instructions are on any given line is subject to change and therefore not documented, but information on partial coverage may sometimes be useful for identifying branching constructs where not all branches are covered.
Tip: | Every executable line that is not fully covered has the (!) string in the margin, which makes it possible to jump backwards and forwards between these lines using the Find functionality provided by most web browsers. |
The purpose of the coverage information is to provide insight into areas of user EPL that are being missed by test cases. Although it is worth aiming for a high percentage of lines and instructions being covered, it is not always possible to write tests that cover every line. However, as long as someone looks at the lines that were missed, there is no need to worry about having less than 100 percent coverage.
Similarly, the information about partial line coverage can often be useful, particularly for control constructs where it might indicate a missed branch in an if statement, or a while loop condition that always returns false. But it will not always be possible for users to get 100 percent coverage of every line, or (since the internal instructions used by EPL are not documented and may be changed at any time between versions) even to understand the reason why a line was not fully covered in some cases. Software AG support cannot provide explanations for why a given line of EPL was only partly covered.
Examples
The following code snippets illustrate some common cases.
The following line is partially but not fully covered if
a() returns
true every time this line is executed, since the instructions for the value of
b() are never checked in this case.
if a() or b() then {
The following line is only partially covered unless the test is run with
DEBUG logging enabled, since expressions in log statements are only evaluated if the log level is specified.
log "Hello world" at DEBUG;
Another common example is a stream query that uses an aggregate where nothing drops out of the window while the test is executed. For example, if less than 100 seconds pass after the first
E() event, the following line is only partially covered:
from a in all E() within 100.0 select com.apama.aggregates.sum(a.val): i
If the test does not have anything drop out of the within window, then you will get amber coverage, as no code to remove a value from the set being aggregated over (by sum) is being executed. This may happen if no events go through this query, or if only less than 20 seconds pass since the first event.
Any code in an
onunload action will never be covered at all, since it is only executed with
engine_delete, which also removes the coverage information.
