Quick Start - Jenkins
Overview
This guide explains how to use Diffblue Cover to write tests in Jenkins CI. 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
Diffblue Cover stored in the cloud for download along with the license key (or pre-installed and activated in your CI machines). See Installation.
To integrate Diffblue Cover into your CI pipeline, we will guide you through creating a Jenkinsfile that:
Builds your project
Downloads and activates Diffblue Cover CLI
Runs Diffblue Cover to create tests
Commits the created tests to a branch
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. Building 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.
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 your Diffblue Cover did not succesfully activate, this is out of the scope of this tutorial. See the Jenkins documentation, or you may need to double-check your project configuration.
2. Downloading and activating Diffblue Cover CLI
You need to give the CI run access to the Diffblue Cover 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 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 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.
Append the code for getting, unzipping and activating dcover
to the shell script in the Jenkinsfile.
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 DCOVER_SCRIPT_LOCATION
.
Push the changes so that CI is triggered - ensure that you can see the successful activation of dcover
in your "Use dcover create in Jenkins" stage before moving on. You will see a line starting with "Successfully activated key" if this was successful. If your Diffblue Cover did not successfully activate, please see Licensing or contact Diffblue Support.
3. Running Diffblue Cover CLI to create tests
Now that Diffblue Cover is running in Jenkins, you can use it to write tests. In the script started above in the Jenkinsfile, append the following. Note that the --batch
option makes the output more suitable for CI, as it ensures the CI logs are not cluttered with progress bar output.
Push the changes so this pipeline runs. Once successfully complete, you should expect to see output that looks like this in your "Use dcover create in Jenkins" stage:
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.
Depending on the size of your module/project, creating tests could take a while. You may wish to restrict test creation to a single class by specifying its fully qualified name:
4. Committing the created tests to a branch
To see the new tests created in the previous step in your project you need to commit them and push back to the repository. Assuming your Jenkins sever is already configured to allow you to push changes, you will need to configure your Git credentials. We recommend creating a service account for this.
To commit the tests append the following to your script. This will check for any changes to Diffblue tests, add them to a commit and push to your branch.
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:
Export a patch file with the new tests as an artifact for the user to use locally.
Set up a job that a user can trigger that pushes the Diffblue tests back to the change branch as a Jenkins freestyle project.
Trigger the above job using a webhook for every pull request in a Jenkins multi-branch declarative pipeline.
Last updated