Integrating Diffblue Cover into a CI pipeline provides the fastest and most comprehensive way to protect your codebase from regressions. Diffblue Cover CLI is triggered by your CI orchestration tool on each pull-request/merge request to:

• Automatically write new unit tests for new code.

• Automatically update existing unit tests in your code.

• Automatically notify about untestable code.

• Automatically make the code testable using Diffblue Cover Refactor.

• Automatically optimize the running of your unit tests with Diffblue Cover Optimize.

Cover Pipeline is completely flexible to fit into your workflow - you can customize how, when, and where Diffblue Cover is triggered so your workflow remains as natural as possible.

Cover Reports in CI

Cover Pipeline can also automatically Diffblue Cover CLI on a regular basis to generate and upload to Cover Reports.

See Quick Start - General for information on how to use Diffblue Cover to write tests for your project as part of a CI pipeline. The topic outlines the basic commands that you will need to add to your CI scripts, but provides general information to understand the key steps - for specific CI tools, refer to the following:

• Quick Start - Jenkins

• Quick Start - Azure Pipelines

• Quick Start - AWS Codebuild

Overview

This guide explains how to use Diffblue Cover to write tests for your project as part of a CI pipeline. It outlines the basic commands that you will need to add to your CI scripts. We also have dedicated quick start guides for the most common CI tools, such as GitHub Actions or Jenkins.

This guide assumes that you have:

• A Maven or Gradle project that:

  • Compiles

  • Does not have non-compiling or failing tests

  • Is stored in a git repository with any CI tool enabled

• A basic understanding of your chosen CI tool

• The ability to configure environment variables for your CI tool.

• Diffblue Cover stored in the cloud for download along with the license key. See Installation.

To integrate Diffblue Cover into your CI pipeline, we will guide you through creating a CI script that adds the following to change request push events:

1. Downloads Diffblue Cover CLI

2. Configures the Diffblue Cover environment

3. Runs Diffblue Cover to:

   • build the project

   • 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.

1. 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.

You need to give the CI runner access to the Diffblue Cover files in order to write tests.

This guide assumes that you have a URL with the Diffblue Cover CLI release zip referred to as DIFFBLUE_COVER_URL. For example, the latest release of Diffblue Cover CLI can be found at https://release.diffblue.com/cli/latest.

  mkdir -p "~/dcover"
  cd "~/dcover"
  curl --silent --show-error --location --output "diffblue-cover-cli.zip" "$DIFFBLUE_COVER_URL"
  unzip -q "diffblue-cover-cli.zip"
  rm -f "diffblue-cover-cli.zip"
  PATH=$PATH:~/dcover/

2. Configuring the Diffblue Cover Environment

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

This section describes the main configuration information required to enable Diffblue Cover CLI to perform in a CI environment. This guide uses environment variables in the configuration as these are most suited for CI environments, however many environment variables can also be configured (or even overridden) with command line options. In addition to the common options here, many other options can be specified for CI, or for tuning Diffblue Cover in general. Further details of these can be found in Commands & Arguments.

Note that Diffblue Cover Pipeline is designed to write tests in either a patch mode or a baseline mode.

• Patch mode generates tests for code changes on the branch compared to the specified base (branch or commit).

• Baseline mode will write tests for all the code.

Patch mode is best suited for being run on incremental changes such as change requests or merges into a repository with existing Diffblue Cover generated tests. Baseline mode is used for writing initial Diffblue Cover generated tests, or refreshing tests after a major change or version upgrade (e.g. of Diffblue Cover).

License Configuration

The DIFFBLUE_LICENSE_KEY environment variable should contain the Diffblue Cover license key. For further license options including offline licensing see Licensing.

Git Configuration

Diffblue Cover Pipeline integrates with git to write appropriate tests and to add these to your repository. This requires credentials to access git history, make commits, and push. The following environment variables are those that grant access to Diffblue Cover, however if these are not specified Diffblue Cover CLI will attempt to invoke git commands and assume git credentials already exist in the environment.

Branch Configuration

Diffblue Cover Pipeline runs on a branch and commit/push the tests before merging into the main branch of the repository. The branch configuration determines what code tests are written for and where the tests are committed. The following environment variables are most commonly used to configure the git branch. Please note the following.

• If DIFFBLUE_HEAD_BRANCH is not specified then the current branch will be used.

• If neither DIFFBLUE_BASE_BRANCH nor DIFFBLUE_BASE_SHA are specified then Diffblue Cover will run in Baseline mode (see Mode Configuration).

Mode Configuration

The default behavior for Diffblue Cover Pipeline is Patch mode, where code changes between the base and the head are detected and tests written for these code changes. The following environment variables can be set to true to change the behavior of Diffblue Cover Pipeline.

3. Running Diffblue Cover Pipeline

Note that this section should be added into change request push events in your CI work flows. The command to invoke Diffblue Cover is as follows

dcover ci activate build validate create

This will:

• dcover : 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.

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

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 are the 1. Downloading Diffblue Cover CLI , #ci-environment-configuration and License Configurationsections above.

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

dcover coverage-reports upload <Reports Server URL>

This will:

• dcover : 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. Diffblue created tests should be committed before the upload, ensuring that the data in Cover Reports is associated with the commit which adds these tests.

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

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.

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.

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.

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.

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

Overview

This guide explains how to use Diffblue Cover to write tests in Azure Pipelines CI. This guide assumes that you have:

• A Maven or Gradle project that:

  • Compiles

  • Does not have non-compiling or failing tests

  • Is stored in a Git repository which you are able to create a new Azure Pipeline YAML for

• A basic understanding of Azure Pipelines

• The ability to add secret variables to a pipeline

• Diffblue Cover stored in the cloud for download along with the license key. See Installation.

To integrate Diffblue Cover into your CI pipeline, we will guide you through creating a pipeline YAML that:

1. Builds your project

2. Downloads and activates Diffblue Cover CLI

3. Runs Diffblue Cover to create tests

4. Commits the created tests to a branch

The following sections provide more details for each of the above steps.

1. Building the project

Add a new pipeline to your project's CI. In the example below the pipeline is triggered on any pull request against the main branch. Make sure to check, and if necessary modify, the 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.

name: Cover

trigger: none
pr:
  branches:
    include:
    - main

pool:
  vmImage: 'ubuntu-latest'

variables:
  BASH_ENV: "~/.profile"

jobs:
- job: update_diffblue_tests
  displayName: Update Diffblue Tests

  steps:
  - checkout: self
    persistCredentials: true

  - script: |
      git checkout "$(System.PullRequest.SourceBranch)"
    displayName: 'Checkout Branch'

  - script: |
      mvn --batch-mode --no-transfer-progress clean install -DskipTests
    displayName: 'Build Project'

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. See Installation. If your license allows it you may wish to install Diffblue Cover with offline activation. See Licensing.

Add a new variable with the name DIFFBLUE_COVER_URL, set the value to the URL of the Diffblue Cover CLI release zip file and tick the "Keep this value secret" box. Then add a second variable with the name DIFFBLUE_COVER_LICENSE_KEY. Set the value to your Diffblue Cover license key and make this a secret variable as well.

Append the code for getting, unzipping and activating dcover to your pipeline YAML.

  - script: |
      mkdir dcover
      cd dcover
      curl --silent --show-error --location --output "diffblue-cover-cli.zip" "$(DIFFBLUE_COVER_URL)" 
      unzip -q "diffblue-cover-cli.zip"
      rm --force "diffblue-cover-cli.zip"
      echo "export PATH=$PATH:$PWD/" >> ~/.profile
      source ~/.profile
    displayName: 'Download Diffblue Cover'
  
  - script: |
      dcover activate "$(DIFFBLUE_COVER_LICENSE_KEY)"
    displayName: 'Activate Diffblue Cover'

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. Add this to your path so that you can call Diffblue Cover as dcover. In order to add Cover to your path ensure you include the "BASH_ENV" variable from the first step.

Push the changes so this workflow runs - ensure that you can see the successful activation of dcover in your "Activate Diffblue Cover" step 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 Azure Pipelines, you can use it to write tests. Append the following to your pipeline YAML. 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.

  - script: dcover create --batch
    displayName: 'Create tests using Diffblue Cover'

Push the changes so this workflow runs. Once successfully complete, you should expect to see output that looks like this in your "Create tests using Diffblue Cover" step:

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

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:

dcover create com.somepackage.SomeClass --batch

4. Committing the created tests to a branch

To see these new tests in the project you'll need to commit them and push back to the repository. You'll need to configure Git credentials to commit. We recommend creating a service account for this.

  - script: |
      git config user.name db-ci-bot
      git config user.email db-ci-bot@yourorg.com
    displayName: 'Config git user'

To commit the tests append the following to your pipeline YAML. This will check for any changes to Diffblue tests, add them to a commit and push to your branch.

  - script: |
      if [ -n "$(git status --short **/*DiffblueTest.java)" ]; then 
        git add **/*DiffblueTest.java
        git commit --message "Update Unit Tests for $(git rev-parse --short HEAD)"
        git push --set-upstream origin
      else
        echo "Nothing to commit"
      fi
    displayName: Stage, commit and push unit tests

Please note - be careful not to create an infinite CI loop here. This is because pushing a commit with updated tests will re-trigger the pipeline. To avoid this becoming a loop we recommend checking the author of each commit to ensure you are not creating tests for a commit authored by your Diffblue service account. This can be done by appending the following to the start of your pipeline YAML.

  - script: |
      LAST_NON_BOT_COMMIT="$(git rev-list -1 --author='^(?!db-ci-bot).*$' --perl-regexp HEAD --no-merges)"
      echo "Last non bot commit is $LAST_NON_BOT_COMMIT"
      LAST_COMMIT="$(git rev-list HEAD -1 --no-merges)"
      echo "Last commit is $LAST_COMMIT"
      if [[ "$LAST_NON_BOT_COMMIT" == "$LAST_COMMIT" ]]
      then
        echo "##vso[task.setvariable variable=last_bot_commit]0"
      else
        echo "##vso[task.setvariable variable=last_bot_commit]1"
      fi
    displayName: 'Check if last commit was bot commit'

Then append this condition to all of the subsequent jobs:

  condition: eq(variables.last_bot_commit, 0)

Your final pipeline YAML should look similar to:

name: Cover

trigger: none
pr:
  branches:
    include:
    - main

pool:
  vmImage: 'ubuntu-latest'

variables:
  BASH_ENV: "~/.profile"

jobs:
- job: update_diffblue_tests
  displayName: Update Diffblue Tests

  steps:
  - checkout: self
    persistCredentials: true

  - script: |
      git checkout "$(System.PullRequest.SourceBranch)"
    displayName: 'Checkout Branch'

  - script: |
      LAST_NON_BOT_COMMIT="$(git rev-list -1 --author='^(?!db-ci-bot).*$' --perl-regexp HEAD --no-merges)"
      echo "Last non bot commit is $LAST_NON_BOT_COMMIT"
      LAST_COMMIT="$(git rev-list HEAD -1 --no-merges)"
      echo "Last commit is $LAST_COMMIT"
      if [[ "$LAST_NON_BOT_COMMIT" == "$LAST_COMMIT" ]]
      then
        echo "##vso[task.setvariable variable=last_bot_commit]0"
      else
        echo "##vso[task.setvariable variable=last_bot_commit]1"
      fi
    displayName: 'Check if last commit was bot commit'

  - script: |
      mvn --batch-mode --no-transfer-progress clean install -DskipTests
    displayName: 'Build Project'
    condition: eq(variables.last_bot_commit, 0)

  - script: |
      mkdir dcover
      cd dcover
      curl --silent --show-error --location --output "diffblue-cover-cli.zip" "$(DIFFBLUE_COVER_URL)" 
      unzip -q "diffblue-cover-cli.zip"
      rm -f "diffblue-cover-cli.zip"
      echo "export PATH=$PATH:$PWD/" >> ~/.profile
      source ~/.profile
    displayName: 'Download Diffblue Cover'
    condition: eq(variables.last_bot_commit, 0)
  
  - script: |
      dcover activate "$(DIFFBLUE_COVER_LICENSE_KEY)"
    displayName: 'Activate Diffblue Cover'
    condition: eq(variables.last_bot_commit, 0)

  - script: |
      dcover create --batch
    displayName: 'Creating unit tests using Diffblue Cover'
    condition: eq(variables.last_bot_commit, 0)

  - script: |
      git config user.name db-ci-bot
      git config user.email db-ci-bot@yourorg.com
    displayName: 'Config git user'
    condition: eq(variables.last_bot_commit, 0)

  - script: |
      if [ -n "$(git status --short **/*DiffblueTest.java)" ]; then 
        git add **/*DiffblueTest.java
        git commit --message "Update Unit Tests for $(git rev-parse --short HEAD)"
        git push --set-upstream origin
      else
        echo "Nothing to commit"
      fi
    displayName: Stage, commit and push unit tests
    condition: eq(variables.last_bot_commit, 0)

Overview

This guide explains how to use Diffblue Cover to write tests in AWS Codebuild. This guide assumes that you have:

• A Maven or Gradle project that:

  • Compiles

  • Does not have non-compiling or failing tests

  • Is stored in a Git repository that can be accessed by AWS

• A basic understanding of AWS Codebuild CI

• Permissions to add Codebuild jobs and secret variables.

• Diffblue Cover stored in the cloud for download along with the license key. See Installation.

To integrate Diffblue Cover into your CI pipeline, we will guide you through creating a workflow file that:

1. Builds your project

2. Downloads and activates Diffblue Cover CLI

3. Runs Diffblue Cover to create tests

4. Commits the created tests to a branch

The following sections provide more details for each of the above steps.

1. Building the project

Create a new build project and select the source to be your Git repository (in this example we'll be using GitHub).

Add a new phase to build your project. Make sure to check, and if necessary modify, the 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.

version: 0.2

phases:
  install:
    commands:
      - mvn --batch-mode --no-transfer-progress clean install -DskipTests

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 - see Installation. If your license allows it you may wish to install Diffblue Cover with offline activation - see Licensing.

Create a new secret in the secret manager called DIFFBLUE_COVER_URL and set the value to the URL of the Diffblue Cover CLI release zip file. Add a second secret with the name DIFFBLUE_COVER_LICENSE_KEY and set the value to your Diffblue Cover license key. Make sure that the service role you assigned to this project has access to these secrets. To do this create a new IAM policy and assign it to your service role.

Append the code for getting, unzipping, and activating dcover to your workflow file, replacing the strings with the ARNs for the corresponding secrets you created.

env:
  secrets-manager:
    DIFFBLUE_COVER_URL: "COVER_URL_ARN_HERE"
    DIFFBLUE_COVER_LICENSE_KEY: "COVER_LICENSE_KEY_ARN_HERE"

  build:
    commands:
      - mkdir -p "dcover"
      - cd "dcover"
      - curl --silent --show-error --location --output "diffblue-cover-cli.zip" "$DIFFBLUE_COVER_URL"
      - unzip -q "diffblue-cover-cli.zip"
      - rm -f "diffblue-cover-cli.zip"
      - PATH=$PATH:$PWD
      - cd ..
      - dcover activate "$DIFFBLUE_COVER_LICENSE_KEY"

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. Add this to your path so that you can call Diffblue Cover as dcover (or dcover.bat).

Push the changes so this workflow runs - ensure that you can see the successful activation of dcover before moving on. 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 AWS Codebuild, you can use it to write tests. Append the following to your workflow file. 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.

    - dcover create --batch

Push the changes so this workflow 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 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:

dcover create com.somepackage.SomeClass --batch

4. Committing the created tests to a branch

To see these new tests in the project repository you'll need to commit them and push back to the repository. You'll need to configure Git credentials to commit. We recommend creating a service account for this.

      - git config --global user.email "db-ci-bot@yourorg.com"
      - git config --global user.name "db-ci-bot"
      - git remote set-url origin https://db-ci-bot:$GH_TOKEN@github.com/yourorg/yourproject.git
      - git add **/*DiffblueTest.java
      - git commit --message "Update Unit Tests for $(git rev-parse --short HEAD)"
      - git push origin

As this project was cloned using https we must add our credentials to the origin URL - to do this you must add a third secret in the secret manager for the GitHub token.

env:
  secrets-manager:
    GH_TOKEN: "GH_TOKEN_ARN_HERE"

Please note - be careful not to create an infinite CI loop here. This is because pushing a commit with updated tests will re-trigger the pipeline. To avoid this becoming a loop we recommend checking the author of each commit to ensure you are not creating tests for a commit authored by your Diffblue service account. This can be done by appending the following line to the start of all three jobs making sure to replace "db-ci-bot" with the name of your service account.

  - |
          if [ "$(git rev-list -1 --author='^(?!db-ci-bot).*$' --perl-regexp HEAD --no-merges)" = "$(git rev-list HEAD -1 --no-merges)" ]; then
            ...
            git push origin
            ...
          fi

Overview

This topic will help you to create a Jenkins declarative pipeline that is triggered by a webhook to automatically write Diffblue tests for a pull request.

Prerequisites

This topic assumes that you have:

• Set up the Jenkins freestyle project to trigger Diffblue Cover.

• A Jenkinsfile in your project (see Quick Start - Jenkins or perhaps you have an existing Jenkinsfile).

and will wrap the Jenkins freestyle project that pushes tests to a branch in a Jenkinsfile for a Jenkins multi-branch pipeline that is triggered by a webhook for pull requests.

Setup a webhook

The Jenkins pipeline will be triggered by a webhook, so it is necessary to set up a webhook on the remote host if you do not already have one.

Setting up a webhook is well-documented on Github https://docs.github.com/en/developers/webhooks-and-events/webhooks/creating-webhooks

• The payload URL should be JENKINS_URL/multibranch-webhook-trigger/invoke?token=github-webhook, where JENKINS_URL might look like http://jenkins.your.org.com:8080/

• The type is json/application

• Select Let me select individual events and check Pull requests

The Jenkins pipeline will use the Multibranch Scan Webhook Trigger plugin in Jenkins which is triggered by the payload URL above. Since only pull requests trigger the webhook, the job will run when a pull request is made or updated.

In the Jenkins configuration, under Scan Repository Triggers select Scan by webhook with trigger token github-webhook, to tell Jenkins what to listen for.

Add stages to the Jenkinsfile

If you have done the quick start guide, you can replace the Use dcover create in Jenkins with a step that calls the Jenkins freestyle project difflue-cover-tool, or add a stage to your existing Jenkins file, as follows:

pipeline {
    agent any

    stages {
        stage('Use dcover create in Jenkins') {
            steps {
                script {
                   build job: 'diffblue-cover-tool', parameters: [string(name: 'HEAD_BRANCH', value: "$CHANGE_BRANCH"), string(name: 'BASE_BRANCH', value: "$CHANGE_TARGET"), string(name: 'MODULES', value: "module1 module2 module3")]
                }
            }
        }
    }

}

Replace the MODULES parameter value with the modules in your project. Though for testing purposes, you may wish to select a single module for now.

This will trigger the diffblue-cover-tool job on a pull request when the pull request is made or the branch is updated. However, since this job will push the tests to the pull request branch, you first need to skip this stage if the commit author is the user that pushes the Diffblue tests, which is done in the next section.

Skip Diffblue tests when bot user commits

Add the stage to get the author of the last commit before the Use dcover create in Jenkins stage.

stage('Get last commit author and bot name') {
    steps {
        script {
            env.GIT_AUTHOR = sh (script: 'git log --no-merges -1 --pretty=%cn', returnStdout: true).trim()
            env.DIFFBLUE_BOT_NAME = "db-ci-bot"
        }
        sh '''#!/bin/bash
            echo "Git author is $GIT_AUTHOR and the Diffblue bot name is $DIFFBLUE_BOT_NAME"
        '''
    }
}

then add a when statement to the Update diffblue tests stage

stages {
    stage('Use dcover create in Jenkins') {
        when {
            not { environment name: 'GIT_AUTHOR', value: "$env.DIFFBLUE_BOT_NAME" }
        }
        steps {
            script {
                build job: 'diffblue-cover-tool', parameters: [string(name: 'HEAD_BRANCH', value: "$CHANGE_BRANCH"), string(name: 'BASE_BRANCH', value: "$CHANGE_TARGET"), string(name: 'MODULES', value: "module1 module2 module3")]
            }
        }
    }
}

With this, the Use dcover create in Jenkins stage will only run on code changes by a user other than the Diffblue tests user, avoiding an unnecessary run. At this point, you may wish to add this to any other stages in your Jenkinsfile that require it.

Create a test branch and PR

In the repository you wish to write tests for, create a branch called diffblue-test-pr based on your main branch.

Make a simple change in a module that the diffblue-cover-tool job is set to run on and commit the change. Push this branch to the remote host and make a pull request.

You should see the job running and then a commit pushed to the PR branch. In this simple setup, the commit that pushes Diffblue tests will re-trigger CI, but the author check should prevent Diffblue Cover from re-running. When the PR is merged, the Diffblue tests will be merged with it.

What's next

With this, you can have Diffblue Cover writing tests automatically for your repository.

It is basic and there are efficiencies to make and errors to catch, but how this is done depends heavily on your specific pipeline and environment.

You can see how we at Diffblue have address some of these in our full example which includes:

1. Storing and running Diffblue tests separately to hand-written unit tests.

2. Dealing with non-compiling or failing tests using dcover validate before dcover create.

3. Running existing Diffblue tests against a pull request to catch possible regressions.

4. Parallelizing to speed up runs on PRs and dealing with concurrency in the remote host.

5. Stopping multiple builds on the same PR.

6. Adding a comment to the PR so the end user knows what is happening.

Before you begin the installation, please obtain the link to download Cover (from your product update email, or contact Diffblue). Please note you need version 2022.03.02 or above, installed and activated with an appropriate license.

Installing on a VM

If you only have a few machines it is possible to manually install Cover on each machine. To do this:

1. Unzip the Cover jar files to a common and accessible directory inside each VM.

2. Activate Cover.

3. Reference these jar files when calling Cover in your CI scripts.

Installing during a CI run

For most CI systems, you will want to download Cover as part of your CI run.

This link should be added as a secret variable for your CI system, with a memorable name, such as “RELEASE_URL”, so that it can be referenced later. Depending on your CI system this will have a different name but common examples are:

• GitHub Actions = Secrets

• Codebuild = Parameter store

• Jenkins = Secret text in credentials

• GitLab CI = Protected variables

Then, add a step to your pipeline which downloads from this link and extract the contents. Below is an example in GitHub Actions:

- name: Get Cover
        run: |
          mkdir dcover
          cd dcover
          wget -c "${{ secrets.RELEASE_URL }}" -O dcover.zip -q
          unzip dcover.zip

From this point on you will be able to call Cover by referencing the executable extracted from this zip at the location you specified (dcover/dcover in the example above).

Similarly, add a secret variable for your CI system that holds the Cover license key, such as “LICENSE_KEY”. Activate Cover each time CI is run. For example

- name: Get Cover
        run: dcover/dcover activate "$LICENSE_KEY"