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: ~

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 Blocks, and give more detail about the Phases. Finally, there is a set of variables that you can use in the configuration file, see Variable substitution.

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.

Maven

DiffblueBuild.yaml

cmd:
  windows:
    - mvnw.cmd
    - mvn.cmd
  linux:
    - mvnw
    - mvn
  macos:
    - mvnw
    - mvn

Gradle

DiffblueBuild.yaml

cmd:
  windows:
    - ./gradlew.bat
    - ./gradlew
    - gradle.bat
    - gradle
  linux:
    - ./gradlew
    - gradle
  macos:
    - ./gradlew
    - gradle

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.

Maven

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

Gradle

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

phase

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

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

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.

Ref: https://github.com/gradle/gradle/issues/26114

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.

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 by tool as they’re only applicable to that build tool.

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