From a1bdf3e8eaac64976a54a14aae347c86eaca9915 Mon Sep 17 00:00:00 2001 From: Paul Crane Date: Thu, 9 Oct 2025 12:10:36 +0100 Subject: [PATCH 1/4] Add missing README.md guidance for new annotation --- README.md | 42 ++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 42 insertions(+) diff --git a/README.md b/README.md index 012a678..a32c572 100644 --- a/README.md +++ b/README.md @@ -301,3 +301,45 @@ class User { } ``` +#### Using `@InTestsUseFactories` + +The `@InTestsUseFactories` annotation allows the user to recommend specific factories to use in tests. +This can be useful if Cover is not using the correct factory methods to construct objects. + +Consider the following example. In the test sources, create a class `Factory` that is responsible for constructing +`Car` objects from some external resource (such as a JSON file, or the like). If we annotate the `CarPainter`'s +`changeColor` method with `@InTestsUseFactories` pointing to the `Factory`'s `getFirstCar` method, Cover will attempt +to use that to create instances of `Car` objects for testing. + +You are able to specify multiple method names in the annotation, as well as specifying it multiple times (you could +specify a `ColorFactory` for instance). + +```java +public class CarFactory { + private static final CarFactory INSTANCE = new CarFactory(); + private final List cars; + + private CarFactory() { + // initialize the list of cars from some resource + } + + public static Car getFirstCar() { + return INSTANCE.cars.get(0); + } + + // and so on... +} +``` + +```java +import com.diffblue.cover.annotations.InTestsUseFactories; + +public class CarPainter { + @InTestsUseFactories(className = "CarFactory", methodNames = {"getFirstCar"}) + public static Car changeColor(Car car, Color color) { + car.setColor(color); + return car; + } +} +``` + From 14170a362a561af9c77201fe783a1a952d1280d7 Mon Sep 17 00:00:00 2001 From: Paul Crane Date: Thu, 9 Oct 2025 12:51:51 +0100 Subject: [PATCH 2/4] Add new experimental annotation This will allow Cover to interrogate LLMs on the annotated elements. The exact behaviour is to be determined (hence putting it in an `experimental` package). --- .../experimental/InTestsUseLLM.java | 40 +++++++++++++++++++ 1 file changed, 40 insertions(+) create mode 100644 src/main/java/com/diffblue/cover/annotations/experimental/InTestsUseLLM.java diff --git a/src/main/java/com/diffblue/cover/annotations/experimental/InTestsUseLLM.java b/src/main/java/com/diffblue/cover/annotations/experimental/InTestsUseLLM.java new file mode 100644 index 0000000..c9ce816 --- /dev/null +++ b/src/main/java/com/diffblue/cover/annotations/experimental/InTestsUseLLM.java @@ -0,0 +1,40 @@ +/* + * 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.experimental; + +import static java.lang.annotation.ElementType.METHOD; +import static java.lang.annotation.ElementType.PACKAGE; +import static java.lang.annotation.ElementType.PARAMETER; +import static java.lang.annotation.ElementType.TYPE; +import static java.lang.annotation.RetentionPolicy.RUNTIME; + +import java.lang.annotation.Retention; +import java.lang.annotation.Target; + +/** + * Indicates the annotated element can request assistance from LLMs. + * + *

The specific assistance will depend on: the element, what features Diffblue Cover has + * implemented, and any number of other things. + * + *

Note: this annotation may change in the future without further warning. + * + * @deprecated This annotation is experimental and may change or be removed in future releases. Its + * use is discouraged except for internal experimental purposes. + */ +@Retention(RUNTIME) +@Target({PACKAGE, TYPE, METHOD, PARAMETER}) +@Deprecated +public @interface InTestsUseLLM {} From 425266f14744d07a5fc982e3b0e4116c7b80f74b Mon Sep 17 00:00:00 2001 From: Paul Crane Date: Thu, 9 Oct 2025 12:55:49 +0100 Subject: [PATCH 3/4] Add readme for the experimental annotations --- README.md | 14 ++++++++++++++ 1 file changed, 14 insertions(+) diff --git a/README.md b/README.md index a32c572..032bc8f 100644 --- a/README.md +++ b/README.md @@ -343,3 +343,17 @@ public class CarPainter { } ``` +### Experimental Annotations + +Experimental annotations should not be used in a production setting, but are +included to allow Diffblue to perform experiments with new features. + +> [!NOTE] +> The annotations in the `experimental` package can change at any time. +> +> Do not rely on them in production code! + +#### Using `@InTestsUseLLM` + +Indicates that LLMs can be used in this context. + From 502f72783033892d93aeed623f8ea56b2ee3fd59 Mon Sep 17 00:00:00 2001 From: Paul Crane Date: Thu, 9 Oct 2025 12:56:26 +0100 Subject: [PATCH 4/4] Bump the version --- README.md | 6 +++--- pom.xml | 2 +- 2 files changed, 4 insertions(+), 4 deletions(-) diff --git a/README.md b/README.md index 032bc8f..c4072f5 100644 --- a/README.md +++ b/README.md @@ -24,7 +24,7 @@ For installation into a Maven project the `provided` scope is recommended so tha com.diffblue.cover cover-annotations - 1.7.0 + 1.8.0 provided @@ -36,9 +36,9 @@ For installation into a Gradle project the `compileOnly` and `testImplementation ``` dependencies { - compileOnly("com.diffblue.cover:cover-annotations:1.7.0") + compileOnly("com.diffblue.cover:cover-annotations:1.8.0") - testImplementation("com.diffblue.cover:cover-annotations:1.7.0") + testImplementation("com.diffblue.cover:cover-annotations:1.8.0") } ``` diff --git a/pom.xml b/pom.xml index 0347d9e..2df075f 100644 --- a/pom.xml +++ b/pom.xml @@ -16,7 +16,7 @@ 4.0.0 com.diffblue.cover cover-annotations - 1.7.0 + 1.8.0 jar Cover Annotations