Skip to content

Afry/tg 24054 write tests to annotation #50

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
aidenblue wants to merge 2 commits into
base: develop
Choose a base branch
from
Open

Afry/tg 24054 write tests to annotation #50

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
cd814f2
Add new WriteTestsTo annotation
aidenblue Dec 5, 2025
d942c72
Up version the annotation library
aidenblue Dec 5, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
152 changes: 103 additions & 49 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -12,12 +12,15 @@ In turn this can be used by [Diffblue Cover](https://diffblue.com/cover) to tune

## Installation

Cover Annotations is published in the [Maven central repository](https://central.sonatype.com/artifact/com.diffblue.cover/cover-annotations/overview).
In order to use the annotations simply add `cover-annotations` as a dependency to your project, for example copying the snippet for Maven or Gradle from the repository page.
Cover Annotations is published in
the [Maven central repository](https://central.sonatype.com/artifact/com.diffblue.cover/cover-annotations/overview).
In order to use the annotations simply add `cover-annotations` as a dependency to your project, for example copying the
snippet for Maven or Gradle from the repository page.

### Maven

For installation into a Maven project the `provided` scope is recommended so that the annotations are available at compile and test time, but are not bundled with the project output:
For installation into a Maven project the `provided` scope is recommended so that the annotations are available at
compile and test time, but are not bundled with the project output:

```
<dependencies>
Expand All @@ -32,7 +35,8 @@ For installation into a Maven project the `provided` scope is recommended so tha

### Gradle

For installation into a Gradle project the `compileOnly` and `testImplementation` configurations are recommended so that the annotations are available at compile and test time, but are not bundled with the project output:
For installation into a Gradle project the `compileOnly` and `testImplementation` configurations are recommended so that
the annotations are available at compile and test time, but are not bundled with the project output:

```
dependencies {
Expand All @@ -45,38 +49,42 @@ dependencies {
## Usage

Annotations placed on packages affect tests for all classes and methods under test in that package.
Annotations placed on classes affect tests for that class and all its methods under test, overriding package level annotations.
Annotations placed on classes affect tests for that class and all its methods under test, overriding package level
annotations.
Annotations placed on methods affect just that method under test, overriding package and class level annotations.

The annotations will be respected by Diffblue Cover via both command line and IntelliJ Plugin.
When used from the command line in conjunction with equivalent options then the command line options take priority over the annotations found.
When used from the command line in conjunction with equivalent options then the command line options take priority over
the annotations found.

### 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(..)`.
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`:

```java
public class ClassUnderTest {
@InTestsMock(Number.class)
public static String methodUnderTest(Number number) {
return String.valueOf(number.intValue());
}
@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:
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:

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

Expand All @@ -89,36 +97,39 @@ public class ClassUnderTest {

#### 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)`.
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`:

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

> [!NOTE]
> Note that using `@InTestsMockConstruction` has the same effect as, and can be overridden by, Cover CLI command line option:
> 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)`.
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`:

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

Expand All @@ -136,7 +147,8 @@ Custom input annotations allow particular inputs to be recommended to Diffblue C
#### Using `@InTestsUseEnums`

The `@InTestsUseEnums` annotation allows the user to recommend specific `enum` 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.
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.

```java
public static boolean isDateOrTimeBased(@InTestsUseEnums({"SECONDS", "YEARS", "FOREVER"}) ChronoUnit chronoUnit) {
Expand All @@ -147,7 +159,8 @@ public static boolean isDateOrTimeBased(@InTestsUseEnums({"SECONDS", "YEARS", "F
#### Using `@InTestsUseClasses`

The `@InTestsUseClasses` annotation allows the user 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.
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
Expand All @@ -159,8 +172,10 @@ public static boolean isAnnotation(@InTestsUseClasses(Nullable.class) Class<?> t
#### Using `@InTestsUseStrings`

The `@InTestsUseStrings` annotation allows the user 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:
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) {
Expand All @@ -174,10 +189,13 @@ public static boolean isDayRelatedSongTitle(@InTestsUseStrings({"I Don't Like Mo
#### Using `@InTestsUseCharacters`

The `@InTestsUseCharacters` annotation allows the user 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:
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,
Expand All @@ -192,31 +210,34 @@ public static Integer toNullableCodePoint(
#### Using `@InTestsUseBytes`

The `@InTestsUseBytes` annotation allows the user 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.
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) {
public static String toUpperHexString(@InTestsUseBytes((byte) 0xD1) byte input) {
return Long.toHexString(input).toUpperCase();
}
```

#### Using `@InTestsUseShorts`

The `@InTestsUseShorts` annotation allows the user 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.
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) {
public static String toUpperHexString(@InTestsUseShorts((short) 0xD1FF) short input) {
return Long.toHexString(input).toUpperCase();
}
```

#### Using `@InTestsUseIntegers`

The `@InTestsUseIntegers` annotation allows the user 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.
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
Expand All @@ -228,7 +249,8 @@ public static String toUpperHexString(@InTestsUseIntegers(0xD1FFB) int input) {
#### Using `@InTestsUseLongs`

The `@InTestsUseLongs` annotation allows the user 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.
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
Expand All @@ -240,7 +262,8 @@ public static String toUpperHexString(@InTestsUseLongs(0xD1FFBL) long input) {
#### Using `@InTestsUseFloats`

The `@InTestsUseFloats` annotation allows the user 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.
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
Expand All @@ -252,7 +275,8 @@ public static boolean isNearPi(@InTestsUseFloats(3.14159f) float input) {
#### Using `@InTestsUseDoubles`

The `@InTestsUseDoubles` annotation allows the user 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.
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
Expand All @@ -263,22 +287,25 @@ public static boolean isNearPi(@InTestsUseDoubles(Math.PI) float input) {

### Interesting Value Annotations

Interesting value annotations allow users to promote existing fields and methods to be identified and used in particular roles by Diffblue Cover when writing tests.
Interesting value annotations allow users to promote existing fields and methods to be identified and used in particular
roles by Diffblue Cover when writing tests.

#### Using `@InterestingTestFactory`

Indicates the annotated method as a useful factory method for use in tests.
Cover will automatically recognise factory methods that simply return a newly created instance, but may not identify more complicated factories.
Cover will automatically recognise factory methods that simply return a newly created instance, but may not identify
more complicated factories.
This annotation allows such factory methods to be manually annotated so that Cover considers them for producing inputs.
For example the following method under test takes a `User` as input, but the `User` constructor is private and Cover doesn't naturally consider `ofStaff(String)` to be a safe factory method to call.
By annotating the `ofStaff(String)` with `@InterstingTestFactory` we can tell Cover that this should be considered a good factory method to use in tests.
For example the following method under test takes a `User` as input, but the `User` constructor is private and Cover
doesn't naturally consider `ofStaff(String)` to be a safe factory method to call.
By annotating the `ofStaff(String)` with `@InterstingTestFactory` we can tell Cover that this should be considered a
good factory method to use in tests.

```java
public String getUserDisplayString(User user) {
if (user.manager) {
return user.username + " (manager)";
}
else {
} else {
return user.username;
}
}
Expand Down Expand Up @@ -326,7 +353,7 @@ public class CarFactory {
public static Car getFirstCar() {
return INSTANCE.cars.get(0);
}

// and so on...
}
```
Expand All @@ -343,6 +370,33 @@ public class CarPainter {
}
```

### Test Organization Annotations

Test organization annotations allow users to control how tests are organized and structured.

#### Using `@WriteTestsTo`

The `@WriteTestsTo` annotation directs Diffblue Cover to write tests for a specific source class into a designated test
class file, rather than following the default naming template (configured via `--class-name-template`).

The specified test class name must be alphanumeric, and the test class will be created in the test folder under the same
package structure as the source class.

```java
package com.example.myapp;

@WriteTestsTo("CustomTestClassName")
public class SourceClass {
public String getValue() {
return "example";
}
}
// Tests will be written to: src/test/java/com/example/myapp/CustomTestClassName.java
```

> [!NOTE]
> This annotation can only be applied at the class level.

### Experimental Annotations

Experimental annotations should not be used in a production setting, but are
Expand Down
2 changes: 1 addition & 1 deletion pom.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -16,7 +16,7 @@
<modelVersion>4.0.0</modelVersion>
<groupId>com.diffblue.cover</groupId>
<artifactId>cover-annotations</artifactId>
<version>1.8.0</version>
<version>1.9.0</version>
<packaging>jar</packaging>

<name>Cover Annotations</name>
Expand Down
57 changes: 57 additions & 0 deletions src/main/java/com/diffblue/cover/annotations/WriteTestsTo.java
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,57 @@
/*
* Copyright 2025 Diffblue Limited.
*
* Licensed under the Apache License, Version 2.0 (the "License").
* You may not use this file except in compliance with the License.
* A copy of the License is located at
*
* https://www.apache.org/licenses/LICENSE-2.0
*
* or in the "license" file accompanying this file. This file is distributed
* on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either
* express or implied. See the License for the specific language governing
* permissions and limitations under the License.
*/
package com.diffblue.cover.annotations;

import static java.lang.annotation.ElementType.TYPE;
import static java.lang.annotation.RetentionPolicy.RUNTIME;

import java.lang.annotation.Retention;
import java.lang.annotation.Target;

/**
* Directs Diffblue Cover to write tests for the annotated source class into the specified test
* class file. This annotation allows users to explicitly specify the target test class when it
* should not match the configured or default --class-name-template.
*
* <p>This annotation can only be applied at the class level.
*
* <p>The specified test class name must be alphanumeric. The resulting test class will be created
* in the test folder, under the same package structure as the source class.
*
* <p>Example usage:
*
* <pre>{@code
* package com.example.myapp;
*
* @WriteTestsTo("CustomTestClassName")
* public class SourceClass {
* // class implementation
* }
* // Tests will be written to: src/test/java/com/example/myapp/CustomTestClassName.java
* }</pre>
*
* @since Diffblue Cover 1.9.0
*/
@Retention(RUNTIME)
@Target(TYPE)
public @interface WriteTestsTo {

/**
* @return the alphanumeric name of the test class file where tests for the annotated source class
* should be written. The resulting test class will be placed in the test folder under the
* same package structure as the source class.
*/
String value();
}
Loading