Customize Content and Style of Polyspace Test Reports

You can export C/C++ test results to HTML reports for archiving and certification. The content and formatting of the test reports can be customized. For instance, you can add headers, footers and other custom sections to these reports as required by your organization or apply custom styling to the content you added.

This topic describes the basic approach to customizing HTML reports for test or code profiling generated with Polyspace® Test™.

Customizing Reports Using Report Options File

A report options file is a JSON file that allows you to customize certain aspects of a test or code profiling report.

General Customizations

You can apply these customizations to both test and code profiling reports:

  • Add a header or footer to the report.

  • Add a custom HTML section to the report with a custom title.

  • Reorder the existing sections in the report and insert your custom section at the location you want.

  • Apply custom CSS styles to your custom sections or the existing sections.

Test Report Customizations

You can apply these customizations to reports generated from test results:

  • Generate test specification reports linked from test results.

  • Omit passing assessments from the test reports.

You can also specify these customizations directly using options in the user interface or command line instead of using a report options file. For more information, see Report C/C++ Test Specifications with Test Results and Report Only Failing Assessments in C/C++ Test Reports.

Coverage Report Customizations

You can apply these customizations to reports generated from code coverage results:

  • Omit fully covered elements from the test reports.

  • Omit reporting of cyclomatic complexity.

Create Report Options File

This JSON file shows the full structure of a report options file:

{
    "header": {
        "<text|file>": "<textToEmbed|fileToImportFrom>"
    },
    "footer": {
        "<text|file>": "<textToEmbed|fileToImportFrom>" 
    },
    "style": {
        "<text|file|link>": "<cssToEmbed|cssFileToImportFrom|cssFileToLink>"
    },
    "test_results_report": {
        "report_passed_assessments": <true|false>,
        "generate_test_specification_report": <true|false>,
        "sections_order": { 
            "main_report": [
                "PROJECTINFO", 
                "SECTION_ID", 
                "ENVIRONMENTINFO", 
                "SUMMARY", 
                "SUITESSUMMARY", 
                "MESSAGES"
            ],
            "test_specification_report": ["<sectionId>", "SUITESSUMMARY"]
        }
    },
    "profiling_results_report": {
        "omit_fully_covered_elements": <true|false>,
        "report_cyclomatic_complexity": <true|false>,
        "report_uncalled_functions": <true|false>,
        "sections_order": {
            "main_report": ["INFO", "RUN", "SUMMARY"],
            "per_source_report": ["INFO", "RUN", "SUMMARY", "DETAILS", "CODE"]
        }
    },
    "custom_sections": {
        "<sectionId>": {
            "file": "<htmlFileToImportFrom>",
            "title": "<sectionTitle>"
        }
    }
}

When creating your own report options file:

  1. Copy this example JSON file and remove or modify its contents as needed. For more information on the JSON elements used in the report options file, see Parts of Report Options File.

  2. Save the file.

  3. By using a JSON validator or by visual inspection, validate your file to make sure that it is still a valid JSON file. A JSON validator ensures that your JSON file does not have issues such as:

    • An opening brace that is missing a corresponding closing brace.

    • A path in a JSON string that is not escaped appropriately.

For examples of ways to modify the report options file, see Report Options File Examples.

Generate Report Using Report Options File

To specify a report options file for customizing the content and style of a report:

  • When generating reports in the Polyspace Platform user interface:

    1. With the results open, on the Polyspace Platform toolstrip, select Report. In the Generate HTML Report dialog box, specify the path to a report options JSON file for the Options file setting. For more details on the other options in the dialog box, see Generate Reports from C/C++ Test Results.

    2. Select OK.

  • When generating reports at the command line, use the option -report-options with the command polyspace-test -report.

    For instance, to generate an HTML report from the results using a reports options file <reportCustomizations>.json, at the command line, enter this command:

    polyspace-test -report -report-dir <reportFolder> -html <resultsFolder> -report-options <reportCustomizations>.json
    Here, <reportFolder> is the path to the folder where the generated report is stored and <resultsFolder> is the path to the folder that contains your test results (.pstestr file).

Parts of Report Options File

The report options file can consist of the following parts:

  • header and footer:

    Use the header and footer sections to enter a custom header and footer. You can enter the header or footer content in one of these ways:

    • Use the JSON key text:

      "text": "<textToEmbed>"
      Here, <textToEmbed> is the text that is shown in the header or footer.

    • Use the JSON key file:

      "file": "<fileToImportFrom>"
      Here, <fileToImportFrom> is a text or HTML file that you import into the header or footer. You can specify an absolute path to the file or a path relative to the report options file.

  • style:

    Use the style section to apply custom styling to the report. You can specify the CSS styling in one of these ways:

    • Specify the CSS styles directly by using the JSON key text:

      "text": "<cssToEmbed>"
      Here, <cssToEmbed> is the CSS that will be directly added to the style element of the report HTML-s.

    • Specify a CSS file by using the JSON key file:

      "file": "<cssFileToImportFrom>"
      Here, <cssFileToImportFrom> is the CSS file whose content is added to the style element of the report HTML. You can specify an absolute path or a path relative to the report options file.

    • Specify a CSS file by using the JSON key link:

      "link": "<cssFileToLink>"
      Here, <cssFileToLink> is an external style sheet that is referenced from a link element in the report HTML-s. You can specify an URL address, an absolute path to a CSS file, or a path relative to the generated HTML reports.

      Using an external style sheet allows you to apply any modifications in the style without having to regenerate the report HTML.

  • test_results_report:

    Use the test_results_report section to modify the contents of the test reports. In particular, you can perform these actions:

    • Omit passed assessments:

      "report_passed_assessments": false

    • Generate test specification report in addition to test result reports:

      "generate_test_specification_report": true

    • Remove sections of the report, adjust the order of the sections, and insert your own sections. For instance, the following specification omits the Environment Information section (with ID ENVIRONMENTINFO) from the main test report. It also inserts a section with ID <sectionId> in between the sections Project Information (with ID PROJECTINFO) and Summary (with ID SUMMARY).

      "main_report": ["PROJECTINFO", "<sectionId>", "SUMMARY", "SUITESSUMMARY", "MESSAGES"]
      Each section in the report is referenced by its HTML ID. To see the ID of a section, you can inspect the page source in your browser.

  • profiling_results_report:

    Use the section profiling_results_report to modify the contents of the code profiling reports. In particular, you can perform these actions:

    • Omit fully covered elements:

      "omit_fully_covered_elements": true

    • Report cyclomatic complexity:

      "report_cyclomatic_complexity": true

    • Report uncalled functions in the profiling summary report:

      "report_uncalled_functions": true

    • Remove sections of the report, adjust the order of the sections, and insert your own sections. For instance, this specification omits the Code section (with ID CODE) from the per-file coverage report:

      "per_source_report": ["INFO", "RUN", "SUMMARY", "DETAILS"]
      Each section in the report is referenced by its HTML ID. To see the ID of a section, you can inspect the page source in your browser.

  • custom_sections:

    Use the custom sections section to create custom sections for inserting into the report. Create one or more custom sections using a JSON entry like this one:

    "custom_sections": {
        "<sectionId1>": {
            "file": "<htmlFileToImportFrom1>",
            "title": "<sectionTitle1>"
        },
        "<sectionId2>": {
            "file": "<htmlFileToImportFrom2>",
            "title": "<sectionTitle2>"
        }
}
    Here, <htmlFileToImportFrom1> is an HTML file with the section content and <sectionTitle1> is the section title that is added as an h2 element in the report above the section content. The JSON key <sectionId1> is an ID that is assigned to the custom section. Use this ID in the test_results_report and profiling_results_report parts of the report options file to insert the custom sections into the report.

Report Options File Examples

This section shows examples of simplified report options files for specific use cases. For full workflows using these options files, see polyspace-test -report.

Omit Passed Assessments

This options file omits passed assessments from the generated report:

{
    "test_results_report": {
        "report_passed_assessments": false
    }
}

Add Custom Header And Footer

This options file adds a custom header and footer to the generated report.

{
    "header": {
        "file": "<headerInfo>.html"
    },
    "footer": {
        "text": "For internal audit only. Not for distribution."
    },
    "style": {
        "link": "<reportStyles>.css"
    }
}
This options file is supported by two other files:

  • <headerInfo>.html, containing the header content.

  • <reportStyles>.css, containing the CSS styles to be applied to the header. For instance, to add vertical space between the header and the top of the page, include this code in the CSS file:

    header {
    margin-top: 20px;
}

Add Custom Section

This options file adds a custom section to the generated report.

{
    "custom_sections": {
        "VERSION": {
            "file": "<versionNumber>.html",
            "title": "Version History"
        }
    },
    "style": {
        "link": "<reportStyles>.css"
    },
    "test_results_report": {
        "sections_order": {
            "main_report": "main_report": [
                               "PROJECTINFO",
                               "VERSION", 
                               "ENVIRONMENTINFO", 
                               "SUMMARY", 
                               "SUITESSUMMARY", 
                               "MESSAGES"],
            "test_specification_report": ["VERSION", "SUITESSUMMARY"]
        }
    }
}

This options file is supported by two other files:

  • <versionNumber>.html, containing the section content in HTML format. For example:

    <!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>Version Number</title>
</head>
<body>
    <p>This report contains test results for version 
           <span class="versionNumber">23</span> 
       of the project 
           <span class="projectName">My_project</span>.
    </p>
</body>
</html>

  • <reportStyles>.css, containing the CSS styles to be applied to the section. For instance, to cause HTML elements with classes versionNumber and projectName to appear blue, include this code in your CSS file:

    .versionNumber,
.projectName {
    color: blue;
}

Note that while the HTML content is directly embedded in the generated report, the report contains a link element pointing to the CSS file. This means that if you specify a relative path to the CSS file in the report options file, you have to make sure that the CSS file can be found relative to the HTML file location. In particular, if you specified the file name only, you have to copy the CSS file into the same folder as the HTML file for the CSS styles to be applied.

See Also

Topics