# Building a Gradle project

Tips for successfully building a Gradle project - an essential prerequisite for using Cover CLI.

## Compiling the project

If your project uses the Gradle build system, `cd` into the directory containing the build script (`build.gradle` or `build.gradle.kts`), this is typically located at the root of your repository.

To compile the project, if a `gradlew` (or `gradlew.bat` on Windows) file is present, run the `./gradlew build` command, otherwise run `gradle build`.

It is generally preferable to execute Gradle commands using `./gradlew` (or `gradlew.bat` on Windows) rather than `gradle` if these Gradle wrapper scripts are present in your project.

In either case, if successful, you should see a `BUILD SUCCESSFUL` message towards the end of the output from Gradle:

```
BUILD SUCCESSFUL in 15s
7 actionable tasks: 2 executed, 5 up-to-date
```

In order to run Diffblue Cover CLI it is essential that your Gradle project builds successfully. If it finds a Gradle project, Cover will call Gradle to determine your project settings. If your Gradle project fails then Cover will exit with an error message (and reason):

```
ERROR An error was encountered while building the Gradle project at ...
```

If there is a Gradle wrapper for your project (`gradlew`, `gradlew.bat`), Cover will use the wrapper's declared version in preference to your system's installed Gradle version.

## Gradle and user-specified system properties

The `-D` or `--define` option allows the user to pass additional system properties to `dcover` for test creation and execution.

Any created tests *may* depend upon these user-specified system properties and *may not* execute successfully without them.

Unfortunately by default `Gradle` does not forward command line system properties to test execution. Therefore out-of-the-box `dcover` may fail to [`validate your tests`](/features/cover-cli/writing-tests/test-validation.md).

You can overcome this issue with additional configuration. If you have supplied these system properties to `dcover`:

```groovy
dcover create -Dproperty1=value1 -Dproperty2=value2
```

Then you must also supply those same system properties to `Gradle` test execution *before* running `dcover create`.

Specify your system properties in the `test` task:

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

```groovy
test {
  systemProperty 'property1', 'value1'
  systemProperty 'property2', 'value2'
}
```

{% endtab %}

{% tab title="KOTLIN" %}

```kotlin
tasks {
  test {
    systemProperty("property1", "value1")
    systemProperty("property2", "value2")
  }
}
```

{% endtab %}
{% endtabs %}

Keeping these properties in sync will ensure that [`test validation`](/features/cover-cli/writing-tests/test-validation.md) will succeed and that your created tests can be executed successfully from `Gradle`.

## Gradle Troubleshooting

### JUnit Jupiter Platform Launcher jar

When using JUnit Jupiter, `dcover` relies upon the JUnit Platform Launcher jar to verify created tests. Without this jar `dcover` will not be able to verify that created tests execute successfully in your build environment. You may see this warning message if the launcher jar is not available from your test configuration:

```
13:11:32.487 INFO Checking test environment...
13:11:39.515 ERROR E011: Problems in the local build environment have been detected that will prevent Diffblue Cover from validating the generated tests.
```

To prevent this issue you must configure your build script to supply the corresponding `junit-platform-launcher` for your JUnit engine at test runtime:

```groovy
dependencies {
  testImplementation("org.junit.jupiter:junit-jupiter-api:5.7.1")
  testRuntimeOnly("org.junit.jupiter:junit-jupiter-engine:5.7.1")
  testRuntimeOnly("org.junit.platform:junit-platform-launcher:1.7.1")
}
```

In the example above `1.7.1` is the correct version of the platform launcher for the `5.7.1` version of the engine. See the [JUnit user guide](https://junit.org/junit5/docs/current/user-guide/#running-tests-ide) for further details about this.

### Checkstyle Plugin

If `dcover` cannot verify the tests it creates due to an incompatibility with the stylecheck used in your environment, you will receive an error message.

If your project uses the Gradle Checkstyle plugin (<https://docs.gradle.org/current/userguide/checkstyle_plugin.html>), amend the build script to exclude Diffblue tests, as shown in the example below:

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

```groovy
tasks.withType(Checkstyle) {
    exclude '**/*DiffblueTest**'
}
```

{% endtab %}

{% tab title="KOTLIN" %}

```kotlin
tasks.withType<Checkstyle> {
  exclude("**/*DiffblueTest**")
}
```

{% endtab %}
{% endtabs %}

## Debugging Information

Class files should be compiled with debug information included for Diffblue Cover to write the best tests possible. If you have switched off debug information, please switch it back on again:

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

```groovy
tasks.withType(JavaCompile) {
  configure(options) {
    options.debug = true
  }
}
```

{% endtab %}

{% tab title="KOTLIN" %}

```kts
tasks.withType<JavaCompile> {
  options.isDebug = true
}
```

{% endtab %}
{% endtabs %}

The underlying `javac` Java compiler can use a `-g` option to generate all debugging information, if you're using custom compiler arguments then please ensure the `-g` option and not `-g:none` are present.

For Gradle documentation, see [CompileOptions](https://docs.gradle.org/current/dsl/org.gradle.api.tasks.compile.CompileOptions.html#org.gradle.api.tasks.compile.CompileOptions:debug).


---

# 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/compiling-your-project/building-a-gradle-project.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.