Jenkins CI integration

Jenkins CI is a popular continuous integration tool. Coco can be run under Jenkins, and the changes of the coverage over time displayed by a plugin. The following sections describe the necessary setup.

Prerequisites

Getting a license

The Jenkins process typically runs under a different user, such as jenkins on Linux or SYSTEM on Windows. Therefore, when Coco runs under a different user, initially there will be no Coco license configured or available.

How to get this license is described in the following section. The section after that one describes the use of a license server.

Installing a node-locked license

In order to generate the license, the Coco license tools need to be run from the jenkins account. There are two ways to do it, depending on whether the Jenkins server has an Internet connection.

• With an Internet connection:

  You need to get an activation code from froglogic. With this activation code, create a new Jenkins project that only runs (under Microsoft^® Windows) the command:

  <Windows Coco>\cocolic --fetch-license-key=<activation code>

  Under Linux™ and macOS, this line becomes:

  <cocobin>/cocolic --fetch-license-key=<activation code>

  Note: <cocobin> is the directory that contains the Coco binaries. Under Linux, this is usually /opt/SquishCoco/bin, while under macOS it is /Applications/SquishCoco.

  If the Jenkins server is connected to the Internet through a proxy, additional options are needed to specify the proxy. See cocolic – license activation for the details.

  Now build this project. In the console output window page of Jenkins, you can then see whether cocolic was successful.

• Without an Internet connection:

  Here you create a machine ID offline, and from that ID froglogic creates a license key. This key is then installed on the server in a second step.

  To create a machine ID, create a Jenkins project that executes (under Windows) the following command:

  <Windows Coco>\cocolic --machine-identifier

  Under Linux and macOS, this becomes:

  <cocobin>/cocolic --machine-identifier

  When this project is built, the console output of the build contains the machine ID.

  Send the machine ID to froglogic. We will send you a license key. Now create a Jenkins project that only contains the following command, and build it:

  <Windows Coco>\cocolic --license-key=<your key>

  Under Linux™ and macOS, this becomes:

  <cocobin>/cocolic --license-key=<your key>

Using a license server

To use Coco with a license server, create a new Jenkins CI project, which only runs (under Microsoft Windows) the following command:

<Windows Coco>\cocolic --license-server=<host>:<port>

where <host> and <port> refer to the license server (see cocolic – license activation). The colon and the port can be omitted if the default port is used.

Under Linux and macOS, this becomes:

<cocobin>/cocolic --license-server=<host>:<port>

Then the license is installed.

Getting an EMMA plugin

Coco uses the EMMA-XML format to communicate the coverage results to Jenkins. Jenkins needs a plugin to display EMMA data. We use a fork of the EMMA plugin which you can get from the Coco Download Center. It is packaged as a Jenkins plugin, in a file called cocoemma-latest.hpi, which you can install into Jenkins from the Advanced tab, Deploy Plugin action in the Jenkins Plugin Manager.

Installing Jenkins EMMA plugin

Adaption of the project to Jenkins

We will assume here that you can already compile and run your project under Jenkins, and that you can also generate coverage information, but not yet under Jenkins.

With the license installed, code coverage should now work under Jenkins.

The build process must now be configured in such a way that a single .csmes file is generated that contains all the execution data. This is done with cmcsexeimport.

Now extend your build process such that at the end a report in EMMA-XML format is generated. This is done by calling

<Windows Coco>cmreport -m project.csmes --emma=report.xml

where project.csmes must be replaced with the name of your results file.

We then use the plugin to display data from the file report.xml. To do this, select the configuration section of your Jenkins project and add a post-build action. Since the plugin is installed, the Add post-build action menu contains an entry Record Emma coverage report. Select it, and in the field Folders or files containing Emma XML reports enter report.xml.

After the next build, a coverage report will be generated.

Generating a coverage report from report.html with Jenkins CI

Assuming that the build is started, runs, and is successful, and the Emma XML report can be found by the plugin, we should see something like this:

The Coverage Report button

We can now click on the Coverage Report button to see the coverage results. The XML data is presented in a table with progress bars.

Jenkins EMMA Coco coverage report