# 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](/features/cover-pipeline/cover-pipeline-for-ci/quick-start-guide-general.md). 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](/features/cover-pipeline/cover-pipeline-for-ci/installing-diffblue-cover-in-your-ci-environment.md).\ Note: alternatively access to download Docker files. {% hint style="info" %} 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. {% endhint %} 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](/features/cover-cli/commands-and-arguments/environment-configuration-ci.md). This guide assumes that you have a URL with the Diffblue Cover CLI release zip (or you can use ) 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](/features/cover-pipeline/cover-pipeline-for-ci/installing-diffblue-cover-in-your-ci-environment.md). 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](/get-started/licensing.md). 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. ```groovy 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`. {% hint style="info" %} **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 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. {% endhint %} ## 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. ```groovy 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](/features/cover-cli/commands-and-arguments.md). {% hint style="info" %} **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. {% endhint %} {% hint style="info" %} 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. {% endhint %} ## 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 [#id-1.-configuring-and-downloading-diffblue-cover-cli](#id-1.-configuring-and-downloading-diffblue-cover-cli "mention") 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 ''' } } } ``` 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`` 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. {% hint style="info" %} Cover Reports must be installed on a server that is accessible from the CI runner. {% endhint %} {% hint style="info" %} **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. {% endhint %} For more details on these commands and their tuning with various arguments see [Cover Reports Contributor](/features/cover-reports/cover-reports-contributor.md) --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://cover-docs-preview.diffblue.com/features/cover-pipeline/cover-pipeline-for-ci/quick-start-jenkins.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.