# 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](#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-default-config --maven` , `dcover build-default-config --gradle`, or `dcover build-default-config --ant` which will save Cover's default configuration into a `DiffblueBuild.yaml` file in the current directory. See `dcover build-default-config --help` for further options such as printing to a specific directory or printing to console. Now you can make changes to your `DiffblueBuild.yaml` file 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.

{% tabs %}
{% tab title="Maven" %}
{% code title="DiffblueBuild.yaml" %}

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

{% endcode %}
{% endtab %}

{% tab title="Gradle" %}
{% code title="DiffblueBuild.yaml" %}

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

{% endcode %}
{% endtab %}

{% tab title="Ant" %}
{% code title="DiffblueBuild.yaml" %}

```yaml
global:
 flags: ~
```

{% endcode %}
{% endtab %}
{% endtabs %}

**Note:** The handling of spaces in properties is not supported at the moment; you must use the `=` sign to set the property value, or split the option across two items in the list. 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:

<pre class="language-yaml" data-title="DiffblueBuild.yaml"><code class="lang-yaml">global:
  plugins:
    - name: com.mycila:license-maven-plugin
<strong>      disable: disable
</strong>      enable: format
      flags: ~
      goals:
        - name: format
          goal: format
          once: true
          flags: ~
        - name: disable
          goal: ~
          flags:
            - -Dlicense.skip=true

</code></pre>

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 …`

Cover's default code formatter can be overridden by specifying your project's code formatter in the DiffblueBuild.yaml as shown above.

**Note:** Configuring additional build system plugins is not supported for Ant build systems.

## 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 `~`). By default the goals will be run for each module in the project but goals marked `once:true` will only be run once per project.

**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 different sets of tests based on specific filters. These filters include:

* A single (named) test class.
* The set of tests created by Diffblue Cover (`onlyDiffblue`).
* The set of tests tagged by Diffblue Cover (`onlyDiffblueTag`).
* The set of tests not created by Diffblue Cover (`neverDiffblue`).
* The set of tests not tagged by Diffblue Cover (`neverDiffblueTag`).
* All tests, regardless of their origin (`default`).

{% tabs %}
{% tab title="Maven" %}

<pre class="language-yaml" data-title="DiffblueBuild.yaml"><code class="lang-yaml"><strong>phases:
</strong><strong>  test:
</strong>    filter:
      default: ~
      neverDiffblue:
        - -Dtest=!${DIFFBLUE_TEST_FILE_REGEX},**/Test*.java,**/*Test.java,**/*Tests.java,**/*TestCase.java
      neverDiffblueTag:
        - -Dtest=!${DIFFBLUE_TEST_FILE_REGEX},**/Test*.java,**/*Test.java,**/*Tests.java,**/*TestCase.java
        - -DexcludedGroups=MaintainedByDiffblue,ContributionFromDiffblue      
      onlyDiffblue:
        - -Dtest=${DIFFBLUE_TEST_FILE_REGEX}
      onlyDiffblueTag:
        - -Dtest=!${DIFFBLUE_TEST_FILE_REGEX},**/Test*.java,**/*Test.java,**/*Tests.java,**/*TestCase.java
        - -Dgroups=MaintainedByDiffblue,ContributionFromDiffblue
      named:
        - -Dtest=${DIFFBLUE_TEST_FILE}
</code></pre>

{% endtab %}

{% tab title="Gradle" %}
{% code title="DiffblueBuild.yaml" %}

```yaml
phases:
  test:
    filter:
      default: ~
      neverDiffblue:
        - -PexcludeTests=${DIFFBLUE_TEST_CLASS_REGEX}
      neverDiffblueTag:
        - -PexcludeTests=${DIFFBLUE_TEST_CLASS_REGEX}
        - -PexcludeGroup=MaintainedByDiffblue,ContributionFromDiffblue
      onlyDiffblue:
        - -PincludeTests=${DIFFBLUE_TEST_CLASS_REGEX}
      onlyDiffblueTag:
        - -PexcludeTests=${DIFFBLUE_TEST_CLASS_REGEX}
        - -PincludeGroup=MaintainedByDiffblue,ContributionFromDiffblue
        - -PmergeCoverage=true
      named:
        - --tests=${DIFFBLUE_TEST_CLASS}
```

{% endcode %}
{% endtab %}

{% tab title="Ant" %}
{% code title="DiffblueBuild.yaml" %}

```yaml
phases:
  test:
    filter:
      default: ~
      neverDiffblue:
        - -Dtest.excludes=**/*DiffblueTest.*
      neverDiffblueTag:
        - -Dtest.excludes=**/*DiffblueTest.*
        - -Dtest.excludeTags=MaintainedByDiffblue,ContributionFromDiffblue
      onlyDiffblue:
        - -Dtest.includes=**/*DiffblueTest.*
      onlyDiffblueTag:
        - -Dtest.excludes=**/*DiffblueTest.*
        - -Dtest.includeTags=MaintainedByDiffblue,ContributionFromDiffblue
      named:
        - -Dtest.includes=**/${DIFFBLUE_TEST_FILE}.java
```

{% endcode %}
{% endtab %}
{% endtabs %}

**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.

**Note:** The Ant configuration will need to be adjusted to suit your project's configuration


---

# 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.diffblue.com/features/cover-cli/project-configuration/configuring-cover-to-work-with-your-projects-build-system/quick-guide.md?ask=<question>
```

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.