Installation and initial setup

Diffblue Cover is provided as an Action in the GitHub Marketplace. Implementing Diffblue Cover into your GitHub Actions workflow is a straightforward process. In brief, we’ll:

1. Clone a sample project and configure the GitHub Repository Secrets required for the Diffblue Cover Pipeline.

2. Set up a workflow that will use the Diffblue Cover Pipeline GitHub Action. Note that the Quick Start - General describes how to configure Diffblue Cover in CI without using the Diffblue Cover Pipeline Action.

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

To get familiar with setting up Cover Pipeline for GitHub on a project, we'll use the Spring PetClinic sample project here to activate and configure the Diffblue Cover Action, and write unit tests for the project.

eLearning

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

1. Configure Diffblue Cover Repository Secrets

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

2. Configure your Diffblue License key and your GitHub access token - go to Settings > Secrets and variables > Actions > Repository secrets

• Add a New repository secret and set Name to DIFFBLUE_LICENSE_KEY and set Secret to your Diffblue Cover license key (see Licensing, if needed).

• Add another New repository secret and set Name to DIFFBLUE_ACCESS_TOKEN and set Secret to the GitHub access token used to allow Diffblue Cover to access your project. In general, use a GitHub Classic access token with full repo permissions. For more information on GitHub access tokens, see the GitHub access tokens docs topic.

• Finally, make sure that your repository allows actions to be executed - in the repository go to Settings > Action permissions:

Note that GitHub fine-grained access tokens are in Beta and not supported. If you must use a fine-grained access token then the following are required:

• Contents: write

• Pull requests: write

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.

2. Set up a workflow

This section describes how to create a workflow using the Diffblue Cover GitHub Action. Note that the Quick Start - General describes how to configure Diffblue Cover in CI without using the Diffblue Cover Pipeline Action.

Here we'll create a pull request workflow for the project, to use Diffblue Cover Pipeline from the GitHub Marketplace. The workflow will build the project, write Java unit tests for the project, and commit the changes to the branch.

1. From the project in GitHub (either the sample Spring PetClinic project, or your own project) go to Actions > New Workflow > Set up a workflow yourself.

2. In the editor, paste in the Diffblue Cover workflow - you can copy this from the GitHub Marketplace. For reference, the default workflow is duplicated below.

name: Example Workflow

# Diffblue Cover Pipeline responds to pull request
on:
  pull_request:

# Avoid running the same workflow on the same branch concurrently
concurrency:
  group: ${{ github.workflow }}-${{ github.ref }}

jobs:
  DiffblueCover:
    runs-on: ubuntu-latest
    steps:

      # Checkout the repository with permission to push
      - name: Checkout
        uses: actions/checkout@v4

      # Run Diffblue Cover
      - name: Diffblue Cover
        uses: diffblue/cover-github-action@main
        env:
          JVM_ARGS: -Xmx4096m
        with:
          # The access token used to push commits and call GitHub APIs.
          #
          # Must have access to the project with at least Write role, and scopes
          # including code, commit-statuses, pull-requests, workflows and actions.
          access-token: ${{ secrets.DIFFBLUE_ACCESS_TOKEN }}

          # The license key provided in your welcome email or provided by your organization.
          # Alternatively obtain a free trial key from https://www.diffblue.com/try-cover/github.
          license-key: ${{ secrets.DIFFBLUE_LICENSE_KEY }}

          # Working directory where the project can be found, if not at the root.
          # working-directory: path/to/project

          # The Diffblue Cover commands and options to use.
          # Below is the default behavior, uncomment these and edit to customize
          # how Diffblue Cover is run on your project.
          #args: >-
          #  ci
          #  activate
          #  build
          #  validate
          #  create

      # Collect Diffblue Cover outcome files
      # This step saves Diffblue Cover run outcome files for later use. These include summary
      # information on Diffblue Cover's results, reports files, and logs. The information
      # contained in these files can be used for project analysis, metrics, improving analysis
      # or troubleshooting problems.
      # Note that this job will always run even when the Run Diffblue Cover job fails. This
      # ensures troubleshooting logs and output are available.
      - name: Diffblue Artifacts
        if: always()
        uses: actions/upload-artifact@v4
        with:
          name: logs
          path: |
            **/.diffblue/**

When implementing the Diffblue Cover Pipeline and workflows with your own project and existing workflow file(s), add the Diffblue template content to your file and modify as needed - see Configuration for details.

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

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

• Check Create a new branch for this commit and start a pull request to create a new branch and create a new pull request.

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

• Click Propose changes to start the pull request.

3. Create the baseline unit test suite

1. On the Create pull request screen, update Title with an appropriate pull request title such as Add Cover workflow and create baseline unit test suite.

1. When you're ready, click Create pull request.

2. The pull request workflow 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 pull request workflow 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 GitHub workflow.

Next steps

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

When implementing the Diffblue Cover Pipeline with your own project and existing workflow file, add the 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 GitHub, as detailed in Configuration.

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