Knowledge Base > Diffblue Cover in the CI Pipeline > Quick Start Guide for GitHub Actions

Quick Start Guide for GitHub Actions

• Overview
• 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

Overview

This guide explains in few simple steps how to use Diffblue Cover to write tests in GitHub Actions 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 GitHub repository that has GitHub Actions enabled

• A basic understanding of GitHub Actions

• The ability to add secrets to your GitHub project

• 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 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.

1. Building the project

Add a new workflow to your GitHub project, this is done by creating a new YAML file in the “.github/workflows” directory. 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.

name: Cover
on:
  # Allow the workflow to be triggered manually using the GitHub API, CLI, or browser interface
  workflow_dispatch:
  # Trigger the workflow automatically on pushes to master
  push:
    branches: [master]
concurrency:
  # Only allow one run of the workflow per branch to run at a time
  group: $
  cancel-in-progress: true

jobs:
  Test:
    runs-on: ubuntu-22.04
    env:
      JVM_ARGS: -Xmx4096m
    steps:
      - name: Checkout repository
        uses: actions/[email protected]
        with:
          fetch-depth: 0
      - name: Compile project
        run: 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.

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. Then add secret text credentials with the name DIFFBLUE_COVER_LICENSE_KEY and set the value to your Diffblue Cover license key.

Append the code for getting, unzipping and activating dcover to your workflow file.

      - name: Download Diffblue Cover
        run: |
          mkdir -p "$RUNNER_TEMP/dcover"
          cd "$RUNNER_TEMP/dcover"
          curl --retry 5 --silent --show-error --location --output "diffblue-cover-cli.zip" "$"
          unzip -q "diffblue-cover-cli.zip"
          rm -f "diffblue-cover-cli.zip"
          echo "$RUNNER_TEMP/dcover" >> "$GITHUB_PATH"
      
      - name: Activate Diffblue Cover
        run: dcover activate "$"

This will put the Diffblue Cover files into the directory dcover in the root of the workspace. The Diffblue Cover files contain a script to invoke dcover which has the relative path dcover/dcover (or dcover\dcover.bat in Windows environments). Add this to your path so that you can call Diffblue Cover as dcover (or dcover.bat).

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.

      - name: Create tests for single module
        run: dcover create --working-directory "moduleToTest" --batch
          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:

      - name: Create unit tests on each module
        run: |
          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 these new tests in the GitHub project you will need to commit them and push back to the repository. You will need to configure git credentials to commit. This can be achieved using a community action.

      - name: Setup Git Credentials
        uses: fregante/[email protected]

To commit the tests append the following to your workflow file. This will check for any changes to Diffblue tests, add them to a commit and push to your branch.

      - name: Stage, commit and push unit tests
        run: |
          if [ -n "$(git status --short **/*DiffblueTest.java)" ]; then 
            git add **/*DiffblueTest.java
            git commit --message "Update Unit Tests for $GITHUB_SHA"
            git push --set-upstream origin
          else
            echo "Nothing to commit"
          fi

Please note to be careful not to create an infinite CI loop here. By using the provided GitHub account and credentials GitHub Actions will skip running on commits it created. If you choose to use a dedicated service account however, we recommend checking the author of each commit to ensure you are not creating tests for a commit authored by your Diffblue service account.