LogoLogo
diffblue.comFree trial
  • Discover Diffblue Cover
  • Get Started
    • What is Diffblue Cover?
    • Get started
      • Free trial
      • Get started - Cover Plugin
      • Get started - Cover CLI
      • Get started - Cover Pipeline
      • Get started - Cover Reports
    • Specs & Reqs
    • Reference Deployments
    • Licensing
      • Online license activation
      • Offline license activation
      • Diffblue License Manager
    • Update Cover
    • FAQs
    • Diffblue Learning
      • Get started
        • Just the basics
        • Free trial
        • Cover Plugin (IDE)
        • Cover CLI (Command Line)
      • Developer
        • Unit tests (IDE)
        • Unit tests (CLI)
        • Test coverage
      • DevOps
        • GitHub
        • GitLab
        • Other CI
      • Administrator
        • Admin - IntelliJ
        • Admin - CLI
        • Admin - Reports
      • Test coverage
        • Developer
        • Senior developer
        • Cover Reports Administrator
  • EVALUATION & ONBOARDING
    • Proof of Value
    • Jumpstart
      • Prerequisites for onboarding
      • Phase 1: Up and running
        • Module 1: Create your Cover unit test baseline
        • Module 2: Cover Pipeline CI integration
      • Phase 2: Developer productivity
        • Module 3: Getting started using Cover
        • Module 4: Introduction to Cover Reports
      • Phase 3: Advanced topics
        • Module 5: Speed up your test execution
        • Module 6: Getting more from Cover
  • Features
    • Cover Plugin
      • Writing tests
        • Gutter icons
        • Menu options
        • Run configurations
        • Cover Plugin tool window
        • Test Review
        • Test examples
        • Creating partial tests
        • Creating skeleton tests
        • Covering all enum values
        • Test insertion order
        • Diffblue Sandbox
        • Environment Check Cache
      • Project configuration
        • General dependencies
        • Test framework dependencies
      • Cover Plugin settings
        • Test Naming
        • Test Formatting
        • Spring configuration options
        • Method Annotations
        • Test Directory
        • Reset Cover Plugin settings
      • Cover Plugin admin
        • Core Maintenance
        • Cover Plugin toolbar menu
        • Cover Plugin status bar widget
        • Telemetry
        • Memory management
        • Using SonarQube with Cover Plugin
        • Log files
        • Troubleshooting
    • Cover CLI
      • Writing tests
        • Command summary
        • Test examples
        • Creating partial tests
        • Customizing test inputs
        • Customizing test setup
        • Test naming
        • Test formatting
        • Test insertion order
        • Patch files
        • Diffblue Sandbox
        • Operational behaviors
        • Test validation
      • Project configuration
        • Preflight checks
        • General dependencies
        • Test framework dependencies
        • Compiling your project successfully
          • Building a Maven project
          • Building a Gradle project
        • Configuring Cover to work with your project's build system
          • Quick guide
          • Configuration file in detail
          • Getting Started with Ant Projects
          • Default configuration
        • Mocking using Mockito
        • Spring profiles
        • Runtime environment
      • Commands & Arguments
        • Environment configuration for CI
        • Packages, classes, and methods
        • Quoting command line arguments
        • Argument files
      • Cover CLI admin
        • Core Maintenance
        • Telemetry
        • Memory management
        • Using Cover CLI in Eclipse
        • Using SonarQube with Cover CLI
        • Log files
        • Troubleshooting
      • Environment Configuration
    • Cover Pipeline
      • Cover Pipeline for CI
        • Quick Start - General
        • Quick Start - Jenkins
        • Quick Start - Azure Pipelines
        • Quick Start - AWS Codebuild
        • Integrating Diffblue Cover into CI on pull requests
        • Installation - VMs or CI run
      • Cover Pipeline for GitLab
        • Introduction
        • Installation and initial setup
        • GitLab workflow
        • Configuration
        • Troubleshooting
        • Related topics
      • Cover Pipeline for GitHub
        • Introduction
        • Installation and initial setup
        • GitHub workflow
        • Configuration
        • Troubleshooting
        • Related topics
    • Cover Reports
      • Cover Reports Contributor
        • Java project config (JaCoCo)
        • Generate and upload reports bundles
        • Authenticated uploads
      • Cover Reports User
        • Navigation
        • Dashboards
        • Telemetry data
        • Export API
        • Considerations
      • Cover Reports Administrator
        • Install and update Cover Reports
        • Configuration options
        • Database backup
        • SSO with Cover Reports
        • Uninstall Cover Reports
    • Cover Optimize
      • Get started - Cover Optimize
      • Cover Optimize & Gradle
      • Cover Optimize & Maven
      • Patch files
    • Cover Refactor
      • Get started - Cover Refactor
    • Cover Annotations
      • Mocking Annotations
      • Custom Input Annotations
      • Interesting Value Annotations
    • Output Codes
      • E - Environment Codes
      • L - License Codes
      • R - Reason Codes
      • T - Testability Codes
      • V - Validation Codes
      • Working with output codes
        • Working with code E020
        • Working with codes E057 to E065
        • Working with code E085
        • Working with code R005
        • Working with code R006
        • Working with code R008
        • Working with code R011
        • Working with code R012
        • Working with code R013
        • Working with code R026
        • Working with code R031
        • Working with code V003
    • Tutorials
      • How to measure test quality
      • How to improve code coverage
      • How to test a new feature
      • How to find regressions
      • How to use Diffblue Cover in test driven development (TDD)
      • How to write tests for Kotlin projects
      • Examples of tests created by Diffblue Cover
      • Best practices for testing private methods
  • Updates & Upgrades
    • Update Cover
    • Cover Editions
    • What's new
    • Release archive
      • 2025-05-01
      • 2025-04-02
      • 2025-04-01
      • 2025-03-02
      • 2025-03-01
      • 2025-02-02
      • 2025-02-01
      • 2025-01-02
      • 2025-01-01
      • 2024-12-02
      • 2024-12-01
      • 2024-11-02
      • 2024-11-01
      • 2024-10-02
      • 2024-10-01
      • 2024-09-02
      • 2024-09-01
      • 2024-08-02
      • 2024-08-01
      • 2024-07-04
      • 2024-07-03
      • 2024-07-01
      • 2024-06-02
      • 2024-06-01
      • 2024-05-02
      • 2024-05-01
      • 2024-04-02
      • 2024-04-01
      • 2024-03-02
      • 2024-03-01
      • 2024-02-02
      • 2024-02-01
      • 2024-01-02
      • 2024-01-01
      • 2023-12-02
      • 2023-12-01
      • 2023-11-03
      • 2023-11-02
      • 2023-11-01
      • 2023-10-02
      • 2023-10-01
      • 2023-09-02
      • 2023-09-01
      • 2023-08-02
      • 2023-08-01
      • 2023-07-03
      • 2023-07-02
      • 2023-07-01
      • 2023-06-02
      • 2023-06-01
      • 2023-05-02
      • 2023-05-01
      • 2023-04-02
      • 2023-04-01
      • 2023-03-02
      • 2023-03-01
      • 2023-02-02
      • 2023-02-01
      • 2023-01-02
      • 2023-01-01
      • 2022-12-02
      • 2022-12-01
      • 2022-11-02
      • 2022-11-01
      • 2022-10-03
      • 2022-10-02
      • 2022-10-01
      • 2022-09-02
      • 2022-09-01
      • 2022-08-05
      • 2022-08-03
      • 2022-08-02
      • 2022-08-01
      • 2022-07-02
      • 2022-07-01
      • 2022-06-02
      • 2022-06-01
      • 2022-05-02
      • 2022-05-01
      • 2022-04-02
      • 2022-04-01
      • 2022-03-02
      • 2022-03-01
      • 2022-02-02
      • 2022-02-01
      • 2022-01-02
      • 2022-01-01
      • 2021-06-02
      • 2021-02-01
  • Legal
    • Diffblue Legal
      • Diffblue End User License Agreement (EULA)
      • Cover Third Party Notices and/or Licenses
      • Privacy Notice
Powered by GitBook
On this page
  • Blocks
  • meta
  • cmd
  • global
  • phase
  • Phases
  • info
  • launcher
  • clean
  • build
  • test
  • coverage
  • refactor
  • validate
  • Variable substitution
  • Phase specific variables
  • Build tool specific variables

Was this helpful?

Export as PDF
  1. Features
  2. Cover CLI
  3. Project configuration
  4. Configuring Cover to work with your project's build system

Configuration file in detail

The minimum configuration file that will be accepted by Cover (all the blocks below are required):

DiffblueBuild.yaml
meta:
  version: 1
  toolName: my-special-maven
cmd:
  windows:
    - mvn.cmd
  linux:
    - mvn
  macos:
    - mvn
global:
  timeout: PT1M
phase:
  info: ~
  launcher: ~
  clean: ~
  build: ~
  test: ~
  coverage: ~
  refactor: ~
  validate: ~

Blocks

meta

Contains metadata about the file. Currently, the version field must be set to 1 as this governs the version of the specification of this file. The toolName is the name used for this build system in console and log file messaging.

cmd

The executables to use for each operating system Windows, Linux, or MacOS. The list is presented in priority order and each will be tried in turn until the first executes without an issue.

Note: If none of the commands complete successfully, they’re assumed to all fail for the same reason and only the first failure will be reported.

DiffblueBuild.yaml
cmd:
  windows:
    - mvnw.cmd
    - mvn.cmd
  linux:
    - mvnw
    - mvn
  macos:
    - mvnw
    - mvn
DiffblueBuild.yaml
cmd:
  windows:
    - ./gradlew.bat
    - ./gradlew
    - gradle.bat
    - gradle
  linux:
    - ./gradlew
    - gradle
  macos:
    - ./gradlew
    - gradle
DiffblueBuild.yaml
cmd:
  windows:
    - ant.cmd
    - ant.bat
    - ant
  linux:
    - ant
  macos:
    - ant

global

Here you can specify any options that apply to all commands that are constructed. You can define timeout (but it can be overridden for each specific phase), a list of flags (command line options or properties with specific values) and a list of plugins.

Note: Plugins are not supported on Ant build systems

DiffblueBuild.yaml
global:
  flags:
    - -Dmaven.ext.class.path=${DIFFBLUE_MAVEN_SPY_JAR}
    - -Dcom.diffblue.cover.skipTests=true
    - --batch-mode
    - --projects=${MODULE}
    - --settings=${DIFFBLUE_MAVEN_USER_SETTINGS}
    - --global-settings=${DIFFBLUE_MAVEN_GLOBAL_SETTINGS}

  timeout: PT10M

  plugins:
    - name: com.mycila:license-maven-plugin
      disable: disable
      enable: format
      flags: ~
      goals:
        - name: format
          goal: format
          flags: ~
        - name: disable
          goal: ~
          flags:
            - -Dlicense.skip=true
DiffblueBuild.yaml
global:
  flags:
    - --init-script=${DIFFBLUE_GRADLE_INIT_SCRIPT}
    - --info
    - --console=plain
    - -PskipTestOptimizer=true
    - -Dcom.diffblue.cover.buildsystem.gradle.model-jar=${DIFFBLUE_GRADLE_SPY_JAR}
    - --no-daemon

  timeout: PT10M

  plugins:
    - name: io.spring.javaformat.gradle.SpringJavaFormatPlugin
      disable: disable
      enable: format
      flags: ~
      goals:
        - name: format
          goal: ${MODULE_PATH}format
          flags: ~
        - name: disable
          goal: ~
          flags:
            - -Pspring-javaformat.skip=true
DiffblueBuild.yaml
global:
  flags: ~
  timeout: PT10M
  plugins: ~

phase

Phases

info

Before Cover can create tests it needs to know some information about the structure of the project. For example: where should the created tests be written; what testing framework is in use (both present on the classpath and has been set up to execute tests); what modules are present; and so on. To avoid needing to know the exact build system in use (and thus having to interpret messaging designed for human consumption from multiple tools) Cover attaches an event spy which emits messaging in a machine readable format to the processes standard output.

launcher

Note: This is not applicable for Maven or Ant projects.

JUnit5 is composed of several different modules from different sub-projects. The JUnit Platform serves as a foundation for launching testing frameworks on the JVM. JUnit Jupiter allows writing tests and extensions in JUnit 5 on the platform (basically the import statements you’d write in your tests). The JUnit Vintage project is used to run JUnit 3 and JUnit 4 tests on the platform.

Under some Gradle projects it is possible to configure the project so the launcher is missing but the tests are executed when run under gradle This happens because gradle uses the dependencies from the gradle distribution and not the configured classpath in the project. If the tests are executed outside a gradle environment, then the tests won’t be executed.

This phase remedies this situation by downloading an appropriate version of the launcher for the version of JUnit in use on the project.

clean

There are times when Cover needs to make sure that the project’s artefacts are up to date (for example, when computing coverage with JaCoCo the previous measurement files are kept around and appended to, thus leading to misleading coverage figures) and thus cleaning the project is necessary.

build

As a corollary of cleaning a project, we also need to build the same project.

test

Cover needs to be able to execute tests to perform a number of tasks, such as probing the project to determine the testing framework and validating the created tests.

coverage

Cover needs to be able to measure coverage of the different test classes in the project (those created by Cover, those created by the developer, a single test, or the coverage of all the tests).

refactor

When Cover fails to create tests for a method, it reports an output code with detailed information. Some output codes can be addressed in an automated way. This phase applies those automated fixes to the project, using OpenRewrite. For example, if Cover detects a missing test framework then we can apply a small refactoring to the build configuration to add the dependency.

Note: This is only supported on Maven and Gradle projects

validate

The validate phase runs once the test creation has finished and ensures that the created tests have no side-effects on the project as a whole. Cover removes created tests if they fail to pass at this point but will leave any existing tests alone.

Variable substitution

There is a set of predefined variables that you can refer to in your DiffblueBuild.yaml file. The values of these variables are determined by Cover itself and cannot be customised. Whenever you refer to one of these variables as ${VARIABLE_NAME}, Cover will replace it with the corresponding value according to the tables below.

Phase specific variables

Note: The refactor phase uses OpenRewrite to refactor code, therefore some of the variable names below relate to the OpenRewrite dependency.

Variable name
Purpose
Phase

DIFFBLUE_GROUP_ID

the group ID of the artefact to download

launcher

DIFFBLUE_ARTIFACT_ID

the artefact ID of the artefact to download

launcher

DIFFBLUE_VERSION

the version of the artefact to download

launcher

DIFFBLUE_REWRITE_CONFIG

the location of the rewrite configuration to apply

refactor

DIFFBLUE_COVER_REFACTORING_RECIPES_JAR

the location of the recipes for refactoring

refactor

DIFFBLUE_COVER_REFACTORING_RECIPES_GROUP_ID

the group ID for the recipes for refactoring

refactor

DIFFBLUE_COVER_REFACTORING_RECIPES_ARTIFACT_ID

the artefact ID for the recipes for refactoring

refactor

DIFFBLUE_COVER_REFACTORING_RECIPES_VERSION

the version for the recipes for refactoring

refactor

DIFFBLUE_OPEN_REWRITE_JAR

the location of the OpenRewrite jar file

refactor

DIFFBLUE_OPEN_REWRITE_POM

the location of the OpenRewrite pom file

refactor

DIFFBLUE_OPEN_REWRITE_GROUP_ID

the group ID for the OpenRewrite jar/pom files

refactor

DIFFBLUE_OPEN_REWRITE_ARTIFACT_ID

the artefact ID for the OpenRewrite jar/pom files

refactor

DIFFBLUE_OPEN_REWRITE_VERSION

the version for the OpenRewrite jar/pom files

refactor

Build tool specific variables

The variables are available to all build tools but are described here grouped by the tool because those tools' configurations make use of them by default.

Variable name
Purpose
Tool

MODULE_PATH

the path to the module separated by colons, e.g. project:application

Gradle

DIFFBLUE_GRADLE_INIT_SCRIPT

the location of the Gradle init script, e.g. .diffblue/init.gradle

Gradle

DIFFBLUE_GRADLE_SPY_JAR

the location of the Gradle event listener classes

Gradle

DIFFBLUE_TEST_CLASS

the name of a single class containing tests to execute, used during the env checks

Gradle

DIFFBLUE_TEST_CLASS_REGEX

the regex matching class names containing created tests, e.g. **/DiffblueTest

Gradle

DIFFBLUE_COVER_REFACTORING_INIT_SCRIPT

the location of the Gradle init script to apply when configuring refactoring

Gradle

MODULE

the name of the module, e.g. application

Maven

DIFFBLUE_MAVEN_USER_SETTINGS

the location of the Maven user settings.xml configuration file

Maven

DIFFBLUE_MAVEN_GLOBAL_SETTINGS

the location of the Maven global settings.xml configuration file

Maven

DIFFBLUE_MAVEN_SPY_JAR

the location of the Maven event listener classes

Maven

DIFFBLUE_TEST_FILE

the name of a single file containing tests to execute, used during the env checks

Maven

DIFFBLUE_TEST_FILE_REGEX

the regex matching file names containing created tests, e.g. *DiffblueTest.java

Maven

PreviousQuick guideNextGetting Started with Ant Projects

Last updated 2 months ago

Was this helpful?

This example, while valid, won’t execute any commands (all phases are a no-op ~). On this page we describe in detail what can be specified in each block, see , and give more detail about the . Finally, there is a set of variables that you can use in the configuration file, see .

The purpose of each phase is described . For each phase you can specify a timeout, a list of goals and a filter (relevant only for the test and coverage phases).

Ref:

https://github.com/gradle/gradle/issues/26114
Blocks
Phases
Variable substitution
here