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.
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:
Downloads Diffblue Cover CLI
Configures the Diffblue Cover environment
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.
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.
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
norDIFFBLUE_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
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 thebuild
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
This will:
dcover
: Start Diffblue Cover.coverage-reports
: Create the coverage reports bundle to send to Reportsupload
: 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.
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
Last updated