In this section:

Introduction

The Parasoft Findings Plugin for Jenkins allows you to visualize static analysis, test, and code coverage results, including support for quality gates, in Jenkins. It converts XML reports generated by Parasoft products into trend graphs and enables you to conveniently view the details or easily navigate to rule documentation. The plugin can be used with Freestyle, Maven, and Pipeline jobs.

The plugin can consume the following report types:

• Functional test reports generated by Parasoft SOAtest 2020.1+.
• Static analysis, metrics analysis, and unit test and code coverage reports generated by 2020.2+ versions of C/C++test, Jtest, and dotTEST.

Requirements

Parasoft Findings Plugin integrates with the Warnings Next Generation plug-in to report Parasoft code analysis results. Refer to the following table to determine which version of Jenkins and the Warnings Next Generation plug-in is supported by the Parasoft Findings Plugin. If your version is not shown in the table, it supports the same Jenkins and Warnings NG versions as the next, lowest version.

Previous versions are available from the Jenkins plug-in releases section.

Refer to the Publishing Static Analysis Results for 10.4.1 section for usage.

xUnit is required to publish unit test results. 

Java 11 JDK and Maven 3.8.1+ are required to build the plugin.

Upgrading to 10.4.2+

Since 10.4.2, this plugin has been integrated with the Warnings Next Generation Plugin to visualize static analysis results. Make a copy of all your job configuration settings prior to upgrading from a previous version of the Parasoft Findings Plugin for Jenkins. All settings from previous versions, such as the location of the report.xml files, will be lost after upgrading. You will need to re-apply your configuration settings after the upgrade.

Installation

The simplest installation method is to use the Jenkins plugin UI:

1. Choose Manage Jenkins> Manage Plugins> Available.
2. Locate and enable Parasoft Findings Plugin for Jenkins.
3. Click Download now and install after restart. 

Alternatively, you can download the plugin from Parasoft's GitHub repository and follow the instructions to build the plugin as an HPI file (plugin format for Jenkins): https://github.com/jenkinsci/parasoft-findings-plugin. After creating the HPI file, you can deploy the plugin through the Jenkins web UI or through the command line. 

Web UI

1. Choose Manage Jenkins> Manage Plugins from the Jenkins menu and click the Advanced tab.
2. In the Upload Plugin section, click Choose File and choose parasoft-findings.hpi.
3. Click Upload.
4. Restart Jenkins.

Command Line

See the Jenkins documentation for command line installation. Restart Jenkins after installing the plugin. 

Publishing Static Analysis Results

Parasoft Findings supports Maven, Freestyle, and Pipeline jobs. See Viewing Static Analysis Findings for a description of the graphs and reports generated by the Parasoft Findings Plugin.

Maven and Freestyle Jobs

1. Open your Maven job and choose Configure> Post-build Actions.
2. Choose Record compiler warnings and static analysis results from the Add post-build action menu.
   
3. Choose Parasoft Findings from the Tool drop-down menu in the Static Analysis Tools section.
   
4. Specify the location of the static analysis results report (report.xml) file in the Report File Pattern field. You can use an Ant-style pattern to specify multiple directories.
5. Enable the Skip symbolic links when searching for files option if you do not want to include symbolic links.
6. Specify an encoding character set in the Report Encoding field. Start typing in the field to begin auto-filling the character set.
7. Specify the location of the settings.properties file for your Parasoft tool. The .properties file contains settings that, for example, connect the tool to DTP, specify build ID, etc. Refer to your tool documentation to learn more about the settings files.
8. (Optional) Specify a custom ID and custom name for the tool.
9. If you are executing other tools, you can enable the Aggregate results option to aggregate the results into a single result. This is functionality native to the Warnings Next Generation plug-in.
10. Enable the Run always option if you want to record results from failed builds, in addition to stable and unstable builds.
11. Click Apply.

Pipeline Jobs

Add a step to the pipeline script that calls the Warnings Next Generation publisher. You can add Parasoft Findings with the tool parameter and specify the location of the report.xml file(s) and the settings.properties file as arguments. For example:

node {
    stage('Publishing Static Analysis Results') {
        recordIssues (
            tools: [
                parasoftFindings (
                    pattern: '**/report.xml',
                    localSettingsPath: 'settings.properties'
                )
            ]
        )
    }
}

pipeline {
    agent any
    stages {
        stage('Publishing Static Analysis Results') {
            steps {
                recordIssues (
                    tools: [
                        parasoftFindings (
                            pattern: '**/report.xml',
                            localSettingsPath: 'settings.properties'
                        )
                    ]
                )
            }
        }
    }
}

The parameters passed to parasoftFindings:

• pattern: Specifies the location of the static analysis results report (for example, report.xml). You can use an Ant-style pattern to specify multiple directories.
• localSettingsPath: Specifies the location of the settings.properties file for your Parasoft tool. The .properties file contains settings that, for example, connect the tool to DTP, specify build ID, and so on. Refer to your tool documentation to learn more about the settings files.

Publishing Static Analysis Results for 10.4.1

Use Parasoft Findings for Jenkins 10.4.1 if you are on an older version of Jenkins. Download the .hpi file from the plug-in archive directory (see Requirements) and install it as described in the Web UI section. See Viewing 10.4.1 Findings for information about understanding the output from Parasoft Findings 10.4.1. 

Maven and Freestyle Jobs

1. Enable the Publish Parasoft analysis results option. 
   • For Maven jobs, choose Configure> Build Settings and enable the Publish Parasoft analysis results option. 
     
   • For Freestyle jobs: 
     1. Choose Configure> Post-build Actions> Add post-build action
     2. Choose Publish Parasoft analysis results from the drop-down menu.
        
2. Specify an absolute or workspace-relative path to the settings file used by your Parasoft Analyzer in the Settings field. The settings file should include the report.location property, which specifies where the report.xml file is saved. See the documentation for your analyzer for additional information about configuring the settings file.
3. You can also enable the Report location option and specify a workspace-relative path to the report.xml file generated by Parasoft Analyzer in the File pattern field. This setting overrides the report.location configuration from the previous step and is useful when Jenkins and the directory for the report.xml file are both on the local machine.

Pipeline Jobs

Jenkins Pipeline is a suite of plugins that support implementing and integrating continuous delivery pipelines into Jenkins. See the Jenkins documentation for additional information about pipelines. 

To publish static analysis results using a pipeline job, add a step to the pipeline script to call the Parasoft Findings publisher class or use the symbolic name:

step([$class: 'ParasoftPublisher', useReportPattern: true, reportPattern: '*.xml', settings: ''])

or

parasoftFindings useReportPattern: true, reportPattern: '*.xml', settings: ''

The parameters passed correspond to the options following available in plugin configuration:

C/C++test Professional Report Settings

If you are generating static analysis reports with C/C++test Professional 2023.1 or earlier, make sure the Add absolute file paths to XML data option is enabled to link the source code if it is stored in the Jenkins workspace. You can enable this option on the command line by setting the report.location_details=true property in the settings file.

Displaying Rule Documentation

You can display static analysis rule documentation in the reports generated by the plugin.

You can either display the local rule documentation or the documentation stored in DTP.

Documentation in DTP

Connect your tool to DTP by configuring the dtp.url setting in your tool's .properties file. For example, dtp.url=https://<HOST>:<PORT>.

Note: Only DTP 2023.1 or later is supported.

Local Documentation

For local documentation, set the report.rules property to the directory that contains the analyzer documentation. For example: report.rules=<TOOL_INSTALL>/rules/doc

Viewing Static Analysis Results

This section describes the graphs and reports generated by the current version of the Parasoft Findings Plugin. See Viewing 10.4.1 Findings if you are using the older version of the plug-in. 

Parasoft Warnings Trend Graph

The Parasoft Warnings Trend graph appears on the project's homepage. The graph provides an overview of the analysis history. 

You can hover your pointer over a point in the graph to view details. Click on the graph to open the Parasoft Warnings page.

Parasoft Warnings

This page contains the Overview widget, History widget, and Details report.

Overview Widget

The Overview widget has a Severity Distribution mode that shows the reported violation's severities as color-coded wheel segments. The segments are proportional to the total number of violations in the report. You can hover your pointer over a segment to view details.

 Click the next or previous arrow to switch to Reference Comparison mode. 

The Reference Comparison mode that shows the status of violations as new reports are generated.

Click the next or previous arrow to switch to Severities Distribution mode. 

If you zoom out on the webpage, the Overview widget will disappear, and the Severity Distribution and Reference Comparison widgets will be shown.

History Widget

The History widget has three modes for viewing different aspects of the change in violations. The severity mode shows the change in violations according to their severity. Hover your pointer over an area in the graph to view details.

Click the next or previous arrow to switch to a different mode. 

The total violations mode shows the change in total number of violations. Hover your pointer over an area in the graph to view details. 

Click the next or previous arrow to switch to a different mode. 

The new and fixed mode shows the change in violations according to their status. Hover your pointer over an area in the graph to view details. 

For all modes, you can click the setting icon to choose the unit of the x-axis to be date or build.

You can also click and drag the ends of the slider to narrow the range of dates or builds included in the widget. 

Details Report

The Details report shows details about how violations are distributed across the project. 

Click on the tabs and cross-links to explore different aspects of the violations data.

Viewing 10.4.1 Results  

Static analysis trend graphs display results organized by the module, rule category or severity.

You can review the findings in the source code and navigate to rule documentation.

Publishing Test Execution Results

You can publish unit test results from Maven, Freestyle, and Pipeline job executions.

Freestyle and Maven Jobs 

1. Choose Configure> Post-build Actions> Add post-build action.
2. Choose Publish xUnit test result from the drop-down menu. 
    
3. Click Add.
4. Choose ParasoftAnalyzers-10.x or ParasoftSOAtest-9.x. 
   
5. Specify a workspace-relative path to the report.xml file generated by Parasoft Analyzer in the Pattern field.

Pipeline Jobs

To publish unit and functional test results using a pipeline job, add a step to call the xUnit publisher class and specify the appropriate type of reports to publish:

ParasoftAnalyzers-10.x

node {
    stage('Publishing Test Execution Results') {
        xunit (
            tools: [[$class: 'ParasoftType', pattern: '**/report.xml']]
        )
    }
}

pipeline {
    agent any
    stages {
        stage('Publishing Test Execution Results') {
            steps {
                xunit (
                    tools: [[$class: 'ParasoftType', pattern: '**/report.xml']]    
                )
            }
        }
    }
}

ParasoftSOAtest-9.x

node {
    stage('Publishing SOATest Results') {
        xunit (
            tools: [[$class: 'ParasoftSOAtest9xType', pattern: '**/report.xml']]
        )
    }
}

pipeline {
    agent any
    stages {
        stage('Publishing SOATest Results') {
            steps {
                xunit (
                    tools: [[$class: 'ParasoftSOAtest9xType', pattern: '**/report.xml']]
                )
            }
        }
    }
}

C/C++test Professional Unit Test Results

C/C++test reports for unit test results must be generated with the Overview of checked files and executed tests option enabled. You can enable this option on the command line by using the option -property report.contexts_details=true or by setting the report.contexts_details=true property in the settings file.

Starting with version 2024.1, you can also use the command line option -property report.additional.report.dir=<REPORT_DIR> when generating the reports and use reports generated in this directory.

Viewing Test Execution Results

The test execution trend graphs shows test status, execution time, and stack trace for test failures.

Publishing Code Coverage Results

You can publish code coverage from Maven, Freestyle, and Pipeline job executions.

Freestyle and Maven Jobs

1. Go to Configure > Post-build Actions > Add post-build action and choose Record Parasoft code coverage results.
   
2. Enter the relative path to the Parasoft coverage files that you want to use in the Report File Pattern field. To enter multiple paths, separate them by commas.
3. Enter the name of the job that you want to use in the Reference Job field. For more information about specifying a reference job, see https://www.jenkins.io/doc/book/using/referencing-another-project-by-name/.  If this field is left empty, the current job will be used as a default.
4. Enter a build number from reference job in the Reference Build field. The build number can be found in the build title after the '#' symbol. If this field is left empty, last stable build will be used as a default.
5. (Optional) Add quality gates to evaluate after a build. See Configuring Quality Gates.
6. Choose the correct encoding for the source files from the Source Code Encoding menu. If this field is left empty, the platform's default encoding will be used.
   
7. Click Save.

Pipeline Jobs

To publish code coverage using a pipeline job, add a step to call the Parasoft Findings plugin. For example:

node {
    stage('Publishing Code Coverage Results') {
        recordParasoftCoverage (
            pattern: '**/coverage.xml',
            referenceBuild: '20',
            referenceJob: 'Demo', 
            sourceCodeEncoding: 'UTF-8'
        )
    }
}

pipeline {
    agent any
    stages {
        stage('Publishing Code Coverage Results') {
            steps {
                recordParasoftCoverage (
                    pattern: '**/coverage.xml',
                    referenceBuild: '20',
                    referenceJob: 'Demo', 
                    sourceCodeEncoding: 'UTF-8'
                )
            }
        }
    }
}

The parameters passed to recordParasoftCoverage:

• pattern: Specifies the location of the coverage report (for example, coverage.xml).
• referenceBuild: Specifies a reference build. If not specified, the last stable build will be used by default.
• referenceJob: Specifies a reference job. If not specified, the current job will be used by default.
• sourceCodeEncoding: Specifies the character encoding of your source code. If not specified, the platform's default encoding will be used.

Alternatively, you can generate a script of Parasoft Findings Plugin by Pipeline Syntax:

1. Choose recordParasoftCoverage from the Sample Step menu.
2. Enter the relative path to the Parasoft coverage file in the Report File Pattern field. To enter multiple paths, separate them by commas.
3. Enter the name of the job that you want to use in the Reference Job field. For more information about specifying a reference job, see https://www.jenkins.io/doc/book/using/referencing-another-project-by-name/. If this field is left empty, the current job will be used as a default.
4. Enter a build number from reference job in the Reference Build field. The build number can be found in the build title after the '#' symbol. If this field is left empty, last stable build will be used as a default.
5. (Optional) Add quality gates to evaluate after a build. See Configuring Quality Gates.
6. Choose the correct encoding for the source files from the Source Code Encoding menu. If this field is left empty, the platform's default encoding will be used.
   
7. Click Generate Pipeline Script.

Viewing Code Coverage Results

You can view the total coverage of each build in the Status tab.

Click the Parasoft Coverage tab to view the details of your code coverage. This tab has three sub-tabs for Overview, Overall Code Coverage, and Modified Code Coverage views.

C/C++test Professional Reports

Code coverage reports for C/C++test Professional are not supported for versions prior to 2024.1.

Starting with version 2024.1, you can also use the command line option -property report.additional.report.dir=<REPORT_DIR> when generating the reports and use reports generated in this directory.

Configuring Quality Gates

The Parasoft Jenkins plugin supports quality gates. Once configured, quality gate status information will be shown in the plugin.

Static Analysis

For static analysis, no additional configuration is required once you have defined your quality gates in Jenkins (refer to Quality gate configuration for more information about configuring quality gates in Jenkins). The status of the quality gate (Success, Unstable, or Failed) will be shown in the plugin and you can hover over the status icon for more details.

Code Coverage

When configuring the settings of Parasoft Code Coverage, you can add a quality gate with the fields listed below. The specified reference build will be compared with the current build for any configured quality gates tasks.

• Type: Choose the type to be used for the code coverage computation of this quality gate. There are two types available:
  • Overall project: Coverage of the whole project. This is an absolute value that might not change much from build to build.
  • Modified code lines: Coverage of the modified lines (for example, within the modified lines of a pull or merge request). This will focus on new or modified code only.
• Threshold: Defines the minimum value of line coverage that is required to pass the quality gate. The range must be between 0 and 100, any value outside this range will be set to 0 or 100. The default value is 0.0, which will be used if this field is empty.
• Stage or Build Result: When a quality gate fails, this property determines whether the result of the associated coverage stage will be marked as unstable or failed.

For Pipeline jobs, add the configurations of quality gates in a pipeline script that calls the Parasoft Findings plugin. For example:

node {
    stage('Publishing Code Coverage Results with Quality Gates') {
        recordParasoftCoverage (
            pattern: '**/coverage.xml',
            referenceBuild: '20',
            referenceJob: 'Demo', 
            sourceCodeEncoding: 'UTF-8', 
            coverageQualityGates: [
                [
                    criticality: 'NOTE',
                    threshold: 60.0, 
                    type: 'PROJECT'
                ]
            ]
        )
    }
}

pipeline {
    agent any
    stages {
        stage('Publishing Code Coverage Results with Quality Gates') {
            steps {
                recordParasoftCoverage (
                    pattern: '**/coverage.xml',
                    referenceBuild: '20',
                    referenceJob: 'Demo', 
                    sourceCodeEncoding: 'UTF-8', 
                    coverageQualityGates: [
                        [
                            criticality: 'NOTE',
                            threshold: 60.0, 
                            type: 'PROJECT'
                        ]
                    ]
                )
            }
        }
    }
}

The parameters passed to coverageQualityGates:

• criticality: Determines the result of the coverage stage. Options: 'NOTE', 'UNSTABLE', 'ERROR' or 'FAILURE'.
• threshold: Specifies the minimum line coverage required to pass the quality gate. The range must be between 0 and 100.
• type: Determines the type of code coverage computation for this quality gate. Options: 'PROJECT' or 'MODIFIED_LINES'.

The status and details of quality gates (Success, Unstable, or Failed) will be shown in the table in Summary page.

Troubleshooting

Can't write coverage paint of 'Xxx‘ to zipped source file ’Xxx'

This error occurs when there is a mismatch between the Source Code Encoding configured in Jenkins and the charset used in your source code. To resolve this:

1. Check Jenkins Settings: Confirm that the Source Code Encoding option in the Jenkins settings aligns with the encoding charset of your source code files. If this option isn't configured, Jenkins defaults to UTF-8.
2. Adjust File Encoding:
   • If the error affects only a single file, consider changing the encoding charset of that file to match your Jenkins settings.
   • If the error persists in all files of the project, it's recommended that you update the Source Code Encoding option in the Jenkins settings to match the encoding of your source code files.

Third-party Acknowledgements

The Parasoft Findings Plugin for Jenkins uses the following third-party software:

Apache Ant

This software is used under an Apache License 2.0 with this notice.

Apache Ant Launcher

This software is used under an Apache License 2.0 with this notice.

Apache HttpClient

This software is used under an Apache License 2.0 with this notice.

Apache HttpClient5

This software is used under an Apache License 2.0 with this notice.

Apache HttpClient Fluent API

This software is used under an Apache License 2.0 with this notice.

Apache HttpCore5

This software is used under an Apache License 2.0 with this notice.

Apache HttpCore5-h2

This software is used under an Apache License 2.0 with this notice.

Code Coverage API Plugin

This software is used under a MIT License.

Coverage Model

This software is used under a MIT License.

FindBugs JSR305

This software is used under an Apache License 2.0.

jackson-databind

This software is used under an Apache License 2.0 with this notice.

jsoup Java HTML Parser

This software is used under a MIT License.

Plexus Classworlds

This software is used under an Apache License 2.0.

Saxon-HE

This software is used under a Mozilla Public License 2.0.

SpotBugs Annotations

This software is used under a GNU LGPLv2.1 License.

XML Resolver

This software is used under an Apache License 2.0 with this notice.