Diffblue Logo
Go to diffblue.com

Get unit tests for your Java code automatically with our free IntelliJ plugin. Download now

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"