Justification of non-covered lines of code

You can enter justification statements in uncovered branches of a program so that they are considered as exceptions to the coverage rules. Thus, you identify in the source code the branches that are not covered and explain why they are not covered. The justification text must be declared in the attol cov_justify pragma line of the uncovered branch with one or multiple attributes.

Note: This feature applies to C and C++ programming languages only.

SYNTAX:

The justification pragma syntax is the following one: 

#pragama attol cov_justify (<lineOffset>, <type>, <what>, <justification text> ) [ (….) [ (….) …..]]

#pragama attol cov_justify is the pragma, and <lineOffset>, <type>, <what>, and <justification text> are the attributes.

Multiple statements can be specified in the same pragma line, with four attributes for each.

Each justification statement in a pragma line can cover only one branch of the code starting from a specified line of the source code.

Double-quotes can be added if the attribute includes commas.

The attributes are the following ones:
  • <type> attribute:

    This attribute is mandatory. It is used to determine what kind of code must be covered and how it must be covered.

    You can use the following <type>values:
    • proc: to justify that a function or a method is not covered.
    • return: to justify that a return statement is not covered.
    • branch or block: to justify that a block of code is not covered.
    • implicit: to justify that an implicit else statement is not covered.
    • logical, or for, or while: to justify that a loop is not covered (the loop number is given in the <what> attribute).
    • case: to justify that a case statement in a switch is not covered.
    • call: to justify that a function call or method call is not covered.
    • cond: to justify that a simple condition is not covered (the value true or false of the condition is given in the <what> attribute).
    • mcdc: to justify that a MC/DC is not covered (the description of the MD/DC is given in the <what> attribute).
  • <lineOffset> attribute:

    This attribute is optional.

    <lineOffset> attribute represents the number of lines between the pragma and the branch that must be justified. The value can be '+' if the branch is located after the pragma, or '-' if the branch is located before the pragma.

    If the <lineOffset> attribute is omitted <lineOffset> is considered as "0". It means that the justification applies to the closest type of branch (attribute <type>) from the pragma. If there are multiple branches at a same distance of the pragma, <lineOffset> helps distinguish between branches which branch should be justified.

    The <lineOffset> attribute specifies the line where the branch or condition to justify starts, it is relative to the pragma line (+/-), allowing to write this pragma line anywhere in the source file.
    Note: For the <block> value, the target block of lines is the block where the pragma is declared.
  • <what> attribute:

    The <what> values are used to help specify some of the branches to be justified. It depends on the attribute <type> values being used:

    • For block or branch <type>: The value is a string that describes the logical position of the block in the function, like ‘/then/else/seq’.
    • For logical, for and while <type>: The value is a list of ‘0’ (the loop is not executed), ‘1’ (the loop is executed only once) or ‘2+’ (the loop is executed more that once) separated by ‘ ;’, each of them could be prefixed with the block description string.
    • For cond <type>: The value is <expression>:<value>, <value> is true or false and <expression>.
    • For mcdc <type>: The value is a list of impossible combinations of the conditions separated by ‘;’, each value of the conditions are set with ‘T’ for true, ‘F’ for false, or ‘X’ if the condition is not evaluated. For example, if the MC/DC consists of 3 conditions, the <what> value could be the following one: “TFX;FXX”.

  • <justification text> is the reason why this part of code can't be covered by a test.

    <justification> is mandatory. It is presented as a free text in the coverage report that justifies a uncovered branch. It explains why it is not covered.

    Example: 

    #pragma attol cov_justify (call, ”my justification”) (block, ”myjustification”) (cond, ”:true”, ”my justification”) (for, ”0;1” ,”my justification”)

The following table lists the parameters that can be entered in the “<lineOffset>” and <what> attributes depending on the parameters indicated in the <type> attribute.

<type> attribute <lineOffset> attribute <what> attribute
proc For the <type>=proc, the pragma line declared above or inside the body, or just after the end of the body justifies the function/procedure entry.
return For <type>=return, the pragma line, must be just before or just after the return line.

branch/block For <type>=branch or block. It starts on the first { of that block or on the line of the unique statement.

The “branch to cover" attribute is used for a branch=<type> The branch string format is a list of :

/then/else/seq or /

It is used to indicate which branch to cover when there are multiple branches on the same line.

It can be empty is there are no ambiguity with the line number.
implicit For <type>=implicit, the pragma line must be just before the decision, or at the else place.

The “branch to cover" attribute is used for <type>= <branch>.

The branch string format is a list of: /then/else/seq or /

It is used to indicate which branch to cover when there are multiple branches on the same line.

It can be empty is there are no ambiguity with the line number.
logical/for/do/while For <type>=logical/for/while, the pragma line must be just before the ‘for' or ‘while’, or ‘do’ keyword.

This attribute is used for <type>=logical, the branch string format looks like ‘branch depth/instruction type/value’ with :

instruction type is:

/for or /while or /do

The value is /0 or /1 or /2+ to specify which part must be covered and justified. It is mandatory and can specify multiple parts if separated by ; e.g. “/0 ; /1”

Branch depth is a suite of strings like /then /else /for /while etc. clarifying the code depth of the branch where the loop has been found.

e.g. “/else/then/for/while/1” or “/while/1” or “/1”
case For <type>=case, the pragma line must be just before or just after the case line.

A case is both a block and a condition. If you enter a justification for a case <type>, it is the condition that is justified. You need to declare another pragma to justify the corresponding block.

Used for <type>=case, the string details the case expression (between ‘case’ and the ‘:’) to cover into the switch block.

It can be empty is there are no ambiguity with the line number.
call For <type>=call, the pragma line must be just before or just after the call line,

Used for type=call, the string details the called method name to cover.

It can be empty is there are no ambiguity with the line number.
cond For <type>=cond, the pragma line must be just before or just after the condition line.

“condition expression:value" is used for “<type>”=cond.The string indicates the condition expression to cover into the decision with the value to cover, true or false. The “condition expression” can be empty if there is no ambiguity with the line number but the value must always be specified after a colon at the end of the string.

Example: “var>5:false” or “:true”.

Multiple values can be justified, separated by ‘;’ such as “:true ; :false”
mcdc For <type>=mcdc, the pragma line must be just before or after the first condition line, or just before or after the last condition line.

“combinations" is used for type= mcdc. It is a series of patterns separated by a semi-colon ";". It cannot be empty.

Once the source code is built, you can see the results of the non-coverage justification statements in the Code Coverage report, on the Source page.

For more information about the code coverage reports, see About coverage reports.