Capturing code coverage using IDz is great when a developer wants to run individual test cases, but what if¬†there are¬†many test cases and they need to be run as part of a build?¬† Is there a way to collect code coverage data without having to start the IDz client?¬† Can I run the “collector” on a machine that does not have a UI?¬† The answer is YES and it is called the “Headless Code Coverage for IBM z/OS Debugger”.
Headless Code Coverage for IBM z/OS Debugger
Before I explain the term “Headless”, I need to describe how code coverage data is collected.¬† When a program is started with code coverage enabled, the debug engine (IBM z/OS Debugger) interacts with the code coverage collector built into IDz.¬† ¬†The collector writes out the code coverage data and at the end displays it in IDz.
The “Headless Code Coverage for IBM z/OS Debugger” has the exact same collector as IDz but with a difference.¬† ¬†It has no UI!¬† It can collect code coverage data and then write out the file(s) but it can’t display the results.
The term “Headless” in this context means that it doesn’t have a UI.¬† It doesn’t require a graphical user interface to run.
Being “Headless” gives it some special capabilities that¬†are not possible with the IDz client.
- Runs from a command line.
- Runs on a machine that doesn’t have a UI, e.g. a Linux VM.
- Runs on Linux, Windows AND z/OS.
- Additional¬†options to¬†customize the¬†capture of code coverage data.
- Run in the background independent of IDz.
The code coverage data captured can be imported and displayed in IDz.
Where is it installed?
Headless Code Coverage for IBM z/OS Debugger is not installed in IDz by default.¬† ¬†When installing IDz make sure to select the feature.
If you already have IDz installed, no problem, you can start Installation Manager and select “Modify” to¬†add the feature.
Once installed, the headless collector can be found¬†in a directory called “headless-cc” in the IDz install directory.
How do I¬†start it?
Similar to enabling the debug daemon in IDz, the headless collector has an option to start the daemon that will listen for incoming connections from the debug engine.
If you have a command window/Windows PowerShell/Lunix command shell in the headless-cc directory you can type¬†codecov to get a list of parameters.
I’m not going to get into all the different options in this post.¬† Some are obvious from the help shown and there is¬†more information available in the IDz online help.
I recommend using at least the following parameters:
-startdaemon¬†– starts listening for incoming connections from the debug engine.¬† ¬†This is the only required parameter to capture code coverage data.
-port=8006 – specifies the listening port.¬† If this parameter is not specified, then the next available port will be used.
The codecov command prints out the message CRRDG7026 <port>, that indicates the listening port.¬† By using a constant message id, scripts can look for the message to determine the port number.
-savesource – by default only code coverage data is collected.¬† By specifying this parameter, the source/listing that matches the code coverage data is also collected.
-zipresult – gathers the source and results into a single zip file with a .zip extension
In a future post, I’ll show the other ways that parameters can be specified.
Using the headless collector
Since the headless collector behaves just like IDz when it comes to collecting code coverage data, the modifications to JCL or wherever the connection information is specified, is small.
You will need 2 pieces of information
- <address>¬†IP or hostname of the machine running the headless collector.
There are several commands that will return the IPv4 address:
- ipconfig on windows or ifconfig on Linux
- ping -4 <hostname> on windows or ping <hostname> on Linux
- nslookup <hostname>
- <port> number that the headless collector is listening on (see message CRRDG7026 printed when¬†codecov is started)
NOTE: The headless collector does not support the DBM connection mode.¬† ¬†Use DIRECT or TCPIP in the TEST option.
//CEEOPTS DD *
//CEEOPTS DD *
Submit your JCL and the headless collector will indicate that a code coverage session has started/finished and where the results were stored.
The results were zipped and saved as shown above.
NOTE: By default the results are written to the¬†CC directory¬†in the user’s home directory.¬† This can be changed by adding¬†-output=<directory>¬†when starting codecov.
Displaying the results in IDz
I’ll finish up by showing an easy way to see these results in IDz.
- Open the “Code Coverage Results” view and click the¬†¬†to add a location.
By adding a location, any new results captured by the headless collector will show up in the view when it is refreshed.
- Enter the path to where the results are being written (in this example it is the default for the user id Administrator).
- Press OK.
- Expand the added location.
- Double click to open the results.
- Results are displayed in IDz.
IDz ships a headless (no UI required) version of the code coverage collector.¬† This headless collector has several advantages including the ability to run from the command line where there is no UI.¬† The headless collector is a perfect fit for integrating code coverage into builds or automated testing where starting an IDz client is difficult.¬† IDz can be used to display the results.
Make sure¬†to check out¬†the¬†announcement¬†for IBM Application Delivery Foundation for z Systems V3.1.1¬†where you will find new features for IDz and the headless collector.¬† ¬†For example the headless collector shipped with IDz V14.1.2 supports exporting to SonarQube.