# Custom Input Annotations

## 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:

```java
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:

```java
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:

```java
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:

```java
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:

```java
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:

```java
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:

```java
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:

```java
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:

```java
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:

```java
@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.

```java
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:

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


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://cover-docs-preview.diffblue.com/features/cover-annotations/custom-input-annotations.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.