Configuration file in detail
The minimum configuration file that will be accepted by Cover (all the blocks below are required):
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.
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.
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.
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.
Last updated