Merge pull request #47 from diffblue/release/1.8.0

Release 1.8.0

Author: pcrane

README.md

@@ -24,7 +24,7 @@ For installation into a Maven project the `provided` scope is recommended so tha
     <dependency>
         <groupId>com.diffblue.cover</groupId>
         <artifactId>cover-annotations</artifactId>
-        <version>1.7.0</version>
+        <version>1.8.0</version>
         <scope>provided</scope>
     </dependency>
 </dependencies>
@@ -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")    
 }
 ```
 
@@ -301,3 +301,59 @@ 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<Car> 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;
+    }
+}
+```
+
+### 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.
+

pom.xml

@@ -16,7 +16,7 @@
   <modelVersion>4.0.0</modelVersion>
   <groupId>com.diffblue.cover</groupId>
   <artifactId>cover-annotations</artifactId>
-  <version>1.7.0</version>
+  <version>1.8.0</version>
   <packaging>jar</packaging>
 
   <name>Cover Annotations</name>

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.
+ *
+ * <p>The specific assistance will depend on: the element, what features Diffblue Cover has
+ * implemented, and any number of other things.
+ *
+ * <p><em>Note:</em> 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 {}