Atlassian Bamboo integration

Atlassian Bamboo is a continuous integration server used to build, test and release software. The Coco plug-in provides seamless integration with Bamboo. Users can add one or more Coco tasks to a Bamboo job. Each Coco task can perform the following actions:

1. Import an execution report into an instrumentation database.
2. Merge several instrumentation databases.
3. Generate a code coverage report.

The user can choose one, two, or all three actions to be performed. If more than one action is chosen, they are executed in the order mentioned above.

Coco task configuration overview

After the actions have ended, files that are created by Coco (like the coverage report), can be stored to allow efficient troubleshooting.

Agent configuration

An agent is a service that runs Bamboo builds, tests and deployments. The Agent Capabilities setting lets users specify which agents are capable of running Coco jobs. In order to execute it, we must first install Coco at the agent host. Then we need to set up an agent-specific capability called coco with Coco installation directory as a value in the configuration entry Bamboo administration > BUILD RESOURCES > Agents > AgentName > Agent-specific capabilities.

Later, during the job configuration, we need to set the existence of a coco capability as a job requirement. This way, Coco jobs will be executed only on agents on which Coco is installed.

Importing an execution report

This action calls cmcsexeimport to import the execution report (.csexe file) into an instrumentation database (.csmes file). The user needs to provide an absolute or relative path (from the Bamboo build directory) to the .csexe and the .csmes file, and also a title for the execution.

When this action is activated, the following command is executed on the agent host:

cmcsexeimport --debug --title=<Title> -m <CSMesFile> -e <CSExeFile>

Merging the instrumentation databases

This action calls cmmerge to merge several instrumentation databases (.csmes files). We must provide a full or relative path to the resulting .csmes output file. If we provide a relative path (or just a filename), then the .csmes output file will be generated relative to the Bamboo working directory. The .csmes input files need to be specified. Multiple files can be used, separated by a comma.

When this action is activated, the following command will be executed on the agent host:

cmmerge --verbose -o <CSMesOutputFile> <CSMesInputFile1> ... <CSMesInputFileN>

Additionally, the user can select the option merge only instrumentations and executions present in the reference file. This option is useful for importing .csmes files with unit tests. When the option is selected, the user must provide the name of a .csmes reference file. This will cause the cmmerge command to be executed with the additional option -i:

cmmerge --verbose -o <CSMesOutputFile> -i <CSMesInputFile1> ... <CSMesInputFileN>

Generating the coverage report

The last action generates an HTML report by running cmreport. We need to provide a .csmes file name (either absolute or relative path). The .csmes file must contain the previously imported execution report (i.e. by using the first action offered by the plugin).

cmreport --title=<BambooJobName> -m <CSMesFile> --debug --html=coco/report.html

The generated report will be stored in the coco subdirectory, therefore we can define Artefact with coco/** as the copy pattern. This allows us to view the report directly in Bamboo after job execution. The report title is built using a Bamboo job name.

Examples

A coverage report from a single execution

First, we need to activate the action Import an execution report into an instrumentation database to import the execution report (.csexe file) into an instrumentation database (.csmes file). Finally, we need to activate the third action, Generate code coverage report. The .csexe file for this action is the same as for first action.

Coco task configuration for example addressbook application

Coverage report for unit tests

In this scenario we would like to generate a coverage report for unit tests execution. To achieve this goal in Bamboo, we need a job that consists of two Coco tasks.

After the build of the program which is being tested, we have two .csmes files: one for the application and another for the unit tests. We need to merge those instrumentation databases where the .csmes file for the application will be a reference during the merge. The merge step creates a new .csmes file as its output file. This is done in the following task:

Coco task configuration to merge unit test executions

In the second task, the execution report for the unit tests is imported into a .csmes file (which was the .csmes output file of the previous task). The last action in the task, Generate code coverage report, generates an HTML report.

Coco task configuration for importing execution and generating report