Quick guide

How can I see all the build system commands that Cover would execute on my project?

Run dcover build-debug to see the currently configured build system commands for each phase, without actually executing them. This command can be used as part of a quick feed-back loop allowing you to modify your DiffblueBuild.yaml file and inspect the changes you’ve made without needing to invoke any other Cover CLI commands.

How do I customise the behaviour?

Create a DiffblueBuild.yaml or DiffblueBuild.yml file either in the root of your project or in its module, depending on whether you want to customise Cover's behaviour for your whole project or just a particular module.

To populate the file, you have two options. The first option is to copy and paste the minimal configuration shown in the Overview section, and extend it as desired. You can follow the instructions in this quick guide to learn how to set up the most common customisations. Note that the file must describe all the interactions between Cover and your project's build system.

The second, recommended option is to retrieve Cover's default configuration and adjust it as needed. In order to do that, run dcover build-debug --dump=maven or dcover build-debug --dump=gradle which will print out Cover's default configuration between two markers (--- BEGIN/END CONFIGURATION ---). Copy and paste this content into your DiffblueBuild.yaml. Now you can make changes to it as desired.

How do I change the timeout globally or for a specific phase?

The timeout key in the global block allows you to set a timeout for all phases unless the phase defines its own timeout. The value must be a valid ISO-8601 duration format (viz. PnDTnHnMn.nS, for example 60 minutes is PT60M).

How do I add an option to all invocations of my build system?

In the global block you can add a list of flags that will be applied to all commands in the configuration file. Flags can be any command line options or properties with specific values.

Maven

DiffblueBuild.yaml

global:
 flags:
   - --commandLineOptionName
   - -DpropertyName=propertyValue

Gradle

DiffblueBuild.yaml

global:
 flags:
   - --commandLineOptionName
   - -DsystemPropertyName=propertyValue
   - -PprojectPropertyName=propertyValue

Note: The handling of spaces in properties is not supported at the moment; you must use the = sign to set the property value. No warnings will be emitted to this effect and you may find the command you’re configuring fails to execute.

How do I configure a build system plugin that isn’t already configured?

In the global block you can add a list of plugins with an appropriate configuration. For example, in Maven, the configuration the license-maven-plugin can look as follows:

DiffblueBuild.yaml

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

To disable the plugin, Cover will lookup the goals named disable. To enable, Cover will look up the goals named format. In both cases, if there is a goal specified, the resultant argument will be a concatenation of the name and the goal , and if there is a flag specified, it will too be added to the resultant argument. For the above example, the resultant arguments are:

• to enable the plugin: … com.mycila:license-maven-plugin:format …

• to disable the plugin: … -Dlicense.skip=true …

How do I adjust the behaviour of a goal?

To adjust the behaviour of a goal in a list of goals, you can adjust its flags, goal and name. The flags will be added after the name:goal (or just goal if name is not present – indicated with ~).

Note: Maven’s lifecycle goals are not the same as those of the corresponding plugins. For example, org.apache.maven.plugins:maven-install-plugin:install is not the same as install.

How do I adjust the behaviour of phases?

Phases contain a list of goals to add to an invocation of the build system. Some phases have multiple goals, others have a single goal. The structure of the goal has been described above. To adjust the behaviour of a phase add or remove a goal from the list of goals.

How do I include/exclude test classes?

During the test and coverage phases Cover needs to be able to run a single (named) test class, a set of tests that have been created by Diffblue Cover (onlyDiffblue), the set of tests that have not been created by Diffblue Cover (neverDiffblue) and all tests regardless of who/what created them (default). These four elements define a filter for the phase.

Maven

DiffblueBuild.yaml

phases:
  test:
    filter:
      default: ~
      neverDiffblue:
        - -Dtest=!${DIFFBLUE_TEST_FILE_REGEX},**/Test*.java,**/*Test.java,**/*Tests.java,**/*TestCase.java
      onlyDiffblue:
        - -Dtest=${DIFFBLUE_TEST_FILE_REGEX}
      named:
        - -Dtest=${DIFFBLUE_TEST_FILE}

Gradle

DiffblueBuild.yaml

phases:
  test:
    filter:
      default: ~
      neverDiffblue:
        - -PexcludeTests=${DIFFBLUE_TEST_CLASS_REGEX}
      onlyDiffblue:
        - -PincludeTests=${DIFFBLUE_TEST_CLASS_REGEX}
      named:
        - --tests=${DIFFBLUE_TEST_CLASS}

Note: The Gradle filters use the name of the class whereas Maven filters use the name of the file.

Note: Under Gradle, there’s no command line option to exclude tests from the test suite. This (and a property to include tests) are configured as part of the plugin used to listen to events.