# Building a Maven project

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

## Compiling the project

If your project uses the Maven build system, `cd` into the directory containing the `pom.xml` file. This is typically located at the root of your repository.

To compile the project, run the `mvn install` command. If successful, you should see a `BUILD SUCCESS` message towards the end of the output from Maven. Note that we recommend `mvn install` rather than `mvn compile` because the former may produce configuration files which have to be taken into account to verify the tests.

## Maven 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.

If you have supplied these system properties to `dcover`:

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

Then you must also supply those same system properties to `Maven` when executing your tests, either as command line options:

```groovy
mvn test -Dproperty1=value1
```

Or in the `<environmentVariables>` section of your `Surefire` plugin configuration:

```groovy
<plugin>
  <artifactId>maven-surefire-plugin</artifactId>
    <configuration>
      <systemPropertyVariables>
        <property1>value1</property1>
      </systemPropertyVariables>
    </configuration>
</plugin>
```

## Maven Troubleshooting

### Checkstyle Plugin

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

If your project uses the `Checkstyle` plugin (<https://maven.apache.org/plugins/maven-checkstyle-plugin/>) please either:

* Allow the tests to be verified using the command `--ignore-stylecheck=true`
* Amend the pom file to exclude Diffblue tests, as shown in the example below.

```groovy
<plugin>
   <groupId>org.apache.maven.plugins</groupId>
   <artifactId>maven-checkstyle-plugin</artifactId>
      <configuration>
         <excludes>**/generated/**/*</excludes>
      </configuration>
</plugin>
```

### JUnit Platform Launcher jar

When using JUnit Jupiter, `dcover` detects and utilizes the JUnit Platform Launcher jar used by your `Maven Surefire` plugin. There is **no need** to include the `junit-platform-launcher` jar as a test dependency.

Including an incompatible launcher dependency may even cause execution of your `mvn test` phase to fail. The snippet below captures the output of such a failure:

```
[ERROR] There was an error in the forked process
[ERROR] java.lang.NoClassDefFoundError: org/junit/platform/commons/util/ClassNamePatternFilterUtils
[ERROR] org.apache.maven.surefire.booter.SurefireBooterForkException: There was an error in the forked process
```

## Debugging Information

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

```xml
<plugin>
  <groupId>org.apache.maven.plugins</groupId>
  <artifactId>maven-compiler-plugin</artifactId>
  <configuration>
    <debug>true</debug>
  </configuration>
</plugin>
```

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 Maven documentation, see the [compiler:compile](https://maven.apache.org/plugins/maven-compiler-plugin/compile-mojo.html#debuglevel) topic.