Installation and initial setup

Implementing Diffblue Cover into your pipeline is a straightforward process. In brief, we’ll:

1. Find and configure the Diffblue Cover integration.

2. Set up a pipeline for the sample project using the GitLab pipeline editor and the Diffblue Cover pipeline template.

3. Create the full baseline unit test suite for a sample project.

To get familiar with setting up Cover Pipeline for GitLab on a project, we'll use the Spring PetClinic sample project here to activate and configure the Diffblue Cover integration, set up a pipeline, and write a baseline unit test suite.

eLearning

Short on time? If you'd like a fast-track experience check out our getting started video. [5 min]

1. Configure Diffblue Cover

1. Clone the sample project from the https://github.com/diffblue/demo-spring-petclinic Diffblue repo to your GitLab account.

2. From the project in GitLab (either the sample Spring PetClinic project, or your own project) go to Settings > Integrations, find Diffblue Cover, and click Configure.

3. In the configuration screen, update the following (some items may be pre-selected):

• Check/tick the Active box.

• Enter your Diffblue Cover License key provided in your welcome email or by your organization. If needed, click the Try Diffblue Cover link to sign up for a free trial.

• Enter details of your GitLab access token (Name and Secret) to allow Diffblue Cover to access your project. In general, use a GitLab Project Access Token with a Developer role, plus api and write_repository scopes/permissions. If necessary you can use Group Access or Personal Access Tokens, again with api and write permissions. See the GitLab docs links below for full details on how to create an access token.

Using an access token with excessive permissions is a security risk. If you use a Personal access token, consider creating a dedicated user with access limited to just the project, minimizing the impact of the token being leaked.

4. When you're done, click Save changes to apply your updates. Your Diffblue Cover integration is now Active and ready for use in your project.

2. Set up a pipeline

Here we'll create a merge request pipeline for the project that will download the latest version of Diffblue Cover, build the project, write Java unit tests for the project, and commit the changes to the branch.

1. From the project in GitLab go to Build > Pipeline editor and click Configure pipeline to create/edit the .gitlab-ci.yml file.

2. In the editor, click Browse templates and search for the Diffblue Cover pipeline template file in the GitLab templates repo. Copy the contents of this file (sample below) to your project .gitlab-ci.yml pipeline file.

When using the Diffblue Cover pipeline template with your own project and existing pipeline file, add the Diffblue template content to your file and modify as needed - see Configuration for details.

3. When we commit these changes we'll use the commit to create a new branch and create a new merge request. So before you click Commit, update the following:

• Update the Commit message with an appropriate description such as "Update .gitlab-ci.yml file".

• Update the Branch field with an appropriate name such as "add-diffblue-cover-pipeline".

• Check/tick Start a new merge request.

4. When you're ready, click Commit changes and go to #3.-create-the-baseline-unit-test-suite below.

For reference, the Diffblue Cover pipeline template is shown below. Note that this is a sample only - use the file provided in the GitLab templates repo to ensure that you have the latest version.

# This template is provided and maintained by Diffblue.
# You can copy and paste this template into a new `.gitlab-ci.yml` file.
# This template is designed to be used with the Cover Pipeline for GitLab integration from Diffblue.
# It will download the latest version of Diffblue Cover, build the associated project, and
# automatically write Java unit tests for the project.
# Note that additional config is required:
# https://docs.diffblue.com/features/cover-pipeline/cover-pipeline-for-gitlab
# You should not add this template to an existing `.gitlab-ci.yml` file by using the `include:` keyword.
#
# To contribute improvements to CI/CD templates, please follow the Development guide at:
# https://docs.gitlab.com/ee/development/cicd/templates.html
# This specific template is located at:
# https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/ci/templates/Diffblue-Cover.gitlab-ci.yml

variables:
  # Configure the following via the Diffblue Cover integration config for your project, or by
  # using CI/CD masked Variables.
  # For details, see https://docs.diffblue.com/features/cover-pipeline/cover-pipeline-for-gitlab

  # Diffblue Cover license key: DIFFBLUE_LICENSE_KEY
  # Refer to your welcome email or you can obtain a free trial key from
  # https://www.diffblue.com/try-cover/gitlab

  # GitLab access token: DIFFBLUE_ACCESS_TOKEN, DIFFBLUE_ACCESS_TOKEN_NAME
  # The access token should have a role of Developer or better and should have
  # api and write_repository permissions.

  # Diffblue Cover requires a minimum of 4GB of memory.
  JVM_ARGS: -Xmx4g

stages:
  - build

diffblue-cover:
  stage: build

  # Select the Cover CLI docker image to use with your CI tool.
  # Tag variations are produced for each supported JDK version.
  # Go to https://hub.docker.com/r/diffblue/cover-cli for details.
  # Note: To use the latest version of Diffblue Cover, use one of the latest-jdk<nn> tags.
  # To use a specific release version, use one of the yyyy.mm.dd-jdk<nn> tags.
  image: diffblue/cover-cli:latest-jdk17

  # Diffblue Cover currently only supports running on merge_request_events.
  rules:
    - if: $CI_PIPELINE_SOURCE == 'merge_request_event'

  # Diffblue Cover log files are saved to a .diffblue/ directory in the pipeline artifacts,
  # and are available for download once the pipeline completes.
  artifacts:
    paths:
      - "**/.diffblue/"

  script:

    # Diffblue Cover requires the project to be built before creating any tests.
    # Either specify the build command here (one of the following), or provide
    # prebuilt artifacts via a job dependency.

    # Maven project example (comment out the Gradle version if used):
    - mvn test-compile --batch-mode --no-transfer-progress

    # Gradle project example (comment out the Maven version if used):
    # - gradle testClasses

    # Diffblue Cover commands and options to run.
    #   dcover – the core Diffblue Cover command
    #   ci – enable the GitLab CI/CD integration via environment variables
    #   activate - activate the license key
    #   validate - remove non-compiling and failing tests
    #   create - create new tests for your project
    #   --maven – use the maven build tool
    # For detailed information on Cover CLI commands and options, see
    # https://docs.diffblue.com/features/cover-cli/commands-and-arguments
    - dcover
        ci
        activate
        validate --maven
        create --maven

    # Diffblue Cover will also respond to specific project labels:
    #   Diffblue Cover: Baseline
    #     Used to mark a merge request as requiring a full suite of tests to be written.
    #     This overrides the default behaviour where Cover will only write tests related
    #     to the code changes already in the merge request. This is useful when running Diffblue
    #     Cover for the first time on a project and when new product enhancements are released.
    #   Diffblue Cover: Skip
    #     Used to mark a merge request as requiring no tests to be written.
    

3. Create the baseline unit test suite

1. On the New merge request screen, update Title with an appropriate merge request title such as Add Cover pipeline and create baseline unit test suite.

2. When you're ready, click Create merge request.

3. The merge request pipeline will now run Diffblue Cover to create the baseline unit test suite for the project. Once complete, go to the src/test folders in the project repo to see the unit tests created by Diffblue Cover (suffixed with *DiffblueTest.java).

Subsequent code changes

When performing subsequent code changes to a project, the merge request pipeline will run Diffblue Cover but will only update the associated tests. The resulting diff can then be analyzed to check the new behavior, catch regressions, and spot any unplanned behavioral changes to the code. This workflow is illustrated further in GitLab workflow.

Next steps

This topic demonstrates some of the key features of Cover Pipeline for GitLab and how to use the integration within a pipeline. The wider and deeper functionality, provided through dcover commands in the pipeline template, can be implemented to extend your unit test capabilities even further.

When using the Diffblue Cover pipeline template with your own project and existing pipeline file, add the Diffblue template content to your file and modify as needed - see Configuration for details. Note that only specific dcover commands and arguments are currently supported for use with Cover Pipeline for GitLab, as detailed in Configuration.

Once you're familiar with the topics covered under Cover Pipeline for GitLab, check out the Related topics to expand your knowledge further.