Mocking Annotations

Mocking annotations allow fine grained control over what mocking should be preferred when testing.

Using @InTestsMock

Perhaps you have a method that Diffblue Cover would ordinarily test using an Integer but you'd prefer to see it tested using Mockito.mock(..). In this case you could annotate the method (or class, or package) to recommend mocking Number:

public class ClassUnderTest {
  @InTestsMock(Number.class)
  public static String methodUnderTest(Number number) {
    return String.valueOf(number.intValue());
  }
}

Conversely, if Diffblue Cover normally does mock a particular class, and you have a particular location where it shouldn't be then you can forbid it:

public class ClassUnderTest { 
  @InTestsMock(value = Number.class, decision = MockDecision.FORBIDDEN)
  public static String methodUnderTest(Number number) {
    return String.valueOf(number.intValue());
  }
}

Note that using @InTestsMock has the same effect as, and can be overridden by, Cover CLI command line options:

dcover create --mock ClassToMock --disable-mock-inputs ClassToForbidMocking

Specifying values to return

When mocking a class, it can be useful to specify what each method returns. This can be achieved using the following attributes:

Attribute name
Description
Example usage

method

The simple name of the method to mock

method = "intValue"

booleanReturnValues

The boolean value (or an array of values) to return

booleanReturnValues = true or booleanReturnValues = {true,false}

byteReturnValues

The byte value (or an array of values) to return

byteReturnValues = (byte) 1 or byteReturnValues = {(byte) 1,(byte) 0}

charReturnValues

The char value (or an array of values) to return

charReturnValues = 'A' or charReturnValues = {'A','B'}

intReturnValues

The int value (or an array of values) to return

intReturnValues = 2 or intReturnValues = {2,3}

shortReturnValues

The short value (or an array of values) to return

shortReturnValues = 3 or shortReturnValues = {3,4}

longReturnValues

The long value (or an array of values) to return

longReturnValues = 4L or longReturnValues = {4L,5L}

floatReturnValues

The float value (or an array of values) to return

floatReturnValues = 5.0f or floatReturnValues = {5.0f,6.0f}

doubleReturnValues

The double value (or an array of values) to return

doubleReturnValues = 6.0d or doubleReturnValues = {6.0d,7.0d}

stringReturnValues

The String value (or an array of values) to return

stringReturnValues = "AAA" or stringReturnValues = {"AAA","BBB"}

returnValueFactory

The name of the static method to call to create the required object. The syntax is: fully qualified class name + method name, separated by a dot

returnValueFactory = "com.example.Factory.makeUser"

throwException

The class of the exception to throw when the method is called. Must be a subclass of Throwable with an accessible constructor.

throwException = IllegalArgumentException.class

throwExceptionFactory

The name of the static method to call to create the exception instance. The syntax is: fully qualified class name + method name, separated by a dot. The method must return a subclass of Throwable

throwExceptionFactory= "com.example.Factory.createCustomException"

For example, to return a value of 5 from the mocked method Number.intValue() , the following annotation could be used:

public class ClassUnderTest {
  @InTestsMock(value = Number.class, method = "intValue", intReturnValues = "5")
  public static String methodUnderTest(Number number) {
    return String.valueOf(number.intValue());
  }
}

To return an object, use a factory method. Diffblue Cover will call the specified static method and use its result as the mocked return value.

public class ClassUnderTest {
  @InTestsMock(
    value = AccountService.class,
    method = "getAccount",
    returnValueFactory = "com.example.Factory.createTestAccount"
  )
  public static String methodUnderTest(AccountService service) {
    return service.getAccount().getId();
  }
}

Specifying an array of values

Since a mocked method can only return a single value, why specify an array of values? Cover will try to use the values in the order they are specified. The value chosen is the value that provides the best test. In most cases, however, specifying only a single value will be sufficient for generating a test with good coverage.

Using multiple @InTestsMock annotations

You can specify multiple mocked methods by using the annotation more than once:

@InTestsMock(
  value = UserService.class,
  method = "getName",
  stringReturnValues = {"Alice"}
)
@InTestsMock(
  value = UserService.class,
  method = "getAge",
  intReturnValues = {30}
)
@InTestsMock(
  value = AccountService.class,
  method = "getAccount",
  returnValueFactory = "com.example.Factory.createTestAccount"
)
public boolean isValid(UserService user, AccountService account) {
  return user.getName().length() >= 3
      && user.getAge() >= 18
      && account.getAccount().getId().startsWith("test-");
}

Using @InTestsMockConstruction

Perhaps you have a method that Diffblue Cover is unable to test, and you think it could make more progress using Mockito.mockConstruction(Random.class). In this case, you could annotate the method (or class, or package) to recommend mocking construction of Random:

public class ClassUnderTest {
  @InTestsMockConstruction(Random.class)
  public static int methodUnderTest() {
    return new Random().nextInt();
  }
}

Note that using @InTestsMockConstruction has the same effect as, and can be overridden by, Cover CLI command line option:

dcover create --mock-construction ClassToMockConstruction

Using @InTestsMockStatic

Perhaps you have a method that Diffblue Cover is unable to test, and you think it could make more progress using Mockito.mockStatic(UUID.class). In this case, you could annotate the method (or class, or package) to recommend mocking static methods of UUID:

public class ClassUnderTest {
  @InTestsMockStatic(UUID.class)
  public static Path methodUnderTest() {
    return Paths.get(UUID.randomUUID() + ".zip");
  }
}

Note that using @InTestsMockStatic has the same effect as, and can be overridden by, Cover CLI command line option:

dcover create --mock-static ClassToMockStatic

Last updated

Was this helpful?