Merge pull request #50 from diffblue/afry/tg-24054-WriteTestsToAnnotation

add @WriteTestsTo annotation

Author: aidenblue

README.md

@@ -12,71 +12,79 @@ 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>
     <dependency>
         <groupId>com.diffblue.cover</groupId>
         <artifactId>cover-annotations</artifactId>
-        <version>1.8.0</version>
+        <version>1.9.0</version>
         <scope>provided</scope>
     </dependency>
 </dependencies>
 ```
 
 ### 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 {
-    compileOnly("com.diffblue.cover:cover-annotations:1.8.0")
+    compileOnly("com.diffblue.cover:cover-annotations:1.9.0")
 
-    testImplementation("com.diffblue.cover:cover-annotations:1.8.0")    
+    testImplementation("com.diffblue.cover:cover-annotations:1.9.0")    
 }
 ```
 
 ## 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());
+    }
 }
 ```
 
@@ -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");
+    }
 }
 ```
 
@@ -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) {
@@ -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
@@ -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) {
@@ -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,
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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;
     }
 }
@@ -326,7 +353,7 @@ public class CarFactory {
     public static Car getFirstCar() {
         return INSTANCE.cars.get(0);
     }
-    
+
     // and so on...
 }
 ```
@@ -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

pom.xml

@@ -1,6 +1,6 @@
 <?xml version="1.0" encoding="UTF-8"?>
 <!--
-  ~ Copyright 2024 Diffblue Limited.
+  ~ Copyright 2024 - 2026 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
@@ -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>