Our last post announced the availability of the new Diffblue Cover Pipeline for GitHub Actions. This post is a quick start guide to getting started and discovering the power of autonomous AI-powered unit test generation in your GitHub Actions CI workflow.
The best way forward is to try it out for yourselves. Diffblue Cover is available as a free 14-day trial and you can grab the plugin from the GitHub Marketplace.
Before we dive into the available GitHub Action for use with Diffblue Cover Pipeline, we should probably take a moment to understand what GitHub Actions is all about.
GitHub Actions Explained
GitHub Actions allows you to automate processes directly within your repository triggered by certain events; for example a ‘pull request’. When a specific event occurs in a GitHub repository, it triggers a workflow defined by a YAML file. These YAML files are referred to as “workflows’.
Individual operations are called “steps”. Steps can run shell commands or execute reusable actions, which can perform a wide range of tasks such as testing code, deploying applications, or managing issues and pull requests. Developers can write their own steps or can simply search the GitHub Marketplace to help themselves to predefined ‘off-the-shelf’ workflows without having to build the bespoke functionality they need themselves. GitHub Actions are an extremely powerful way to automate the software development processes directly within the GitHub platform.
Let’s get you started
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 integration, set up the action, and write a baseline unit test suite.
If you’re short on time, you can fast-track and watch this video, or you can follow along with this written guide below it.
1. How to configure Diffblue Cover repository secrets
- Clone the sample project from the
https://github.com/diffblue/demo-spring-petclinicDiffblue repo to your GitHub account. - 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_KEYand set Secret to your Diffblue Cover license key (see Licensing, if needed).
- Add another New repository secret and set Name to
DIFFBLUE_ACCESS_TOKENand 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 fullrepopermissions. 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. How to set up a workflow
Here we’ll create a pull request workflow for the project, to use the Diffblue Cover Action from the GitHub Marketplace. The workflow will build the project, write Java unit tests for the project, and commit the the branch.
- 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.
- 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 CI 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 using the Diffblue Cover Action 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.
- 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. How to create the baseline unit test suite
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.
- When you’re ready, click Create pull request.
- 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/testfolders in the project repo to see the unit tests created by Diffblue Cover (suffixed with*DiffblueTest.java).
How to make 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 this GitHub workflow.
Next steps: get going with your own code
When using the Diffblue Cover Action with your own project and existing workflow 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 GitHub, as detailed in Configuration.
