Custom Input Annotations

Custom input annotations allow particular inputs to be recommended to Diffblue Cover when writing tests.

Using @InTestsUseStrings

The @InTestsUseStrings annotation allows you to recommend specific String values to use in tests. Sometimes this can be useful to control the values used for cosmetic reasons, but it can also be useful when Cover is unable to identify values to cover all cases. For example the following method is annotated with some genuine examples of song titles that can be used to achieve coverage:

public static boolean isDayRelatedSongTitle(@InTestsUseStrings({"I Don't Like Mondays", "Here Comes The Weekend"}) String title) {
    return Stream.of(DayOfWeek.values())
            .map(DayOfWeek::name)
            .map(String::toLowerCase)
            .anyMatch(title.toLowerCase()::contains);
}

Using @InTestsUseIntegers

The @InTestsUseIntegers annotation allows you to recommend specific int values to use in tests. Sometimes this can be useful to control the values used for cosmetic reasons, but it can also be useful when Cover is unable to identify values to cover all cases. For example the following method is annotated to use a specific preferred value:

public static String toUpperHexString(@InTestsUseIntegers(0xD1FFB) int input) {
    return Long.toHexString(input).toUpperCase();
}

Using @InTestsUseShorts

The @InTestsUseShorts annotation allows you to recommend specific short values to use in tests. Sometimes this can be useful to control the values used for cosmetic reasons, but it can also be useful when Cover is unable to identify values to cover all cases. For example the following method is annotated to use a specific preferred value:

public static String toUpperHexString(@InTestsUseShorts((short) 0xD1FF) short input) {
    return Long.toHexString(input).toUpperCase();
}

Using @InTestsUseLongs

The @InTestsUseLongs annotation allows you to recommend specific long values to use in tests. Sometimes this can be useful to control the values used for cosmetic reasons, but it can also be useful when Cover is unable to identify values to cover all cases. For example the following method is annotated to use a specific preferred value:

public static String toUpperHexString(@InTestsUseLongs(0xD1FFBL) long input) {
    return Long.toHexString(input).toUpperCase();
}

Using @InTestsUseBytes

The @InTestsUseBytes annotation allows you to recommend specific byte values to use in tests. Sometimes this can be useful to control the values used for cosmetic reasons, but it can also be useful when Cover is unable to identify values to cover all cases. For example the following method is annotated to use a specific preferred value:

public static String toUpperHexString(@InTestsUseBytes((byte) 0xD1) byte input) {
    return Long.toHexString(input).toUpperCase();
}

Using @InTestsUseFloats

The @InTestsUseFloats annotation allows you to recommend specific float values to use in tests. Sometimes this can be useful to control the values used for cosmetic reasons, but it can also be useful when Cover is unable to identify values to cover all cases. For example the following method is annotated to use a specific preferred value:

public static boolean isNearPi(@InTestsUseFloats(3.14159f) float input) {
    return Float.toString(input).startsWith("3.14");
}

Using @InTestsUseDoubles

The @InTestsUseDoubles annotation allows you to recommend specific double values to use in tests. Sometimes this can be useful to control the values used for cosmetic reasons, but it can also be useful when Cover is unable to identify values to cover all cases. For example the following method is annotated to use a specific preferred value:

public static boolean isNearPi(@InTestsUseDoubles(Math.PI) float input) {
    return Double.toString(input).startsWith("3.14");
}

Using @InTestsUseEnums

The @InTestsUseEnums annotation allows you to recommend specific Enum values to use in tests. Sometimes this can be useful to control the values used for cosmetic reasons, but it can also be useful when Cover is unable to identify values to cover all cases. For example the following method is annotated with the names of specific enum values preferred by the developer:

public static boolean isDateOrTimeBased(@InTestsUseEnums({"SECONDS", "YEARS", "FOREVER"}) ChronoUnit chronoUnit) {
    return chronoUnit.isDateBased() || chronoUnit.isTimeBased();
}

Using @InTestsUseClasses

The @InTestsUseClasses annotation allows you to recommend specific Class literal values to use in tests. Sometimes this can be useful to control the values used for cosmetic reasons, but it can also be useful when Cover is unable to identify values to cover all cases. For example the following method is annotated with an example class literal to achieve a positive test:

public static boolean isAnnotation(@InTestsUseClasses(Nullable.class) Class<?> theClass) {
    return theClass.isAnnotation();
}

Using @InTestsUseCharacters

The @InTestsUseCharacters annotation allows you to recommend specific char values to use in tests. Sometimes this can be useful to control the values used for cosmetic reasons, but it can also be useful when Cover is unable to identify values to cover all cases. For example the following method is annotated with a genuine examples characters that make up a Unicode surrogate pair that can be used to achieve a positive test:

@Nullable
public static Integer toNullableCodePoint(
        @InTestsUseCharacters('\uD801') char high,
        @InTestsUseCharacters('\uDC37') char low) {
    if (Character.isSurrogatePair(high, low)) {
        return Character.toCodePoint(high, low);
    }
    return null;
}

Using @InTestsUseFactories

The @InTestsUseFactories annotation allows you to recommend specific factory methods to use in tests. Cover will try to find factory methods, but sometimes needs help. For example, the following class contains a factory for creating sports car instances.

package com.example;

public class Factory {
    public static Car sportsCarFactory() {
        return new SportsCar();
    }
}

The following method is annotated to use the sports car factory method:

public class Dealership {
    @InTestsUseFactories(className="com.example.Factory", methodNames={"sportsCarFactory"})
    public void order(Car car){
        // do whatever with the car
    }
}