Difference between revisions of "Branch Coverage Cheat Sheet"

From OC Systems Wiki!
Jump to: navigation, search
m (If Statements)
m (Markers/Colors)
 
Line 9: Line 9:
 
=== Markers/Colors ===
 
=== Markers/Colors ===
  
A source line with no line count (no color / no marker) is either a line with no object code and can be ignored of it is part of a subprogram for which coverage was not requested.
+
A source line with no line count (no color / no marker) is either a line with no object code and can be ignored or it is part of a subprogram for which coverage was not requested.
  
 
[[file:BCCS_1.jpeg|1200px]]
 
[[file:BCCS_1.jpeg|1200px]]

Latest revision as of 22:22, 16 July 2018

Branch Coverage Cheat Sheet

This document provides information about interpreting the Branch Coverage Reports produced from data collected by the predefined probes coverage,ual (and brcov.ual) and the tool abrmerge. There are sections providing general guidance and sections for target-specific and compiler-specific guidance.

General Guidance

This section provides guidance applicable to all target ins compilers.

Markers/Colors

A source line with no line count (no color / no marker) is either a line with no object code and can be ignored or it is part of a subprogram for which coverage was not requested.

BCCS 1.jpeg

A source line with a positive line count (no marker / green color) is OK (has been executed).

BCCS 2.jpeg

A source line with a zero line count (+ marker / yellow color) needs attention (has not been executed).

BCCS 3.jpeg

A source line with a zero line count (* marker / red color) needs attention (has not been instrumented).

BCCS 4.jpeg

A branch with positive count (green color) is OK (has been executed).

BCCS 5.jpeg

A branch with a zero count (+ marker / yellow color) need attention (has not been executed).

BCCS 6.jpeg

A branch with a zero count (+ marker / red color) need attention (has not been instrumented).

BCCS 7.jpeg

Multiple Branches Per Line

Lines with multiple branches may be easier to work with if the source code is modified to put one decision per line.

BCCS 8.jpeg

versus

BCCS 9.jpeg

C/x86

This section provides guidance for GNU C compiler (gcc) on x86.

Functions

At the end of a function the closing brace may have a line count of 0 due to a patching problem. This is fixed in ap.4.4.63/7. Otherwise, the 0 line count can be ignored.

Loops

In a for loop, the index bounds test is completed at the top of the loop. If the branch associated with the for loop in not taken, then the body of the loop will not have been executed (line counts should be 0).

BCCS 10.jpeg

In a for loop, the index bounds test is completed at the top of the loop. The line count of the for loop should be greater than the branch count of the for loop because the final bounds check will fail and not branch back to the loop body.

BCCS 11.jpeg

In a while loop, the while test is completed at the top of the loop. If the branch associated with the while loop in not taken, then the body of the loop will not have been executed (line counts should be 0).

BCCS 12.jpeg

In a while loop, the while test is completed at the bottom of the loop. The line count of the while loop should be greater than the branch count of the for loop because the final while test will fail and not branch back to the loop body.

BCCS 13.jpeg

In a do-while loop, the while test is completed at the bottom of the loop. The line count of the do-while loop should be greater than the branch count of the for loop because the final while test will fail and not branch back to the loop body.

BCCS 14.jpeg

Conditional Operator (?)

Conditional operator expressions will generate one branch for each conditional operator (?).

Conditional operators on a single line will include a branch to the same line which is for the FALSE condition. If the branch is not taken then the TRUE conditional has not been executed. If the branch is executed fewer times than the line count then both conditions have been executed.

BCCS 15.jpeg

Conditional operator expressions spanning multiple source lines allow for easier (not easy) determination of decisions tested.

BCCS 16.jpeg

versus

BCCS 17.jpeg

Switch Statements

Switch statements with a default case will have a single branch to the default case and use a jump table for the rest. Line counts will indicate which cases have been executed.

BCCS 18.jpeg

Switch statements without a default will have branches for each case. Line counts will indicate which cases have been executed. There will also be a branch to the same line as the switch expression (which represents the default case) which is executed when no explicit cases are executed.

BCCS 19.jpeg

Switch statements with null or no statements will have branches to the next statement following the switch statement. If the switch statement is at the end of a loop, the next statement may be the loop condition test, whose source line number may/will be at the top of the loop.

BCCS 20.jpeg

If Statements

If statements will include (at least) one branch for the condition of each leg. If the branch count is not the same as the line count then both paths of the decision have been tested.

BCCS 21.jpeg

If statements with null/empty legs...TBD

BCCS 21a.jpeg

If statement conditions with multiple boolean operators will have one branch associated with the whole condition. If the boolean operands are spread on separate source lines they will all have the same line count. (See short circuit operators.)

BCCS 22.jpeg

If statement conditions with short circuit operators will have one branch for each operand of the short circuit operator. If a branch has a count of 0 then that path has not been executed. If the boolean operands are spread on separate source lines they will have separate line counts which will indicate if each operand was executed.

BCCS 23.jpeg

GNAT Ada/x86

Exception Checks

Straight-line code will often include exception checks for ranges and bounds. If straight-line code contains branches to the same line then these are exception checks. If the branch counts are the same as the line counts then the exception checks passed and an exception was not raised.

BCCS 24.jpeg

Loops

All for loops will include a branch for the loop range check at the top. The normal loop range check should have a line count greater than the line count of the body statements to indicate the loop reached completion and the branch count should be non-zero to indicate the exit was taken. Testing for 0, 1, and multiple loop executions should be achieved with separate test runs.

BCCS 25.jpeg

For loops with dynamic bounds will test for a null loop range at the top of the loop and contain a branch to the next statement which is taken when the loop range is null.

BCCS 26.jpeg

While loops will test loop exit condition at the top of the loop and contain a branch to the next statement which is taken when the loop exit is taken. The loop exit condition should have a line count greater than the line count of the body statements to indicate the loop reached completion. Using short circuits operators in the loop exit condition will increase the number of branches, and each should be executed for complete coverage. Testing for 0, 1, and multiple loop executions should be achieved with separate test runs.

BCCS 27.jpeg

Exit Statements

Loop exit statements will include a branch which is taken when the exit is taken. The branch count should be less than the line count to indicate that both paths of the decision are taken. Using short circuits operators in the loop exit condition will increase the number of branches, and each should be executed for complete coverage.

BCCS 28.jpeg

Case Statements

Case statements will have a single branch at the top to handle the others case. Coverage of the when alternatives can be confirmed by line counts.

BCCS 29.jpeg

If Statements

If statements will include (at least) one branch for the condition of each leg. If the branch count is greater than zero but less than the line count then both paths of the decision have been tested.

BCCS 30.jpeg

If statements conditions with multiple boolean operators will have one branch associated with the whole condition. If the boolean operands are spread on separate source lines they will all have the same line count. (See short circuit operators.)

BCCS 31.jpeg

If statement conditions with short circuit operators will have one branch for each operand of the short circuit operator. If a branch has a count of 0 then that path has not been executed. If the boolean operands are spread on separate source lines they will have separate line counts which will indicate if each operand was executed.

BCCS 32.jpeg

XLC/PPC

This section covers the IBM XLC compiler on AIX PPC targets.

Functions

At the end of a function the closing brace may have a line count of 0. This can be safely ignored.

Loops

In a for loop, an index bounds test is completed at the top and bottom of the loop. The branches generated for those tests are associated with the first line of the loop, and the first is from the top of the loop and the second is from the bottom of the loop. test, the loop body was not executed (the difference of the counts). If the first branch count is less than the line count of the loop test, the loop body was not executed (the difference of the counts).

BCCS 33.jpeg

In a while loop, an loop exit test is completed at the top and bottom of the loop. The branches generated for those tests are associated with the first line of the loop, and the first is from the top of the loop and the second is from the bottom of the loop. test, the loop body was not executed (the difference of the counts).

BCCS 34.jpeg

In a do-while loop, an loop exit test is completed at the bottom of the loop. The branch generated for that test is associated with the last line of the loop. The loop body will have been executed one more time then the branch count, as confirmed by loop body line counts.

BCCS 35.jpeg

Conditional Operator (?)

Conditional operator expressions will generate one branch for each conditional operator (?). Conditional operators on a single line will include a branch to the same line which is for the FALSE condition. If the branch is not taken then the TRUE conditional has not been executed. If the branch is executed fewer times than the line count then both conditions have been executed.

BCCS 36.jpeg

Conditional operator expressions spanning multiple source lines allow for easier (not easy) determination of decisions tested.

BCCS 37.jpeg

Switch Statements

Switch statements with a default case will have a single branch to the default case which shows up as a branch to the top of the switch statement. (This is a conditional branch to an unconditional branch to the default case.) Line counts will indicate which cases have been executed.

BCCS 38.jpeg

Switch statements without a default will have branches for each case. Line counts will indicate which cases have been executed.

BCCS 39.jpeg

Switch statements with null or no statements will not have branches to those cases. For multiple cases with the same statements, each case will have a branch to the same source line.

BCCS 40.jpeg

If Statements

If statements will include (at least) one branch for the condition of each leg. If the branch count is not the same as the line count then both paths of the decision have been tested.

BCCS 41.jpeg

If statements with null/empty legs...TBD

BCCS 42.jpeg

If statement conditions with multiple boolean operators will have one branch associated with the whole condition. If the boolean operands are spread on separate source lines they will all have the same line count. (See short circuit operators.)

BCCS 43.jpeg

If statement conditions with short circuit operators will have one branch for each operand of the short circuit operator. If a branch has a count of 0 then that path has not been executed. If the boolean operands are spread on separate source lines they will have separate line counts which will indicate if each operand was executed.

BCCS 44.jpeg

PowerAda/PPC

This section covers the OCS PowerAda compiler for the PPC target.

Exception Checks

Straight-line code will often include exception checks for ranges and bounds. If straight-line code contains branches to the end of a subprogram then these are exception checks. Branch counts will indicate how many time the exception was raised.

BCCS 45.jpeg

Loops

All for loops will include a branch for the loop range check at the bottom. The normal loop range check should have a branch count less than the line count of the body statements to indicate the loop reached completion. Testing for 0, 1, and multiple loop executions should be achieved with separate test runs.

BCCS 46.jpeg

For loops with dynamic bounds will test for a null loop range at the top of the loop and contain a branch to the next statement which is taken when the loop range is null.

BCCS 47.jpeg

While loops will test the loop exit condition at the top of the loop and contain a branch to the next statement which is taken when the loop exit is taken. While loops will test the loop exit condition at the bottom of the loop too and contain a branch to the top of the loop which is taken when the loop continues. The loop exit condition should have a line count greater than the line count of the body statements to indicate the loop reached completion. Using short circuits operators in the loop exit condition will increase the number of branches, and each should be executed for complete coverage. Testing for 0, 1, and multiple loop executions should be achieved with separate test runs.

BCCS 48.jpeg

Exit Statements

Loop exit statements will include a branch which is taken when the exit is taken. The branch count should be less than the line count to indicate that both paths of the decision are taken. Using short circuits operators in the loop exit condition will increase the number of branches, and each should be executed for complete coverage.

BCCS 49.jpeg

Case Statements

Case statements will have a branch for each alternative listed. The others alternative will have branches associated with values not handled by the specified alternatives, including values below the range, above the range, and values in between. Coverage of the when alternatives can be confirmed by line counts. Coverage of out of bound values can be confirmed by the branch counts.

BCCS 50.jpeg

If Statements

If statements will include (at least) one branch for the condition of each leg. If the branch count is greater than zero but less than the line count then both paths of the decision have been tested.

BCCS 51.jpeg

If statements conditions with multiple boolean operators will have one branch associated with the whole condition. If the boolean operands are spread on separate source lines they will all have the same line count. (See short circuit operators.)

BCCS 52.jpeg

If statement conditions with short circuit operators will have one branch for each operand of the short circuit operator. If a branch has a count of 0 then that path has not been executed. If the boolean operands are spread on separate source lines they will have separate line counts which will indicate if each operand was executed.

BCCS 53.jpeg