Improve or Justify Missing Code Coverage Results

You can calculate code coverage metrics to see how much of your C/C++ code is validated by existing tests. You can calculate the code coverage metrics of your tests in the Polyspace Platform user interface or using the polyspace-code-profiler command. See:

This topic shows how you can use the code coverage results to add tests that cover untested execution paths. This topic also shows how you can justify missing coverage results and carry over the justification to future projects.

Prerequisites

To begin with, you must have calculated code coverage in the Polyspace^® Platform user interface or at the command line. To review code coverage results, it is convenient to open the results (*.psprof file) in the user interface. For more information, see:

Alternatively, you can also review the results in an HTML report. See Structure of HTML Reports Generated from C/C++ Code Profiling Results.

To follow this topic, calculate the code coverage for this source code and tests cases:

Source code:

int factorial (int n)
{
    if (n > 0)
        {
            if (n < 20)
                {
                    long long bar = 1;
                    for (int i = 1; i <= n; ++i)
                        {
                            bar *= i;
                        }
                    return bar;
                }
            else
                return 0;
        }
    else
        return -1;
}

Tests:
- factorial(1)==1
- factorial(2)==2

The code coverage of these test cases is incomplete:

To address the missing coverage, you can add test cases or justify the missing coverage.

Add Missing Tests Manually

Identify which tests to add by reviewing the untested outcomes of decisions. For instance, Polyspace Test™ identifies that these condition outcomes in factorial() are untested:

Decision	Untested Outcome
`n>0`	`false`
`n<20`	`false`

To cover the outcome (n<20)==false, add a test case where the input is greater than 20. The new test case factorial(21)==0 covers the outcome (n<20)==false, which improves the code coverage results:

Generate Missing Tests

Instead of adding tests manually, you can use the code coverage results to generate missing tests. For more information, see Generate Additional C/C++ Tests for Missing Code Coverage.

Justify Missing Coverage

In cases where the low coverage is justifiable, you can justify the result. If your code leverages third-party code, you might be satisfied with less than 100% coverage. Or, your code might contain code execution paths that are not relevant. For instance, because factorial() calculates the factorial of a number, the behavior of this mathematical operation when the input n is negative might not be relevant for you. Instead of adding new tests to cover n>0==False, justify the missing coverage. Once you add justification to your results, you can:

Apply the same justification to your project later when you update your tests or source code.
Apply the justification to other projects that use the same source code.
Reach coverage objectives set by your organization.

Justify Missing Coverage in Polyspace Platform User Interface

To justify the missing coverage in the Polyspace Platform user interface, you can either import preexisting justifications or add the justification directly in the UI.

To add justification to the coverage result by using the Polyspace Platform user interface:

Open code coverage results in the user interface. For more information, see Open Polyspace Results in Polyspace Platform User Interface.
In the Results List, locate the result that you want to justify. The results list shows files, functions, and decisions by default. To see the outcomes as well, select Show Outcomes.
You can justify outcomes, decisions, conditions, functions, or projects. A justified result appears highlighted by the color cyan in the results list. If you justify an outcome or a decision, the justification propagates to the function, file, and project and all these results show cyan highlights. Similarly, if you justify a file or a project, the justification propagates to the lower level results. To justify the outcome n>0==False, select the row 'false' outcome under n>0.
In the Result Details pane:
- Select Status as Justified.
- Optionally, enter a comment in the text box.
Note that the status Justified appears only for the outcome n>0==False. The justification propagates to the higher levels, highlighting the decision n>0 and the function factorial as the color cyan in the Results List pane. The status does not propagate. Because this outcome is the only uncovered execution path, justifying this outcome brings coverage metrics of the higher levels to 100%.
For more information, see Rules for Propagating Code Coverage Justifications Across Multiple Results.
You can save this added justification by clicking Save. The justification is saved in a *.psprof.filter file that is saved in the same folder as the code coverage results.

Once you save or export justifications in a *.psprof.filter file, you can reuse the justifications in a different project by importing the *.psprof.filter file. To import preexisting justification, open the coverage results in the Review tab and click Import. Then, navigate to the preexisting justification (*.psprof.filter file).

Justify Missing Coverage at Command Line

At the command line, you review code coverage results by generating a readable report from a *.psprof file. You cannot add justifications directly in the report, which is a static document. To add justifications to results in the command line, create a *.psprof.filter file that describes your justifications. Then apply the justifications to your results to generate a report containing the justified code coverage results.

You can export justifications for missing code coverage from the Polyspace Platform user interface. If you do not have access to this UI, you can manually create a *.psprof.filter file that contains the justifications. See Save Justification for C/C++ Code Coverage Results. This section shows how to justify missing coverage without using the Polyspace Platform user interface.

In the function factorial(), to justify the decision n<0,:

Save this XML content as the file filt.psprof.filter.

<?xml version="1.0" encoding="utf-8"?>
<filter>
    <rule type="DECISION" fileName="src.c" functionName="factorial" expr="n &gt; 0" index="1" mode="JUSTIFIED" rationale="Behavior Undefined"/>
</filter>

To generate a report with the added justification, at the command line, enter:
```
polyspace-code-profiler -report -html -report-dir reportFolder -filter-files filt.psprof.filter  result.psprof
```
Where result.psprof is the coverage result.
In the coverage report, the reported metric now reaches 100%. The report highlights the expression n<0 in cyan and states that the expression is justified.

Once you justify the missing coverage of an outcome, the justification propagates. See Rules for Propagating Code Coverage Justifications Across Multiple Results.