Quick Start - GitLab CI
Quick Start - how to use Diffblue Cover to write tests in GitLab CI
This guide explains how to use Diffblue Cover to write tests in GitLab 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 GitLab repository that has GitLab CI enabled
- A basic understanding of GitLab CI
- The ability to add secret variables to your GitLab project
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.
Add a new pipeline to your GitLab project. Add a "before_script" to configure your runner for the pipeline we are about to create.
before_script:
- export DEBIAN_FRONTEND=noninteractive
- apt-get update
- apt-get --yes --force-yes install wget git maven unzip curl default-jdk
Add a new stage 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.
stages:
- build
Compile project:
stage: build
artifacts:
untracked: true
script:
- mvn --batch-mode --no-transfer-progress clean install -DskipTests
only:
- merge_requests
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 secret variable with the name
DIFFBLUE_COVER_URL and set the value to the URL of the Diffblue Cover CLI release zip file. Add a second secret credential with the name DIFFBLUE_COVER_LICENSE_KEY and set the value to your Diffblue Cover license key.Add a second stage called update-tests:
stages:
- build
- update-tests
Append the code for getting, unzipping and activating
dcover to your workflow file.Update Tests:
stage: update-tests
dependencies:
- Compile project
script:
- 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
- dcover activate "$DIFFBLUE_COVER_LICENSE_KEY"
artifacts:
untracked: true
only:
- merge_requests
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.Now that Diffblue Cover is running in GitLab 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.
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 .. 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 --working-directory "moduleToTest" --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 --working-directory "moduleToTest" --batch
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
To see these new tests in the GitLab 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.Create a new stage called "push-tests":
stages:
- build
- update-tests
- push-tests
Then append the following stage to your workflow file. This will check for any changes to Diffblue tests, configure your git account, checkout your branch, add the updated tests to a commit and push to your branch. Create a new variable "GIT_CI_USER" which will be a username for a GitLab account that is able to push to the repository. Create a second secret variable "GL_DB_TOKEN" which will be a personal access token for this same account. You will also want to replace "[email protected]" with the credentials for your own service account.
Stage, commit and push unit tests:
stage: push-tests
dependencies:
- Update Tests
script:
- if [ -n "$(git status --short **/*DiffblueTest.java)" ]; then
- git config --global pull.ff only
- git remote set-url origin https://$GIT_CI_USER:[email protected]/$CI_PROJECT_PATH.git
- git fetch origin $CI_MERGE_REQUEST_SOURCE_BRANCH_NAME:$CI_MERGE_REQUEST_SOURCE_BRANCH_NAME
- git checkout $CI_MERGE_REQUEST_SOURCE_BRANCH_NAME
- git config --global user.email "db-ci-[email protected]"
- git config --global user.name "db-ci-bot"
- git add **/*DiffblueTest.java
- git commit --message "Update Unit Tests for $(git rev-parse --short HEAD)"
- git push --set-upstream origin $CI_MERGE_REQUEST_SOURCE_BRANCH_NAME
- else
- echo "Nothing to commit"
- fi
only:
- merge_requests
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 exit 0; fi TODO:Check double brackets
For example your build step should now match the following:
Compile project:
stage: build
artifacts:
untracked: true
script:
- if [[ "$(git rev-list -1 --author='^(?!Diffblue CI).*$' --perl-regexp HEAD --no-merges)" != "$(git rev-list HEAD -1 --no-merges)" ]]; then exit 0; fi
- mvn --batch-mode --no-transfer-progress clean install -DskipTests
only:
- merge_requests
Last modified 23d ago