Configuring Diffblue Cover

When you add a project, Diffblue Cover will attempt to detect your project settings so that it is able to build your code, run existing tests and write new tests to reach the maximum coverage. It will look for a build system config file in your project, e.g. pom.xml (maven), build.gradle (gradle) or build.xml (ant). Any changes made to the project after the initial creation can render these unusable, for example moving the pom.xml to a different directory in the project.

How to configure

There are two methods available to configure your project, either via a file diffblue.yml that is inside the project's source code or via the settings screen for the project. Settings provided via the user interface will always take higher precedence than those specified in the diffblue.yml file.

Adding a configuration file to your project

Add the file diffblue.yml into the root of the source for the project you wish to analyse.

Example configuration file

buildCmd: |-
  cd main_module
  mvn -e -X -Dmaven.test.skip=true compile
testCmd: |-
  cd main_module
  mvn test
classpathCmd: |-
  grep -o ' -classpath [^ ]* ' ../results/build_log.txt | awk '{print $2}'
timeout: 500
skipVerication: true
ignoreExistingCoverage: true

Configuration options

The following is a list of options that you can use to get specific behaviour from Diffblue Cover.


A command or multi line script if placed in diffblue.yml (see above example) that will be called to compile your source into Java byte code.


This should compile the project, but not compile the tests. After it runs, Diffblue Cover will instrument any class files it finds to measure the coverage of your existing tests. If this step also compiles the tests, the tests themselves will be instrumented for coverage, and then Diffblue Cover will attempt to write tests for them, which is not something you normally want to happen. It is also recommended that the build tool outputs a classpath to stdout, or a separate file, during this step for use in the classpathCmd. The defaults that Diffblue Cover will provide on detection, also in the example below, assume this.



mvn -e -X -Dmaven.test.skip=true compile


gradle build


Command to compile and run the tests.


It is important that this not recompile the non-test parts of the codebase as this will remove the instrumentation, meaning Diffblue Cover will not be able to measure the coverage of your existing code.



mvn test


gradle test -x compileJava

The -x compileJava part is needed to ensure gradle does not recompile the non-test classes which Diffblue Cover has instrumented.


A command to output a full class path that can be used to run the projects compiled byte code


Our recommended approach is for the buildCmd to output the classpath to stdout, or alternatively a text file. The classpathCmd then needs to just print out this file via cat or manipulate the output of the buildCmd in any way necessary. The output of the buildCmd can be accessed in ../results/build_log.txt which is relative to where the buildCmd is run.



grep -o ' -classpath [^ ]* ' ../results/build_log.txt | awk '{print $2}'

Assumes the buildCmd specified in the buildCmd section


# Backup gradle build file
cp build.gradle build.gradle.dbBackup

# Append to gradle build file
echo "
task diffbluePrintClasspath {
  doLast {
    def file = new File('diffblue-classpath.txt')
    configurations.testRuntime.each { file.append( ':'+it.toString() )}
" >> build.gradle
gradle diffbluePrintClasspath
cat diffblue-classpath.txt
# Restore original gradle build file
mv build.gradle.dbBackup build.gradle


This option controls how long Diffblue Cover will wait for results. Defaults to 1800 seconds (30 min).


Shorten to get results more quickly, but you might reduce the number of tests Diffblue Cover is able to create and therefore how much coverage you get.


This option skips verification checks that confirm if the produced tests both compile and pass.


Saves time if you are in a hurry.

It's possible that not all created tests will be correct. Normally Diffblue Cover will attempt to run the tests it has written in order to verify that they work as it expected. When Diffblue Cover is able to run and verify some of the tests, only the verified tests will be displayed. In certain cases, for example if the classpath is not configured correctly, Diffblue Cover may be unable to successfully verify any of the tests it produces. When this happens, all tests will be displayed to the end user.


This option writes tests even for parts of the code that have existing coverage.


If you plan on refactoring and want to write more regression tests to be sure nothing changes, you might want this, but Diffblue Cover may reduce the extra coverage it produces as it will have to work harder and may timeout.


This option will instruct Diffblue Cover to ignore the phases in its default settings.


If you wish to straightforwardly define your analysis phases in your diffblue.ymlor project settings, setting this option will disable the default phases completely. As such the only phases to run will be those you have defined, and the settings for those phases will not be merged with those of any corresponding default phase. This is especially useful if you wish to run an analysis with fewer phases than the default settings.


This option will instruct Diffblue Cover to ignore the root level cbmcArguments in its default settings.


Root level cbmcArguments are used as defaults for all phases, and some phase independent settings (e.g cover, cover-include-bytecode) can only be set in this location. Setting this option disables these defaults, so that only root level cbmcArguments that are defined in your diffblue.ymlor project settings are applied.


This option will instruct Diffblue Cover to only analyze the specified functions


The option is set using an array of strings that are prefixes of full function names, including signature suffix (without java::). Workers are only started for functions that match one of the entryPointsInclude prefixes (AND none of the entryPointsExclude prefixes, see below). An empty entryPointsInclude array means 'include all'.


This option will instruct Diffblue Cover to skip analyzing the specified functions


The option is set using an array of strings that are prefixes of full function names, including signature suffix (without java::). Workers are not started for functions that match one of the entryPointsExclude prefixes. An empty entryPointsInclude array means 'exclude nothing'.

User wide configuration

Sometimes it makes sense to add configuration user-wide, for example to set up Diffblue Cover to operate in a manner similar to your organisations standard build. Diffblue Cover allows you to specify a Maven config file (settings.xml) directly, and/or you can upload any user-required files you may need and run a script before each build to move them to the correct locations.

Adding settings.xml

If you have a specific Maven configuration for a given user, you can use settings.xml. For more information see

You can use the web UI to add settings.xml:

  1. Navigate to User profile.
  2. Under Configuration files, click Upload Maven settings file.
  3. You will be presented with a new pane, click Choose file.
  4. Select file, from your file system i.e. settings.xml.
  5. Click Upload.

Adding a user-files archive

If all your builds require specific files other than Maven's settings.xml, you can upload a zip archive. The files become available to your build at the path /user-files. This can be used, for example, to save encryption certificates for authentication to maven repositories using client SSL.

Configuring prebuildCmd

prebuildCmd is a shell script that runs immediately before the projects buildCmd from the folder that contains the project source code (Usually /diffblue-workspace/version-new/). Note that as this runs before the buildCmd, any errors in this command will cause all analyses to fail. The output will be written to a log that is available in the api for each analysis at /projects/[project]/analyses/[analysis]/log/prebuild.


prebuildCmd can be used to move files from /user-files to wherever they are needed for builds. For example, if you need a .mavenrc file to set up SSL authentication, you can add a file called mavenrc to your user-files archive and use:

cp /user-files/mavenrc ~/.mavenrc

as your prebuildCmd to copy it to the right place.

You could also include trust.jks and certificate.p12 files in your user-files, and the mavenrc file could contain something like:

MAVEN_OPTS="-Xmx512m \

results matching ""

    No results matching ""