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.

buildCmd

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.

Usage

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.

Examples

Maven:

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

Gradle:

gradle build

testCmd

Command to compile and run the tests.

Usage

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.

Examples

Maven:

mvn test

Gradle:

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.

classpathCmd

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

Usage

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.

Examples

Maven:

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

Assumes the buildCmd specified in the buildCmd section

Gradle:

# 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')
    file.write('.')
    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

timeout

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

Usage

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.

skipVerification

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

Usage

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.

ignoreExistingCoverage

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

Usage

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.

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 https://maven.apache.org/settings.html.

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.

Example

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 -Djavax.net.ssl.trustStore=/user-files/trust.jks \
                     -Djavax.net.ssl.trustStorePassword=XXXXXX  \
                     -Djavax.net.ssl.keyStore=/user-files/certificate.p12 \
                     -Djavax.net.ssl.keyStoreType=pkcs12 \
                     -Djavax.net.ssl.keyStorePassword=XXXXXX"

results matching ""

    No results matching ""