Quick Start - Jenkins

Overview

This guide explains how to use Diffblue Cover to write tests in Jenkins CI. Note that this guide focuses on the specifics of Jenkinsfile configuration, for more details on configuring Diffblue Pipeline for CI see Quick Start - General. This guide assumes that you have:

• A Maven or Gradle project that:

  • Compiles

  • Does not have non-compiling or failing tests

  • Triggers Jenkins CI on push or pull request with a declarative Jenkinsfile

• A basic understanding of Jenkins

• The ability to add credentials to, and generally manage, the Jenkins server

• Access to download Diffblue Cover along with the license key (or pre-installed and activated in your CI machines). See Installation. Note: alternatively access to download Docker files.

The rest of this guide assumes that you already have your project set to build (and test) in a CI environment. Typically, this would be a script that downloads your project from the repository, builds the project, and performs testing/checking. The steps below are to incorporate Diffblue Cover into this CI pipeline. If you are starting from scratch, you should do the above first to save trying to understand and configure your project and Diffblue Cover concurrently.

To integrate Diffblue Cover into your CI pipeline, we will guide you through creating a Jenkinsfile that adds the following to change request push events (not that configuration of the event/hook is not included on this page):

1. Configures and downloads Diffblue Cover CLI

2. Runs Diffblue Cover to:

   • build the project

   • activate your Diffblue Cover license

   • create tests

   • commit the created tests

   • push the tests back to the repository

Additionally this guide describes how to configure Diffblue Pipeline to integrate with Diffblue Cover Reports to upload coverage information. Report generation and upload should be performed on merge events, or on a regular basis (e.g. nightly).

The following sections provide more details for each of the above steps. After completing this guide, you can continue on to further examples of adding Diffblue Cover to your CI pipeline in an automated way.

1. Configuring and downloading Diffblue Cover CLI

Note that this section should be added into any step where you required Diffblue Cover CLI; this includes both writing tests and generating reports.

This section assumes you wish to install Diffblue Cover CLI into an existing agent /environment. If you wish to use Diffblue Cover CLI inside a Diffblue provided docker image, see the hint box at the end of the section. To configure Diffblue Cover CLI you will need to add some environment variables. This section introduces the minimal recommended for ease of configuration, for full details of available variables and their use see Environment configuration for CI.

This guide assumes that you have a URL with the Diffblue Cover CLI release zip (or you can use https://release.diffblue.com/cli/latest) and the license key for online activation during the CI run. Alternatively, Diffblue Cover CLI can be pre-installed on the machines running CI with online activation. See Installation. If the machines running CI are not able to access the internet for activation, pre-installing Diffblue Cover with offline activation may be possible if your license allows it. See Licensing.

Add a secret text credentials with id diffblue-cover-license-key and set the value to your Diffblue Cover license key.

environment {
    DIFFBLUE_RELEASE_URL = 'https://release.diffblue.com/cli/latest'
    DIFFBLUE_LICENSE_KEY = credentials('diffblue-cover-license-key')
}

In your Jenkinsfile, add the Jenkins stage Use dcover cli in Jenkins to the Jenkinsfile. Make sure to check, and if necessary modify, the download and install commands for your CI environment.

pipeline {
    agent any

    stages {
        stage('Use dcover cli in Jenkins') {
            steps {
                sh '''
                echo "Get and unzip dcover jars into directory dcover, store dcover script location for later use"
                mkdir --parents dcover
                wget "$DIFFBLUE_RELEASE_URL" --output-document dcover/dcover.zip --quiet
                unzip -o dcover/dcover.zip -d dcover
                DIFFBLUE_COVER_LOCATION="dcover/dcover"
                '''
            }
        }
    }

}

This will put the Diffblue Cover files into the dcover directory in the root of the workspace. The Diffblue Cover files contain a script to invoke dcover which has the relative path dcover/dcover. This is stored in the variable DIFFBLUE_COVER_LOCATION.

Diffblue Cover Docker agent

An alternative is to specify the Jenkins agent to use a Diffblue Cover CLI Docker image. The changes to the above configuration are as follows:

1. Replace the agent any with agent diffblue/cover-cli:latest-jdk17 or other Docker image. The other images are produced for each supported JDK version. Go to https://hub.docker.com/r/diffblue/cover-cli for details. Note: To use the latest version of Diffblue Cover, use one of the latest-jdk tags. To use a specific release version, use one of the yyyy.mm.dd-jdk tags.
2. The environment variable DIFFBLUE_RELEASE_URL is no longer required.

3. The above steps to download and install Diffblue Cover CLI are no longer be required.

2. Running Diffblue Cover CLI

Note that this section should be added into change request push events in your CI work flows.

As above, this section describes how to use the installed Diffblue Cover CLI on an existing agent. For the Diffblue Cover Docker agent, see the box at the end for changes.

Now that Diffblue Cover CLI is installed in Jenkins you can use it to: build the project; create tests; commit the created tests; and push the tests back to the repository. In the script started above in the Jenkinsfile, append the following.

stages {
    stage('Use dcover cli in Jenkins') {
        steps {
            sh '''
                ...

                echo "Running dcover to create and commit tests"
                "$DIFFBLUE_COVER_LOCATION" ci activate build validate create

            '''
        }
    }
}

This will:

• "$DIFFBLUE_COVER_LOCATION": Start Diffblue Cover.

• ci : Enable CI behavior and git integration using environment configuration described above.

• activate : Activate your Diffblue Cover license locally for use in CI.

• build: Build the project using standard maven or gradle commands. Note that the build argument can be omitted and the project built before running Diffblue Cover. This is advisable if the project has non-trivial build configuration or specification.

• validate : Validate existing Diffblue Cover tests and ensure they are updated.

• create : Create tests as per the mode configuration

Push the changes so this pipeline runs. Once successfully complete, you should expect to see output commits by Diffblue Cover CLI on the pull request adding tests to the branch.

If you don't see this output, the call may need small modification for your project or dependencies adding until it works. The output gives you warnings along the way to guide you. See CLI Commands for more information.

For more details on these commands and their tuning with various arguments see Commands & Arguments.

Diffblue Cover Docker agent

The only changes necessary are to replace "$DIFFBLUE_COVER_LOCATION" with dcover as the Docker image will already have Diffblue Cover CLI installed and on the path.

Note that Cover Reports integration with Diffblue Cover Pipeline is only supported for writing baseline tests. Generating coverage reports and uploading them from runs in skip or patch mode is unsupported and will yield incomplete report data.

Integrating with Diffblue Cover Reports

Note that this section should be added into change merge events in your CI workflows, or alternatively on a regular job such as a nightly or weekly build. The prerequisites for this is the 1. Configuring and downloading Diffblue Cover CLI section above.

Diffblue Cover can generate coverage reports for your project and upload them to your instance of Cover Reports. This is done with the following script

stages {
    stage('Generate dcover cover reports in Jenkins') {
        steps {
            sh '''
                ...

                echo "Running dcover to generate reports"
                "$DIFFBLUE_COVER_LOCATION" coverage-reports upload <Reports Server URL>

            '''
        }
    }
}

This will:

• "$DIFFBLUE_COVER_LOCATION": Start Diffblue Cover.

• coverage-reports : Create the coverage reports bundle to send to Reports

• upload : Upload the created reports bundle to the Reports server where<ReportsServerURL> is the URL of Cover Reports where the bundle will be uploaded.

Note that generating coverage reports should be performed as a separate step/action after test creation. It is possible to chain coverage-reports upload to the dcover ci command above, but this is not recommended.

Cover Reports must be installed on a server that is accessible from the CI runner.

Diffblue Cover Docker agent

The only changes necessary are to replace "$DIFFBLUE_COVER_LOCATION" with dcover as the Docker image will already have Diffblue Cover CLI installed and on the path.

For more details on these commands and their tuning with various arguments see Cover Reports Contributor