Jenkins CI integration

Jenkins CI is a popular continuous integration tool. Squish Coco can be run under Jenkins, and the changes of the coverage over time displayed by a plugin. This chapter describes the necessary setup.

Prerequisites

Getting a license

The Jenkins process runs under an own account, usually called "jenkins". When therefore Squish Coco runs under Jenkins CI with a node-locked license, it needs a specific license for its account.

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 Squish 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

    Note: <cocobin> stands for the directory with the Squish Coco binaries. Under Linux™, this is usually /opt/SquishCoco/bin, while under macOS it is /Applications/SquishCoco.

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

    If the Jenkins server is connected to the Internet through a proxy, additional options are needed to specify the proxy. See Chapter (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 we 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, we 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

For the use of Squish Coco with a license server, one has to 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 therefore needs a plugin to display EMMA data. We use here the plugin at https://wiki.jenkins-ci.org/display/JENKINS/Emma+Plugin. Install it in Jenkins with the Jenkins plugin manager.

Adaption of the project to Jenkins

We will assume here that you 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 im 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 the data that were written to 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".

Then after the next build, a coverage report will be generated.

{fig:}

Generating a coverage report from report.html with Jenkins CI.

© 2022 The Qt Company Ltd. Documentation contributions included herein are the copyrights of their respective owners. The documentation provided herein is licensed under the terms of the GNU Free Documentation License version 1.3 as published by the Free Software Foundation. Qt and respective logos are trademarks of The Qt Company Ltd. in Finland and/or other countries worldwide. All other trademarks are property of their respective owners.