Starting and stopping the headless code coverage collector

About this task

Headless mode enables you to run the code coverage collection without an UI. This mode is ideal for environments where an UI workbench is not installed, or when you initiate a run from the command line or as a started task. For more information on running the collector as a started task, see Running Headless Code Coverage Collector as a started task.

You can choose to run the collector either from the command line or as a started task depending on the user preferences and the structure of the build pipeline. Factors such as whether the collector is triggered during the build process or which tools are integrated into the pipeline can influence this decision.

Notes:

Headless code coverage is not available on macOS.
The Headless Code Coverage Collector on Windows and Linux is deprecated. Use the headless code coverage collector on z/OS.

The Headless Code Coverage Collector runs a daemon that listens for an incoming connection in the same way that the UI uses a debug daemon. Start or run your application like you do for code coverage capture in the UI but use the IP/Host:port of the Headless Code Coverage Collector . For more information, see Generating code coverage in headless mode using the collector.

Note: By default, the results are stored in the root of the user's home directory under the CC folder. You can use the -output parameter to change the default setting.

The syntax diagram for the codecov command is shown below. You can use either the single letter parameter or the complete one for each option. All parameters and values are case-sensitive.

Options list

Format: codecov [options]

-a,allowoutputlocation=<TRUE|FALSE>

Indicates whether -o,output is allowed in the startup key. The default is FALSE.

-A,applid=<applid>

The APPLID parameter used in bearer authentication generates and authenticates bearer tokens on headless code coverage service on z/OS.

-b,enablebasicauth=<TRUE|FALSE>

Enables basic authentication on headless code coverage service on z/OS. The default is FALSE.

-C,startupcommandlist=<path>

Specifies a file that contains commands that will be sent to the debug engine at startup.

-c,singleconnect

Exits after a single daemon connection (must use with -startDaemon).

-D,stopdaemon=<port>

Stops the daemon that is listening on the port.

-d,startdaemon

Starts in daemon mode and wait for connections. If -port is not specified, the next available port is used. The port number used is displayed in the console.

-E,ignoreerrors

Results will be produced even if errors occur during the session. The results may be incomplete.

-e,exportertype=<CCSONARQUBE|SQ|CCPDF|PDF|CCCOBERTURA|COB>

Specifies the export format for code coverage data. You can specify multiple export types by using a comma between export formats.

-e,exportertype=CCSONARQUBE or -e,exportertype=SQ produces the SonarQube format with the .xml extension. Each test result is contained in a unique subdirectory.
-e,exportertype=CCPDF or -e,exportertype=PDF produces the PDF format with the .pdf extension. By default, source is included in the PDF report. To exclude source from the report, specify -s,savesource=false.
-e,exportertype=CCCOBERTURA or -e,exportertype=COB produces the Cobertura format with the .xml extension. Each test result is contained in a unique subdirectory.

-f,optionsfile=<path>

Reads command arguments from the specified options file.

-G,exportencoding=<encoding>

Specifies an encoding for source when you export in the SonarQube format. By default, UTF-8 is specified.

This parameter is valid only when -e,exportertype=CCSONARQUBE is specified.

-g,tag="text"

Specifies a tag that is associated with the CC results. e.g., test ID.

-h,help

Prints the help screen.

-I,moduleincludelist=<path>

Deprecated. Use -R,filter=<filters> or -r,filterlist=<path> instead.

Specifies a file that contains a list of module names or regular expressions that will cause matching module names to be included in code coverage. The module include parameter overrides the module exclude parameter.

-i,moduleinclude=<module_list>

Deprecated. Use -R,filter=<filters> or -r,filterlist=<path> instead.

Comma-separated list of module names or regular expressions that will include modules in code coverage. The module include parameter overrides the module exclude parameter.

-k,ccskeystoreproperties=<path>

Starts CCS in secure mode with the settings provided in the keystore properties file. The keystore properties file must contain the path to a valid keystore file (ccskeystorefile) and the password (ccskeystorepassword). The keystore password can be encrypted using the z/OS Debugger Password File Generator to prevent storage of plain text. See Generating secure keystore passwords for code coverage. On Windows and Linux, a sample file, ccskeystoreinfo.properties is provided in the same directory as the codecov command. On z/OS this file is in the headless-code-coverage directory.

On Windows and Linux, you can find a sample file in <install_location>/headless-cc/ccskeystoreinfo.properties

On z/OS, you can find a sample file in /usr/lpp/IBM/debug/headless-code-coverage/ccskeystoreinfo.poperties

Note: For the Windows, special characters inside the properties file must be escaped using a backslash. For example: ccskeystorefile=C\:\\headless-cc\\keystore.jks.

-K,daemonkeystoreproperties=<path>

Starts the code coverage daemon in secure mode with the settings provided in the keystore properties file. The keystore properties file must contain the path to a valid keystore file (keystorefile) and the password (keystorepassword). The password must be generated using the z/OS Debugger Password File Generator. See Generating secure keystore passwords for code coverage and Generating secure keystore passwords for Remote Debug Service. On Windows and Linux, a sample file, keystoreinfo.properties is provided in the same directory as the codecov command. On z/OS this file is in the headless-code-coverage directory. When the code coverage daemon is used, the debug engine must also provide the appropriate credentials. See Enabling secure communication between z/OS Debugger and the remote debugger for incoming debug sessions.

Note: AT-TLS is not supported with headless code coverage.

-L,localonly

The daemon will only accept connections from the localhost.

-l,cclevel=<LINE|FUNCTION>

The code coverage level (either "LINE" or "FUNCTION").

-o,output=<path>

The directory to save code coverage result files. A result containing the program name and timestamp is created under the output directory for each session. A subdirectory is created when you export the result in the SonarQube or Cobertura format.

-O,root=<dirname>|<path>

Specifies a directory name or a fully qualified path to define the root location for source files included in code coverage.

-O,root=<dirname>: Sets the top-level directory for the source files included in the code coverage result.
-O,root=<path>: Removes the specified path from the resulting source file paths.

For example, if you start the collector with the -O,root option set to either one of the following formats:

root=projectA
root=/home/username

Then, you collect code coverage on a program that contains a source file located at:

/home/user/projectA/programA.cbl

The collector will output a code coverage result with the source file referenced using a relative path:

projectA/programA.cbl

-P,printparms

Prints a summary of the parameters specified.

-p,port=<port list>

The port number, port list(port,port) or port range(port-port) used by the debug daemon.

-R,filter=<filters>

Specifies a list of filters that are enclosed in single or double quotation marks. Use commas to separate the filters. The filters allow strings or regular expressions to include or exclude modules, parts, and files.

For more information, see Filtering code coverage results during collection.

-r,filterlist=<path>

Specifies a file that contains a list of filters to include or exclude module, parts, and files. Each filter appears on a separate line.

For more information, see Filtering results during collection in headless mode.

-S,ccsport=<port>

Starts Code Coverage Service (CCS) on the specified port. The code coverage collector and CCS will not start if the port is already in use.

When you run CCS with headless code coverage on z/OS, bearer or basic authentication is enabled. z/OS credentials are required to access the CCS REST API and authentication prompts will appear when you view the results in the Code Coverage Results view. Code coverage results are stored in user subdirectories and users only have access to their own results.

CCS uses the Jetty server to deliver REST API. By default, CCS configures the Jetty denial of service filter at 25 requests per second. You can override the default setting in one of the following ways:

For the Windows and Linux versions of the headless code coverage collector, modify the <install_location>/headless-cc/codecov.ini file and define the following system property in the -vmargs section:
```
-DCCSmaxRequestsPerSec=<desired_value>
```
For the z/OS headless code coverage collector, or when you use CCS with Remote Debug Service, you must set the environment variable OPENJ9_JAVA_OPTIONS with the java argument before you start headless code coverage:
```
export OPENJ9_JAVA_OPTIONS="$OPENJ9_JAVA_OPTIONS -DCCSmaxRequestsPerSec=<desired_value>"
```
For Remote Debug Service, see Customizing with the sample job EQARMTSU.

CCS also configures a QoS (quality of service) file with 20 concurrent requests. You can override the default setting in one of the following ways:

For the Windows and Linux versions of the Headless Code Coverage Collector , modify the <install_location>/headless-cc/codecov.ini file and define the following system property in the -vmargs section:
```
-DCCSmaxConcurRequests=<desired_value>
```
For the z/OS Headless Code Coverage Collector , you must set the environment variable OPENJ9_JAVA_OPTIONS with the java argument before you start headless code coverage:
```
export OPENJ9_JAVA_OPTIONS="$OPENJ9_JAVA_OPTIONS -DCCSmaxConcurRequests=<desired_value>"
```
For Remote Debug Service, see Customizing with the sample job EQARMTSU.

You can also further restrict CCS to only allow access using the IP name and not the IP address where CCS is running:

For the Windows and Linux versions of the headless code coverage collector, modify the <install_location>/headless-cc/codecov.ini
```
-Dccs_blockIPAccess=true
```
For the z/OS Headless Code Coverage Collector , you must set the environment variable OPENJ9_JAVA_OPTIONS with the java argument before you start headless code coverage:
```
export OPENJ9_JAVA_OPTIONS="$OPENJ9_JAVA_OPTIONS -Dccs_blockIPAccess=true"
```
For Remote Debug Service, see Customizing with the sample job EQARMTSU.

On Linux and Windows, Jetty expands web files to the temp directory. On z/OS, the files are stored in a hidden directory in the user's home directory. To override this, you can set the CCSworkdir environment value before you start the headless code coverage collector.

For example, on Linux and z/OS:

export CCSworkdir=/u/user/jettyfiles

In Windows command shell:

SET CCSworkdir=C:\jettyfiles

-s,savesource=<TRUE|FALSE>

Saves the source with the results. The default is TRUE. The value for this parameter also controls whether source appears with the PDF exporter. For example, if -savesource=TRUE is specified with -exportertype=CCPDF, source is included in the PDF report.

-T,timeout=<seconds>

Number of seconds to wait for a debug engine response before timing out. The default is 120 seconds. The session will terminate and results already captured will be saved. Specifying 0 (zero) will wait indefinitely.

-t,testid=<testid>

Results will be associated with the specified testid.

-u,authkeystoreproperties=<path>

Enables authentication checking for the code coverage collector daemon. The keystore properties file must contain the path to a valid keystore file (keystorefile) and the password (keystorepassword). The password must be generated using the z/OS Debugger Password File Generator. See Generating secure keystore passwords for code coverage and Generating secure keystore passwords for Remote Debug Service. On Windows and Linux, a sample file, keystoreinfo.properties is provided in the same directory as the codecov command. On z/OS this file is in the headless-code-coverage directory. When authentication is enabled, the certificate must also be provided when invoking the z/OS Debugger. See Enabling authentication for incoming TCP/IP connections

-v,view=<DEFAULT|SOURCE_ONLY|LISTING_ONLY|D|S|L>

Chooses the view to use when you save source.

DEFAULT or D uses whatever is the engine preferred view.
SOURCE_ONLY or S only allows source views to be included in code coverage collection.
LISTING_ONLY or L only allows listing views to be included in code coverage collection.

Notes:

DEFAULT and SOURCE_ONLY are the only supported view options. The SOURCE_ONLY support is available with z/OS Debugger 15.0.3 or later, with PTF UI77786 applied.
To collect source level code coverage with COBOL 6.2 and later, SOURCE_ONLY must be used.

-X,moduleexludelist=<path>

Deprecated. Use -R,filter=<filters> or -r,filterlist=<path> instead.

Specifies a file that contains a list of regular expressions that will cause matching module names to be excluded from code coverage.

-x,moduleexclude=<module_list>

Deprecated. Use -R,filter=<filters> or -r,filterlist=<path> instead.

Comma-separated list of module names or regular expressions that will exclude modules from code coverage.

-z,zunit=<modulename>|<modulename:csectname>

Indicates that the code coverage session is for a ZUnit test case or an IBM Test Accelerator for Z Early Development Testing Unit Test case. The output file name, test ID, and a filter will be initialized to match the specified module or CSECT name.

Note:

ZUnit feature on IBM® Developer for z/OS® is replaced by IBM Test Accelerator for Early Development Testing. Code coverage for unit tests is only available with that product. For more information, see Collecting code coverage for a unit test case - IBM Documentation.
If a filter or filterlist option is also specified, it will override the provided zunit filter.