Knowledge Base > Diffblue Cover in the CI Pipeline > Quick Start Guide
Quick Start Guide
- 1. Building the project
- 2. Downloading and activating Diffblue Cover CLI
- 3. Running Diffblue Cover CLI to create tests
- 4. Committing the created tests to a branch
This guide explains in few simple steps 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:
- 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 store secrets variables for your CI tool.
Diffblue Cover stored in the cloud for download along with the license key. See Diffblue documentation on installing Cover in CI.
To integrate Diffblue Cover into your CI pipeline, we will guide you through creating a CI script 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.
1. Building the project
To run Diffblue Cover CLI your project must be built. Running the project’s tests is not required, and you will save time by skipping them, but they do need to compile and pass.
For example, you can use the following command to build a Maven project while skipping the tests:
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 the separate page on Installation. If your license allows it you may wish to install Diffblue Cover with offline activation. See the Diffblue Cover licensing documentation.
You will need to add two secret variables which, here, will be represented as environment variables: the first secret variable with the name
DIFFBLUE_COVER_URL and the value set to the URL of the Diffblue Cover CLI release zip file; the second with the name
DIFFBLUE_COVER_LICENSE_KEY, and the value set to your Diffblue Cover license key.
Append the code for getting, unzipping and activating
dcover to your script.
mkdir -p "~/dcover" cd "~/dcover" curl --retry 5 --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/ dcover activate "$DIFFBLUE_COVER_LICENSE_KEY"
This unzips the Diffblue Cover files into a new directory,
dcover, in the root of the workspace. The files contain a script called
dcover which has the relative path
dcover\dcover.bat in Windows environments). The script is added to your
PATH variable so that you can invoke Diffblue Cover CLI as
Push the changes so that CI runs and ensure that you can see the successful activation of
dcover before moving on. If this is not working, please see the Diffblue Cover licensing documentation or contact Diffblue Support.
3. Running Diffblue Cover CLI to create tests
Now that Diffblue Cover is installed in CI, you can use it to write tests. The next two sections show how to write tests for a single module, and then how to extend this to all modules.
Creating tests for a single module
Choose a module to test in your project. Append the following to your workflow file, changing
moduleToTest to a module in your project or, if your project does not have modules,
--working-directory moduleToTest can be removed or changed to
--working-directory .. The option
--batch makes the output more suitable for CI, as it ensures the CI logs are not cluttered with progress bar output.
dcover create --working-directory "moduleToTest" --batch
Push the changes so that CI 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 do not see this, the call may need tweaking for your project or dependencies adding until it works. The output gives you warnings along the way to guide you. See the Diffblue Cover CLI documentation.
Depending on the size of your module/project, this 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 --working-directory "moduleToTest" --batch
Creating tests for all modules
To write tests for all the modules, you can use a loop as follows:
for MODULE in module_name_1 module_name_2 module_name_3 do dcover create --batch --working-directory "$MODULE" done
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. Depending on your CI tool you may also need to configure a git user to create the commit. We recommend creating a service account for this.
git config user.name db-ci-bot git config user.email [email protected]
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.
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
Please note to be careful not to create an infinite CI loop here. We recommend checking the author of each commit to ensure you are not creating tests for a commit authored by your Diffblue service account.
LAST_NON_BOT_COMMIT="$(git rev-list -1 --author='^(?!db-ci-bot).*$' --perl-regexp HEAD --no-merges)" LAST_COMMIT="$(git rev-list HEAD -1 --no-merges)" if [[ "$LAST_NON_BOT_COMMIT" == "$LAST_COMMIT" ]] then ... fi