# Configuration file in detail The minimum configuration file that will be accepted by Cover (all the blocks below are required): {% code title="DiffblueBuild.yaml" fullWidth="false" %} ```yaml meta: version: 3 toolName: my-special-maven cmd: windows: - mvn.cmd linux: - mvn macos: - mvn global: timeout: PT1M phase: info: ~ classpath: ~ launcher: ~ clean: ~ build: ~ test: ~ coverage: ~ refactor: ~ validate: ~ ``` {% endcode %} 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](#blocks), and give more detail about the [Phases](#phases). Finally, there is a set of variables that you can use in the configuration file, see [Variable substitution](#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. {% tabs %} {% tab title="Maven" %} {% code title="DiffblueBuild.yaml" %} ```yaml cmd: windows: - mvnw.cmd - mvn.cmd linux: - mvnw - mvn macos: - mvnw - mvn ``` {% endcode %} {% endtab %} {% tab title="Gradle" %} {% code title="DiffblueBuild.yaml" %} ```yaml cmd: windows: - ./gradlew.bat - ./gradlew - gradle.bat - gradle linux: - ./gradlew - gradle macos: - ./gradlew - gradle ``` {% endcode %} {% endtab %} {% tab title="Ant" %} {% code title="DiffblueBuild.yaml" %} ```yaml cmd: windows: - ant.cmd - ant.bat - ant linux: - ant macos: - ant ``` {% endcode %} {% endtab %} {% endtabs %} ### 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 {% tabs %} {% tab title="Maven" %} {% code title="DiffblueBuild.yaml" %} ```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 ``` {% endcode %} {% endtab %} {% tab title="Gradle" %} {% code title="DiffblueBuild.yaml" %} ```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 ``` {% endcode %} {% endtab %} {% tab title="Ant" %} {% code title="DiffblueBuild.yaml" %} ```yaml global: flags: ~ timeout: PT10M plugins: ~ ``` {% endcode %} {% endtab %} {% endtabs %} ### phase The purpose of each phase is described [here](#phases). 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. ### classpath The classpath phase is essential for determining where the dependencies and resources are located for the project. During this phase, the event spy monitors the build process to identify and capture relevant classpath entries, including sub-projects, storing them in a machine-readable format. This information is crucial for test generation and execution and ensures that Cover has precise knowledge of the classpath structure used by the project. ### 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. Ref: ### 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 namePurposePhase
DIFFBLUE_GROUP_IDthe group ID of the artefact to downloadlauncher
DIFFBLUE_ARTIFACT_IDthe artefact ID of the artefact to downloadlauncher
DIFFBLUE_VERSIONthe version of the artefact to downloadlauncher
DIFFBLUE_REWRITE_CONFIGthe location of the rewrite configuration to applyrefactor
DIFFBLUE_COVER_REFACTORING_RECIPES_JARthe location of the recipes for refactoringrefactor
DIFFBLUE_COVER_REFACTORING_RECIPES_GROUP_IDthe group ID for the recipes for refactoringrefactor
DIFFBLUE_COVER_REFACTORING_RECIPES_ARTIFACT_IDthe artefact ID for the recipes for refactoringrefactor
DIFFBLUE_COVER_REFACTORING_RECIPES_VERSIONthe version for the recipes for refactoringrefactor
DIFFBLUE_OPEN_REWRITE_JARthe location of the OpenRewrite jar filerefactor
DIFFBLUE_OPEN_REWRITE_POMthe location of the OpenRewrite pom filerefactor
DIFFBLUE_OPEN_REWRITE_GROUP_IDthe group ID for the OpenRewrite jar/pom filesrefactor
DIFFBLUE_OPEN_REWRITE_ARTIFACT_IDthe artefact ID for the OpenRewrite jar/pom filesrefactor
DIFFBLUE_OPEN_REWRITE_VERSIONthe version for the OpenRewrite jar/pom filesrefactor
### 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 namePurposeTool
MODULE_PATHthe path to the module separated by colons, e.g. project:applicationGradle
DIFFBLUE_GRADLE_INIT_SCRIPTthe location of the Gradle init script, e.g. .diffblue/init.gradleGradle
DIFFBLUE_GRADLE_SPY_JARthe location of the Gradle event listener classesGradle
DIFFBLUE_TEST_CLASSthe name of a single class containing tests to execute, used during the env checksGradle
DIFFBLUE_TEST_CLASS_REGEXthe regex matching class names containing created tests, e.g. **/*DiffblueTest**. Deprecated in version 2.2; use DIFFBLUE_TEST_CLASS_GLOB_PATTERN instead.Gradle
DIFFBLUE_TEST_CLASS_GLOB_PATTERNthe pattern matching file names containing created tests, e.g. **/*DiffblueTest**Gradle
DIFFBLUE_TEST_CLASS_REGEX_PATTERNthe regex matching class names containing created tests, e.g. .*DiffblueTest.*Gradle
DIFFBLUE_COVER_REFACTORING_INIT_SCRIPTthe location of the Gradle init script to apply when configuring refactoringGradle
MODULEthe name of the module, e.g. applicationMaven
DIFFBLUE_MAVEN_USER_SETTINGSthe location of the Maven user settings.xml configuration fileMaven
DIFFBLUE_MAVEN_GLOBAL_SETTINGSthe location of the Maven global settings.xml configuration fileMaven
DIFFBLUE_MAVEN_SPY_JARthe location of the Maven event listener classesMaven
DIFFBLUE_TEST_FILEthe name of a single file containing tests to execute, used during the env checksMaven
DIFFBLUE_TEST_FILE_REGEXthe regex matching file names containing created tests, e.g. **/*DiffblueTest*.java. Deprecated in version 2.2; use DIFFBLUE_TEST_FILE_GLOB_PATTERN instead.Maven
DIFFBLUE_TEST_FILE_GLOB_PATTERNthe pattern matching file names containing created tests, e.g. **/*DiffblueTest*.javaMaven
DIFFBLUE_TEST_FILE_REGEX_PATTERNthe regex matching class names containing created tests, e.g. .*DiffblueTest.*\.javaMaven
--- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://cover-docs-preview.diffblue.com/features/cover-cli/project-configuration/configuring-cover-to-work-with-your-projects-build-system/configuration-file-in-detail.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.