Including Code Coverage in a Continuous Integration Process

The process for producing code coverage results (as binary .tcz results files) from applications running under a Continuous Integration (CI) system is the same as when running the application locally from the command line. You need to compile and execute the applications with test coverage - see To use test coverage from the command line.

Format of the results files

You would typically configure the CI machine to store the test coverage results as a CI artifact file for the CI build. Those results could be stored in one or more of the following formats:

Binary format - as a .tcz results file.
Tip: You can load .tcz files in Visual COBOL for Visual Studio 2022 to examine the results in greater detail.
HTML or TXT - report files produced as described in To create test coverage reports.
XML format - produced with the Test Coverage Utility Program (tcutil). You can use tcutil with different options depending on what
- Use the -x option:
```
tcutil -x myapp.xml myapp.tcz
```
  Produces an XML file, myapp.xml, which includes a summary of the test coverage results. In most cases, you muct include the stylesheets as artifact files alongside the XML file to ensure it is rendered correctly
  .
  Tip: Use a Third-Party XSLT processor such as Saxon or xsltproc to transform myapp.xml to an HTML page using the sample stylesheets mftchtml.xsl and mftchtml.css stored in <installdir>\src\tcov
- Using both the -x and -s options:
```
tcutil -x -s myapp.xsl myapp.tcz
```
  Produces an XML file, myapp.xml, that when displayed is an HTML page of results. The results on the HTML page are rendered using the sample stylesheets mftchtml.xsl and mftchtml.css stored in <installdir>\src\tcov.

See Test Coverage Utility Program (tcutil) for details.

Displaying the results in the CI

Consider installing a plugin in for your CI system to configure the CI build so that the results are displayed directly on the CI dashboard. An example of such plugin is Plot for Jenkins. Plot requires input in CSV format which it then visualizes on the Jenkins dashboard.

Use tcutil with the -x option and a Third-Party XSLT processor to transform the results file, myapp.xml, into a CSV file. See the sample file mftcplot.xsl in <installdir>\src\tcov.

Configuring the CI build to fail

You can use tcutil with the -t option to configure the CI build to fail if the overall test coverage fails to meet a certain threshold level (in percentage). In the following example, tcutil returns a non-zero exit code if the overall code coverage in the .tcz file is less than 80%:

tcutil -t 80 myapp.tcz

Note: On Windows, tcutil is implemented as a batch file. When invoking tcutil from within a batch file or CI command processor, you need to make a call to tcutil in order to execute it - for example:

call tcutil...