gctsExecuteABAPQualityChecks

Runs ABAP unit tests and ATC (ABAP Test Cockpit) checks for a specified object scope.

Description

This step executes ABAP unit test and ATC checks for a specified scope of objects that exist in a local Git repository on an ABAP system. Depending on your use case, you can specify a scope of objects for which you want to execute the checks. In addition, you can choose whether you want to execute only ABAP units tests, or only ATC checks, or both. By default, both checks are executed.
The results of the checks are stored in a Checkstyle format. With the help of the Jenkins Warnings-Next-Generation Plugin), you can view the issues found, and navigate to the exact line of the source code where the issue occurred. To make the findings visible in the Jenkins plug-in, you need to use the recordIssues step, as displayed in the Example section below.
You can use this step as of SAP S/4HANA 2020 with SAP Note 3159798 implemented.

Usage

We recommend to define values of step parameters via .pipeline/config.yml file.
In this case, calling the step is essentially reduced to defining the step name.
Calling the step can be done either in an orchestrator specific way (e.g. via a Jenkins library step) or on the command line.

JenkinsCommand Line

library('piper-lib-os')

gctsExecuteABAPQualityChecks script: this

piper gctsExecuteABAPQualityChecks

Prerequisites

• ATC checks are enabled in transaction ATC in the ABAP systems where you want to use the step.
• ABAP Unit tests are available for the source code that you want to check. Note: Do not execute unit tests in client 000, and not in your production client.
• gCTS is available and configured in the ABAP systems where you want to use the step.
• If you want to use environmental variables as parameters, for example, GIT_COMMIT: The Git Plugin is installed in Jenkins.
• The Warnings-Next-Generation Plugin is installed in Jenkins.

Parameters

Overview - Step

Name	Mandatory	Additional information
client	yes
host	yes
password	(yes)	pass via ENV or Jenkins credentials (abapCredentialsId)
repository	yes
script	(yes)	reference to Jenkins main pipeline script
username	(yes)	pass via ENV or Jenkins credentials (abapCredentialsId)
workspace	yes
aUnitResultsFileName	no
aUnitTest	no
atcCheck	no
atcResultsFileName	no
atcVariant	no
commit	no
queryParameters	no
scope	no
skipSSLVerification	no
verbose	no	activates debug output

Overview - Execution Environment

Orchestrator-specific only

These parameters are relevant for orchestrator usage and not considered when using the command line option.

Name	Mandatory	Additional information

Details

aUnitResultsFileName

Specifies an output file name for the results of the ABAP Unit tests.

back to overview

Scope	Details
Aliases	-
Type	string
Mandatory	no
Default	AUnitResults.xml
Secret	no
Configuration scope	☒ parameter ☐ general ☒ steps ☒ stages
Resource references	none

aUnitTest

Indication whether you want to execute the ABAP Unit tests. If the ABAP Unit tests fail, the results are mapped as follows to the statuses available in the Jenkins plugin. (Successful ABAP unit test results are not displayed.)
- Failed with severity fatal is displayed as an Error.
- Failed with severity critical is displayed as an Error.
- Failed with severity warning is displayed as a Warning.

back to overview

Scope	Details
Aliases	-
Type	bool
Mandatory	no
Default	true
Possible values	- true - false
Secret	no
Configuration scope	☒ parameter ☐ general ☒ steps ☒ stages
Resource references	none

atcCheck

Indication whether you want to execute the ATC checks. If the ATC checks result in errors with priorities 1 and 2, they are considered as failed. The results are mapped as follows to the statuses available in the Jenkins plugin. (Successful ATC check results are not displayed.)
- Priorities 1 and 2 are displayed as an Error.
- Priority 3 is displayed as a Warning.

back to overview

Scope	Details
Aliases	-
Type	bool
Mandatory	no
Default	true
Possible values	- true - false
Secret	no
Configuration scope	☒ parameter ☐ general ☒ steps ☒ stages
Resource references	none

atcResultsFileName

Specifies an output file name for the results of the ATC checks.

back to overview

Scope	Details
Aliases	-
Type	string
Mandatory	no
Default	ATCResults.xml
Secret	no
Configuration scope	☒ parameter ☐ general ☒ steps ☒ stages
Resource references	none

atcVariant

Variant for ATC checks

back to overview

Scope	Details
Aliases	-
Type	string
Mandatory	no
Default	DEFAULT
Secret	no
Configuration scope	☒ parameter ☐ general ☒ steps ☒ stages
Resource references	none

client

Client of the ABAP system in which you want to execute the checks

back to overview

Scope	Details
Aliases	-
Type	string
Mandatory	yes
Default	$PIPER_client (if set)
Secret	no
Configuration scope	☒ parameter ☐ general ☒ steps ☒ stages
Resource references	none

commit

ID of the commit that triggered the pipeline or any other commit used to calculate the object scope. Specifying a commit is mandatory for the remoteChangedObjects and remoteChangedPackages scopes.

back to overview

Scope	Details
Aliases	-
Type	string
Mandatory	no
Default	$PIPER_commit (if set)
Secret	no
Configuration scope	☒ parameter ☐ general ☒ steps ☒ stages
Resource references	none

host

Protocol and host of the ABAP system, including the port. Please provide it in the format <protocol>://<host>:<port>. Supported protocols are http and https.

back to overview

Scope	Details
Aliases	-
Type	string
Mandatory	yes
Default	$PIPER_host (if set)
Secret	no
Configuration scope	☒ parameter ☐ general ☒ steps ☒ stages
Resource references	none

password

Password of the ABAP user that authenticates to the ABAP system. Note - Don´t provide this parameter directly. Either set it in the environment, or in the Jenkins credentials store, and provide the ID as value of the abapCredentialsId parameter.

back to overview

Scope	Details
Aliases	-
Type	string
Mandatory	yes
Default	$PIPER_password (if set)
Secret	yes
Configuration scope	☒ parameter ☐ general ☒ steps ☒ stages
Resource references	Jenkins credential id:   id: abapCredentialsId   reference to: password

queryParameters

Add query parameters (for API requests) that apply to all endpoints of the step. Provide the parameters as key-value pair map in the format <query parameter>:<value>.

back to overview

Scope	Details
Aliases	-
Type	map[string]interface{}
Mandatory	no
Default	$PIPER_queryParameters (if set)
Secret	no
Configuration scope	☒ parameter ☐ general ☒ steps ☒ stages
Resource references	none

repository

Name (ID) of the local repository on the ABAP system

back to overview

Scope	Details
Aliases	-
Type	string
Mandatory	yes
Default	$PIPER_repository (if set)
Secret	no
Configuration scope	☒ parameter ☐ general ☒ steps ☒ stages
Resource references	none

scope

Scope of objects for which you want to execute the checks:
- localChangedObjects: The object scope is derived from the last activity in the local repository. The checks are executed for the individual objects.
- remoteChangedObjects: The object scope is the delta between the commit that triggered the pipeline and the current commit in the remote repository. The checks are executed for the individual objects.
- localChangedPackages: The object scope is derived from the last activity in the local repository. All objects are resolved into packages. The checks are executed for the packages.
- remoteChangedPackages: The object scope is the delta between the commit that triggered the pipeline and the current commit in the remote repository. All objects are resolved into packages. The checks are executed for the packages.
- repository: The object scope comprises all objects that are part of the local repository. The checks are executed for the individual objects. Packages (DEVC) are excluded. This is the default scope.
- packages: The object scope comprises all packages that are part of the local repository. The checks are executed for the packages.

back to overview

Scope	Details
Aliases	-
Type	string
Mandatory	no
Default	repository
Secret	no
Configuration scope	☒ parameter ☐ general ☒ steps ☒ stages
Resource references	none

script

Jenkins-specific: Used for proper environment setup.

The common script environment of the Jenkinsfile running. Typically the reference to the script calling the pipeline step is provided with the this parameter, as in script: this. This allows the function to access the commonPipelineEnvironment for retrieving, e.g. configuration parameters.

back to overview

Scope	Details
Aliases	-
Type	Jenkins Script
Mandatory	yes
Default
Secret	no
Configuration scope	☐ parameter ☐ general ☐ steps ☐ stages
Resource references	none

skipSSLVerification

Skip the verification of SSL (Secure Socket Layer) certificates when using HTTPS. This parameter is not recommended for productive environments.

back to overview

Scope	Details
Aliases	-
Type	bool
Mandatory	no
Default	false
Possible values	- true - false
Secret	no
Configuration scope	☒ parameter ☐ general ☒ steps ☒ stages
Resource references	none

username

User that authenticates to the ABAP system. Note - Don´t provide this parameter directly. Either set it in the environment, or in the Jenkins credentials store, and provide the ID as value of the abapCredentialsId parameter.

back to overview

Scope	Details
Aliases	-
Type	string
Mandatory	yes
Default	$PIPER_username (if set)
Secret	yes
Configuration scope	☒ parameter ☐ general ☒ steps ☒ stages
Resource references	Jenkins credential id:   id: abapCredentialsId   reference to: username

verbose

verbose output

back to overview

Scope	Details
Aliases	-
Type	bool
Mandatory	no
Default	false
Possible values	- true - false
Secret	no
Configuration scope	☒ parameter ☒ general ☒ steps ☒ stages
Resource references	none

workspace

Absolute path to the directory that contains the source code that your CI/CD tool checks out. For example, in Jenkins, the workspace parameter is /var/jenkins_home/workspace/<jobName>/. As an alternative, you can use Jenkins's predefined environmental variable WORKSPACE.

back to overview

Scope	Details
Aliases	-
Type	string
Mandatory	yes
Default	$PIPER_workspace (if set)
Secret	no
Configuration scope	☒ parameter ☐ general ☒ steps ☒ stages
Resource references	none

abapCredentialsId

Jenkins-specific: Used for proper environment setup. See using credentials for details.

ID taken from the Jenkins credentials store containing user name and password of the user that authenticates to the ABAP system on which you want to execute the checks.

back to overview

Scope	Details
Aliases	-
Type	string
Configuration scope	☒ parameter ☒ general ☒ steps ☒ stages

Example

Example configuration for the use in a Jenkinsfile.

gctsExecuteABAPQualityChecks(
  script: this,
  host: 'https://abap.server.com:port',
  client: '000',
  abapCredentialsId: 'ABAPUserPasswordCredentialsId',
  repository: 'myrepo',
  scope: 'remoteChangedObjects',
  commit: "${env.GIT_COMMIT}",
  workspace: "${WORKSPACE}",
  queryparameters: [saml2: 'disabled']

  )

Example configuration for the use in a .yaml config file (such as .pipeline/config.yaml).

steps:
  <...>
  gctsExecuteABAPQualityChecks:
    host: 'https://abap.server.com:port'
    client: '000'
    abapCredentialsId: 'ABAPUserPasswordCredentialsId'
    repository: 'myrepo'
    scope: 'remoteChangedObjects'
    commit: '38abb4814ae46b98e8e6c3e718cf1782afa9ca90'
    workspace: '/var/jenkins_home/workspace/myFirstPipeline'
    queryparameters:
        saml2: "disabled"

Example configuration with the repository scope defined. Here, you don´t need to specify a commit. This sample configuration can also be used with the packages scope.

steps:
  <...>
  gctsExecuteABAPQualityChecks:
    host: 'https://abap.server.com:port'
    client: '000'
    abapCredentialsId: 'ABAPUserPasswordCredentialsId'
    repository: 'myrepo'
    scope: 'repository'
    workspace: '/var/jenkins_home/workspace/myFirstPipeline'

Example configuration when you want to execute only ABAP Unit tests.

steps:
  <...>
  gctsExecuteABAPQualityChecks:
    host: 'https://abap.server.com:port'
    client: '000'
    abapCredentialsId: 'ABAPUserPasswordCredentialsId'
    repository: 'myrepo'
    atcCheck: false
    scope: 'packages'
    workspace: '/var/jenkins_home/workspace/myFirstPipeline'

Example configuration for the use of the recordIssue step in a Jenkinsfile to make the check results visible in the Warnings-Next-Generation Plugin in Jenkins.

stage('ABAP Unit Tests') {
  steps{

   script{

     try{
           gctsExecuteABAPQualityChecks(
              script: this,
              commit: "${env.GIT_COMMIT}",
              workspace: "${WORKSPACE}")
        }
          catch (Exception ex) {
            currentBuild.result = 'FAILURE'
            unstable(message: "${STAGE_NAME} is unstable")
             }

        }
      }
    }
stage('Results in Checkstyle') {
  steps{

     recordIssues(
          enabledForFailure: true, aggregatingResults: true,
          tools: [checkStyle(pattern: 'ATCResults.xml', reportEncoding: 'UTF8'),checkStyle(pattern: 'AUnitResults.xml', reportEncoding: 'UTF8')]
       )

      }
    }

}

Note: If you have disabled the atcCheck or aUnitTest parameters, you must also remove the corresponding ATCResults.xml or AUnitResults.xml from the recordIssues step. In the example below, the atcCheck is disabled. Therefore, the ATCResults.xml is missing.

recordIssues(
  enabledForFailure: true, aggregatingResults: true,
  tools: [checkStyle(pattern: 'AUnitResults.xml', reportEncoding: 'UTF8')]

)