Quick Start - General

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.

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 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/

Diffblue Cover CLI docker images are also available for various JDK versions. These are available on Docker Hub.

2. Configuring the Diffblue Cover Environment

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

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

Environment variable	Notes
DIFFBLUE_ACCESS_TOKEN	The git credentials access token. This should give the user permissions to pull and push to the git repository.
DIFFBLUE_ACCESS_TOKEN_NAME	The name of the access token.
DIFFBLUE_COMMIT_AUTHOR	The author name that Diffblue Cover Pipeline will use in the git repository.
DIFFBLUE_COMMIT_EMAIL	The email that Diffblue Cover Pipeline will use in the git repository.

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

Environment variable	Notes
DIFFBLUE_HEAD_BRANCH	The git name of the branch that the tests will be written for and committed to.
DIFFBLUE_BASE_BRANCH	The name of the branch the change request (or DIFFBLUE_HEAD_BRANCH) was forked from.
DIFFBLUE_BASE_SHA	The SHA of the latest commit before this branch was forked.
DIFFBLUE_REPOSITORY_URL	The full path to the git remote repository (if not specified, this will be read from the local git 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.

Environment variable	Notes
DIFFBLUE_BASELINE_MODE	When set to true this will configure Diffblue Cover to write tests for the whole project, not just changes local to this branch. This is best used when setting up a new project, or with major changes in the code or version of Diffblue Cover.
DIFFBLUE_SKIP_CI	When set to true this will configure Diffblue Cover to exit with a success return code while performing no further actions.
DIFFBLUE_SKIP_PUSH	When set to true this will configure Diffblue Cover to not push changes back to the repository; they will still be committed locally.

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.

It is possible to chain coverage-reports upload to the dcover ci command above, but this is not recommended except on the merge-pipeline that runs on the main branch (as opposed to the pipeline that runs on a feature branch).

Cover Pipeline is primarily used to create tests focused on recently changed source files, but can also be used with a Diffblue Cover: Baseline label in order to create / refresh the full baseline tests suite.

Cover Reports is primarily used to report on the full baseline test suite and so this recommended integration automatically skips generating and uploading reports unless running with the Diffblue Cover: Baseline label

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

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