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
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
timeout: 1000 cbmcArguments: depth: 10 phases: - cbmcArguments: depth: 20 - timeout: 2000
In this example,
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:
- Parameters you set in the UI
- Parameters you set in
To find the values of parameters for an analysis in the Diffblue Cover UI:
- Navigate to the Results window.
- Select the Configuration tab.
- Open the Phases section.
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:
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.
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