Best Practices

Starting Headless Code Coverage Collector

There are two options for starting the Headless Code Coverage Collector:

The started task is recommended when you do not want individual users opening ports and to ensure that all users can share a single instance of the collector. Users are not required to start and stop the CLI. Use the headless parameter allowoutputlocation carefully. This option allows to specify output in their startup key and you will need to ensure that the user id running the task has appropriate permission to allow creating directories. Its also recommended that you enable code coverage service for the collector running in the started task.

Running the headless collector via CLI is recommended as part of a pipeline because the output directory and export formats can be specified at startup. The pipeline should also include a stop command for the headless code coverage instance.

Integrating with SonarQube

The Headless Code Coverage collector and ccexport.sh command both support exporting into SonarQube formats.

The easiest way to get SonarQube reports is to specify the appropriate parameter -e=SQ when you start the collector. This will notify the collector to generate a SonarQube report for each session. Effectively, every test case run by the TAZ CLI will produce its own SonarQube report.

If you are planning on using the ccexport.sh command at the end of a pipeline run to merge several code coverage results, you can choose defer the generation of SonarQube reporting to this step. Specify ccexport.sh with the -e=SQ parameter, and a single SonarQube report will be generated for the merged result.

How to integrate with Jenkins

There are many Jenkins plug-ins for code coverage, however it is important to pick a plug-in that supports one of the formats that Headless Code Coverage Collector uses. The Jenkins Coverage Plugin can consume Cobertura reports, and can help provide the desired integration. Ensure that the correct option is provided to the collector.

How PDF reports can be used for custom pipelines

If you do not have a pipeline or build tool that supports the SonarQube or Cobertura integration, you can use the ccexport.sh command to merge all the results produced by the Headless Code Coverage Collector with the -e=PDF parameter to produce a PDF report that can be viewed with any PDF viewer, and attached to any build results.

Merging Results

Headless Code Coverage Collector will generate a code coverage result for each test case that is run. This can generate many coverage result files and depending on the tooling being used to consume those results, a single result at the end of the run may be desirable. In this circumstance, using ccexport.sh command to merge results is recommended. The command can also be used to produce a single SonarQube, PDF or Cobertura result for the merged result.

Using a certificate for authentication

When Headless Code Coverage Collector is started, it will try to accept any incoming TCPIP communications. If the are not from the z/OS Debugger, it will be refused, however if you are running the collector in a pipeline, you may want to ensure only code coverage sessions from Dynamic Test Engine (z/OS Debugger) for that specific run are accepted. A certificate can be used to accomplish this. When the collector is started with a certificate, only connections with the same certificate are allowed. You will need to create a certificate, keystore, and start the collector with the -u or -authkeystoreproperties parameters see Enabling authentication. To make the unit test CLI work with the collector, ensure you use the -cs or –codeCoverageCertificate parameter.