Analysis parameters

When you're analyzing a project, Diffblue Cover performs multiple analysis passes over the code. Each pass can use different parameters to cover as much of the code as possible. These passes are known as phases.

The core configuration file for Diffblue Cover is diffblue.yml. It is stored in the root of your project.

Here’s an example of a simple diffblue.yml file showing parameters at the beginning of the file, which apply throughout the analysis, and others which apply only for the duration of a particular phase.

cbmcArguments:
  classpath: '/tools/cbmc/models-simple-overlay.jar:/tools/cbmc/models.jar:.'
  depth: false
phases:
-
  timeout: 60
  cbmcArguments:
    unwind: 1
-
  timeout: 120
  cbmcArguments:
    unwind: 2
-
  timeout: 300
  cbmcArguments:
    unwind: 3

The phases section in a diffblue.yml file contains one sub-section for each analysis phase. Each phase has a timeout parameter (in seconds). A parameter set in any of the phases is independent of other phases and overrides any default 'cbmcArguments'. Options with the prefix 'cover' (e.g. 'cover', 'cover-include') cannot be set per phase. Set them in the root cbmcArguments block.

The phases section in a diffblue.yml file should contain one array item for each analysis phase. A parameter set in any of the phases is independent of other phases and overrides any parameters set in the rest of the diffblue.yml.

For example:

timeout: 1000
cbmcArguments:
  depth: 10
phases:
-
  cbmcArguments:
    depth: 20
-
  timeout: 2000

In this example, timeout and depth are set to 1000 seconds and 10 instructions respectively. In the first phase depth is overridden from 10 to 20, while in the second phase timeout is overridden from 1000 to 2000.

You don't have to use a YAML file. Instead, you can use the Diffblue Cover UI or simply use the defaults that are built in. The precedence for parameters is:

  1. Parameters you set in the UI
  2. Parameters you set in diffblue.yml
  3. Defaults

To find the values of parameters for an analysis in the Diffblue Cover UI:

  1. Navigate to the Results window.
  2. Select the Configuration tab.
  3. Open the Phases section.

Performance options

The parameters defined in this section can influence analysis time, which in turn can affect coverage:

Simple library of models

Diffblue Cover uses a modeled version of the JDK classes which is suited for test generation. If execution times out, there is the option to fall back to a simple, more restrictive model. For instance, in this configuration all containers (ArrayList, HashMap, HashSet, ...) have a maximum size of one.

To use the simpler models you need to add them to the classpath, in front of the ordinary models:

classpath: '/tools/cbmc/models-simple-overlay.jar:/tools/cbmc/models.jar:.'

This is often set as an overall parameter rather than per-phase, though there may be situations where prepending simple models to the classpath in individual phases would be preferable.

In this setting, if we find a class in the simple models (models-simple-overlay.jar), it will be used. Otherwise, Diffblue Cover will look in the ordinary models (models.jar).

Note that in this configuration, the ordinary models will never be used if the class exists in the simple models.

Covering specific cases

It is sometimes necessary to tell Diffblue Cover to perform a deeper analysis to extract some corner cases.

Mocking options

There are two main reasons why we would want to mock a method in the generated tests:

  • No definition: If a class was not loaded by Diffblue Cover (for example, to increase performance) or if a class is missing from the library of JDK models, then we want to mock the missing methods so that we can still generate tests by mocking the behavior of these methods.

  • I/O and unpredictable returns: we can specifically mock a method by using the java-mock-class described below

  • java-external-code-action

  • java-mock-class

results matching ""

    No results matching ""