Knowledge Base > Cover in the CI Pipeline > 2. Quick Start Guide

Quick Start Guide

Overview

This quick start guide will be your first step to take you through how to use Diffblue Cover to write tests in Jenkins CI by creating a Jenkinsfile that:

1) Builds your project

2) Downloads and unzips dcover

3) Activates dcover

4) Calls dcover create

This guide assumes that you have:

1) A Maven or Gradle project that:

  1. Compiles
  2. Does not have non-compiling or failing tests
  3. Triggers Jenkins CI on push or pull request with a declarative Jenkinsfile

2) A basic understanding of Jenkins

3) The ability to add credentials to and generally manage the Jenkins server

4) Diffblue Cover stored in the cloud for download along with the license key (or pre-installed and activated into your CI machines). See here.

After completing this guide, you can continue on to further examples for getting Diffblue Cover into your CI pipeline in an automated way.

Getting your first Diffblue tests on CI

Build the project

In your Jenkinsfile, add the Jenkins stage Use dcover create in Jenkins to the Jenkinsfile. Make sure to check, and if necessary modify, the build command to build your project. Running the project’s tests is not required and you will save time by skipping them, but they do need to compile and pass.

pipeline {
    agent any

    stages {
        stage('Use dcover create in Jenkins') {
            steps {
                sh '''
                    echo "Build project, you may need to update this to reflect your project"
                    mvn clean install -DskipTests
                '''
            }
        }
    }

}

Push this change so that CI is triggered. When this runs on Jenkins, you should see in the console log that the project has successfully built. If this is not working, this is out of the scope of this tutorial. See the Jenkins documentation, or you may need to double-check your project configuration.

Get and activate Cover

You need to give the CI run access to the dcover files and activate the dcover license in order to write tests.

This guide assumes that you have a URL with the Diffblue Cover CLI release zip and the license key for online activation during the CI run. Alternatively, it can be pre-installed on the machines running CI with online activation. See the separate page on 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 the Diffblue Cover licensing documentation.

Add secret text credentials with id diffblue-cover-release-url and set the value to the URL of the Diffblue Cover CLI release zip file. Then add secret text credentials with id diffblue-cover-license-key and set the value to your Diffblue Cover license key.

Then add this environment section to your Jenkinsfile.

environment {
    DB_RELEASE_URL = credentials('diffblue-cover-release-url')
    DB_LICENSE_KEY = credentials('diffblue-cover-license-key')
}

Append the code for getting, unzipping and activating dcover to the shell script in the Jenkinsfile.

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

                ...

                echo "Get and unzip dcover jars into directory dcover, store dcover script location for later use"
                mkdir --parents dcover
                wget "$DB_RELEASE_URL" --output-document dcover/dcover.zip --quiet
                unzip -o dcover/dcover.zip -d dcover
                DCOVER_SCRIPT_LOCATION="dcover/dcover"

                echo "Activate dcover"
                "$DCOVER_SCRIPT_LOCATION" activate "$DB_LICENSE_KEY"

            '''
        }
    }
}

This will put the dcover files into the directory dcover in the root of the workspace. The dcover files contain a script to invoke dcover and it has the relative path dcover/dcover. This is stored in the variable DCOVER_SCRIPT_LOCATION.

Push the changes so that CI runs and ensure that you can see the successful activation of dcover before moving on. If this is not working, please see the Diffblue Cover licensing documentation or contact Diffblue Support.

Writing tests with Diffblue Cover

Now that Diffblue Cover is installed in CI, you can use it to write tests. The next two sections show how to write tests for a single module and then how to extend this to all modules.

Single module

Choose a module to test in your project. In the script started above in the Jenkinsfile, append the following - changing moduleToTest to a module in your project, or if your project does not have modules --working-directory moduleToTest can be removed or moduleToTest can be changed to ".". The option --batch makes the output more suitable for CI, as it ensures the CI logs are not cluttered with progress bar output.

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

                echo "Running dcover with create on create, you may need to update this to reflect your project"
                "$DCOVER_SCRIPT_LOCATION" create --working-directory "moduleToTest" --batch

            '''
        }
    }
}

Push the changes so that CI runs. Once successfully complete, you should expect to see output that looks like this:

INFO  Found 7 callable methods in 2 classes
INFO
INFO  Creating tests:
INFO  ---------------
...
INFO  All 5 created tests were successfully validated.

If you do not see this, the call may need tweaking for your project or dependencies adding until it works. The output gives you warnings along the way to guide you. See the Diffblue Cover CLI documentation.

Depending on the size of your module/project, this could take a while. You may wish to restrict to a single class by specifying its fully qualified name:

"$DCOVER_SCRIPT_LOCATION" create com.somepackage.SomeClass --working-directory "moduleToTest" --batch

All modules

To get tests for all the modules, add calls to dcover for each module. For example:

"$DCOVER_SCRIPT_LOCATION" create --working-directory "moduleToTest" --batch
"$DCOVER_SCRIPT_LOCATION" create --working-directory "anotherModuleToTest" --batch
"$DCOVER_SCRIPT_LOCATION" create --working-directory "yetAnotherModuleToTest" --batch

What’s next

It is possible to integrate Diffblue Cover completely automatically into your CI workflow. Listed here are ideas and examples, each building on another, for what to try next:

1) Export a patch file with the new tests as an artifact for the user to use locally

2) Set up a job that a user can trigger that pushes the Diffblue tests back to the change branch as a Jenkins freestyle project.

3) Trigger the above job using a webhook for every pull request in a Jenkins multi-branch declarative pipeline