Knowledge Base > DCover CLI > Custom Inputs
Customizing Test Inputs
Background
A key feature of Diffblue Cover is automatically identifying appropriate inputs necessary to write tests for a given method under test.
Sometimes Diffblue Cover is unable to find appropriate inputs and thus does not produce useful tests. One such example is with the open source XXL-JOB project where Cover fails to produce tests for the CronExpression
class, resulting in an R013
output code:
com.xxl.job.admin.core.cron.CronExpression.<init>
R013: No inputs found that don't throw a trivial exception
Diffblue Cover tried to run the arrange/act section, but the method under
test threw
java.lang.NullPointerException
at com.xxl.job.admin.core.cron.CronExpression.<init>(CronExpression.java:295)
In order to prevent <init>(CronExpression)
from throwing NullPointerException, add constructors or factory
methods that make it easier to construct fully initialized objects used in
<init>(CronExpression).
See https://diff.blue/R013 to resolve this issue.
Also, because the R013
occurs in the primary constructor for the class under test, Diffblue Cover is then unable to produce CronExpression
instances for a further 28 methods and R008
output codes:
com.xxl.job.admin.core.cron.CronExpression.addToSet
R008: Failed to instantiate class under test
Diffblue Cover was unable to construct an instance of CronExpression.
Add a package-visible constructor or a factory method for testing which
(ideally) takes no arguments, and does not throw, return null or return
a subtype.
See https://diff.blue/R008
Experienced developers or system administrators will immediately recognize the concept of “cron expressions” and suppose that tests likely need input strings of a very specific format in order to successfully construct a CronExpression
instance. In fact the javadoc in CronExpression.java
devotes over 100 lines of comments to explaining the requirements for this format - helpfully providing an example of a valid cron expression string: "0 0 14-6 ? * FRI-MON"
. Developers can therefore produce a DiffblueRules.yml
file in the repository with the following contents to provide the necessary hints:
java.lang.String:
- immediate: "0 0 14-6 ? * FRI-MON"
parameter: cronExpr
With this configuration file in place, when java.lang.String
values are required, Diffblue cover will try to use the constant cron expression value (immediate: "0 0 14-6 ? * FRI-MON"
) if the parameter begins with cronExpr
(parameter: cronExpr
). Using just this 1 custom input allows this class to go from 54 tests with 21% line coverage to 194 tests with 59% line coverage.
Rules Location
Custom rules are loaded from the project working directory and any of its ancestor directories. Assuming you have your project checked out into ~/Projects/MyProject
and are working with a module SomeModule
within that, then rules will be read from each of the following locations in order, if they exist:
~/Projects/MyProject/SomeModule/DiffblueRules.yml
~/Projects/MyProject/DiffblueRules.yml
~/Projects/DiffblueRules.yml
~/DiffblueRules.yml
- …
/DiffblueRules.yml
The intention here is that module and project level rules can be checked into the project source control system, but additional fallbacks into the user home directory are also possible. Rules are loaded from each discovered file in order, and so applicable rules local to the module will take precedence over rules defined at a wider scope.
Rules Format
Custom rules are defined in a YAML format with the structure shown here. Rules are grouped by the type of input produced, and so the top level keys are the type being produced, each with a list of rules at the next level down. For example the following would mean that the constant values "Diffblue"
, "Cover"
, "Custom"
, "Inputs"
are all considered as candidate values to use whenever a String
is required. Note that this does not guarantee that all of these constant values will be used, in practice the first candidate constant value may produce full coverage and so further candidate values are not needed.
java.lang.String:
- immediate: "Diffblue"
- immediate: "Cover"
- immediate: "Custom"
- immediate: "Inputs"
immediate:
Rule
The first supported mechanism for producing values is via immediate constant values. This mechanism supports primitives and java.lang.String
. Rules using this mechanism will have an immediate: <constant>
component. For example the following configuration specifies a single unconditional default rule for each supported type:
boolean:
- immediate: true
byte:
- immediate: 65 # 0x41
char:
- immediate: '*'
float:
- immediate: 888.888f
double:
- immediate: 12345.6789
int:
- immediate: 7 # low values are recommended in case used for resource allocation
long:
- immediate: -23
short:
- immediate: 291 # 0x0123
java.lang.String:
- immediate: "Lorem ipsum dolor sit amet"
factory:
Rule
The second supported mechanism for producing values is via factory methods.
This mechanism supports producing class and interface instances, but not arrays, enumerations, java.lang.String
or primitives.
Factory methods must meet the following criteria in order to be used:
- Must be
static
methods or constructors. - Must have
public
visibility. - Any parameters must be able to take
java.lang.String
or primitive values. - Must have a return type assignable to the requested type.
Any factory methods that don’t fit these criteria, or cannot be loaded with the user’s classpath will be silently ignored.
The factory rule syntax will have a factory:
key, with sub-keys of method:
and parameters:
.
The method sub-key must be filled with a method identifier, starting with a class name, followed by a dot and then the method name (or <init>
for constructors).
The identifier is completed with a colon and the javap
style method descriptor.
The parameters sub-key must be filled with a list of values to be used as the parameters.
For example, if you are working with a library then you might need to deal with International Standard Book Numbers in the form of an ISBN
class, created by parsing ISBN formatted strings.
On it’s own, DCover may not be able to discover valid ISBN string formats, in which case custom rules could be used to specify a couple of valid ISBN
values that can be used to test methods that require an ISBN
instance:
com.example.library.ISBN:
- factory:
method: com.example.library.ISBN.parse:(Ljava/lang/String;)Lcom/example/library/ISBN;
parameters: [ "1-56619-909-3" ] # An 'old' style ISBN-10 formatted identifier
- factory:
method: com.example.library.ISBN.parse:(Ljava/lang/String;)Lcom/example/library/ISBN;
parameters:
- "978-1-56619-909-4" # A 'new' style ISBN-13 formatted identifier
properties:
Rule
The properties rule is a special case rule specifically for creating and populating a java.util.Properties
instance.
The properties rule can specify a file using an absolute or relative path to a .properties
file.
When an absolute path is provided then that absolute path will be used directly from the test.
When a relative path is provided then the properties file will be located relative to the DiffblueRules.yml
, and will be re-resolved against the project’s working directory.
For example, given the following rule supplied in the project root:
java.util.Properties:
- properties:
file: relative-file.properties
Then tests will attempt to populate a java.util.Properties
instance as follows:
BufferedReader newBufferedReaderResult = Files.newBufferedReader(Paths.get("relative-file.properties"));
Properties properties = new Properties();
properties.load(newBufferedReaderResult);
newBufferedReaderResult.close();
Alternatively the properties rule can specify a classpath resource to load. Resources are loaded relative to the class under test, so typically an absolute resource path should be used.
For example, given the following rule:
java.util.Properties:
- properties:
resource: /resource.properties
Then tests of ExampleApp
will attempt to populate a java.util.Properties
instance as follows:
InputStream resourceAsStream = ExampleApp.class.getResourceAsStream("/resource.properties");
Properties properties = new Properties();
properties.load(resourceAsStream);
resourceAsStream.close();
Conditions
Typically a custom constant value is associated with one or more conditions for when this custom value should be used. When producing inputs for a particular method, supported conditions allow matching against the fully qualified class name, method name, or parameter name. For ease of use, matching is typically performed using case-insensitive substrings, but if finer control is required then the pattern can be wrapped in a ^
and $
and the pattern will be treated as a regular expression instead.
Consider the following example code under test and the numbered contexts where string inputs need to be produced:
package com.example.myapp;
class MyExampleClass {
static MyExampleClass parse(String text /* Context #1 */) {
...
}
void doSomething(String firstParam /* Context #2 */, String secondParam /* Context #3 */) {
...
}
void doSomethingElse(String firstParam /* Context #4 */) {
...
}
}
class SomeOtherClass {
void doIt(String firstParam /* Context #5 */) {
...
}
}
class:
Condition
Class name conditions match against the fully qualified class name, com.example.myapp.MyExampleClass
in context #1-4 above, or com.example.myapp.SomeOtherClass
in context #5. For example class: "example.myapp"
and class: "^.*Class$"
could both be used to match all contexts above.
method:
Condition
Method name conditions match against the name of the method, parse
in context #1 above, doSomething
in #2-3. For example method: "parse"
would match context #1, whereas method: "^do.*$"
would match contexts #2-5.
parameter:
Condition
Parameter name conditions match against the name of the parameter, text
in context #1 above, firstParam
in contexts #2,4,5. For example parameter: "text"
would match context #1 above, parameter: "^.*Param$"
would match contexts #2-5.
Condition Combination
Up to one of each condition can be combined in a single rule, so for example the following rule can be used to offer the input “Hello World!” only in context #4 above:
java.lang.String:
- immediate: "Hello World!"
method: "doSomethingElse"
parameter: "firstParam"