For Diffblue Cover to write tests successfully, it needs your code to both compile and run. For the best results, your project needs to be completely built from the root. If this doesn't work, you may have an error in your built dependencies.

Potential issues

Being able to execute your unit tests means that the following must be available:

• All class files that are produced by compilation of your project.

• All the dependencies (i.e. other modules in your project and jar files). Note that jar files contain class files and may, in turn, depend on other jar files.

These jar files are typically downloaded by your build system (e.g. Maven or Gradle).

(You also need the Java Class Library provided with your JDK, but Diffblue Cover will work out your JDK version and find the appropriate classes.)

Class errors

Sometimes you might succeed in compiling your code, but when you run either your application or your tests you receive an error that a class was not found. This happens when dependencies are missing that were not necessary for compilation, but they are still required for execution.

"Class not found" errors indicate that the project wasn’t compiled correctly and/or that something is wrong or missing in your build configuration (e.g. pom.xml) or your Java environment. In these situations, Diffblue Cover is unable to run the unit tests it writes until you can fix these problems.

Fixing build or compilation issues

First, ensure that you have compiled multi-module projects from the root, using a command such as:

$ mvn clean install -DskipTests

Please note that even though you can choose to run dcover from within one module you want to create tests for, you have to run the compilation command from the root of your project, not from within a module.

Example 1

The example below uses the multi-module Maven project JDMN. Download the project and switch to the release 3.10.0:

git clone https://github.com/goldmansachs/jdmn
cd jdmn
git checkout 3.10.0

If we simply run mvn compile the project does not compile correctly, and dcover is unable to write tests. Use the command mvn clean install -DskipTests instead to compile the project and write tests successfully.

Example 2

Another common mistake is to use the correct command but inside a module, for example:

$ cd dmn-tck-it
$ mvn clean install -DskipTests

In this example, the compilation 'succeeds', but hides other problems. All the required dependencies were downloaded by Maven from the central repository. One of these dependencies was dmn-core, a module provided by the same project. But the version of that module that Maven downloaded may not match the code we have in the local module, or be able to compile it, e.g.

$ ls ../dmn-core/target
ls: ../dmn-core/target: No such file or directory

This could be a problem if, for example, we make changes to dmn-core{: .language-plaintext} and expect the code in dmn-tck-it{: .language-plaintext} to exercise those changes.

To fix this, return to the project root and run mvn clean install -DskipTests{: .language-plaintext} from there:

$ cd ..
$ mvn clean install -DskipTests

You can now either run dcover from the project root, or change directory into the module that you would like to create tests for, and run dcover create. If this still does not work, then please look at your build configuration.

Finding errors in your build configuration

Typical problems arise from system scope dependencies and exclusions:

• System scope dependencies are sometimes used to bake commonly used dependencies into a prepared environment (e.g. server or CI image). So it could happen that these dependencies are not installed in your local environment. The solution is to ensure that your local environment conforms to the runtime environment on your servers or CI system.

• Exclusions specify that certain transitive dependencies should be excluded from your classpaths. It can happen that such an exclusion is incorrect, excluding classes that are actually needed. The solution in this case is to find the faulty exclusion and fix your build configuration.

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:

dcover create -Dproperty1=value1

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

mvn test -Dproperty1=value1

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

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

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

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