Skip to content

Commit fe4974d

Browse files
roxspringroxspring
authored
Merge pull request #1 from diffblue/roxspring/TG-21323-move-latest-annotations
[TG-21323] Move latest annotations
2 parents d5f2ad7 + 07614ad commit fe4974d

17 files changed

+846
-95
lines changed

‎README.md

Lines changed: 159 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -43,11 +43,11 @@ Annotations placed on packages affect tests for all classes and methods under te
4343
Annotations placed on classes affect tests for that class and all it's methods under test, overriding package level annotations.
4444
Annotations placed on methods affect just that method under test, overriding package and class level annotations.
4545

46-
| Annotation | Equivalent `dcover create` option |
47-
|:----------------------------|:--------------------------------------------------|
48-
| `@InTestsMock` | `--mock`, `--disable-mock-inputs` |
49-
| `@InTestsMockConstruction` | `--mock-construction` |
50-
| `@InTestsMockStatic` | `--mock-static` |
46+
| Annotation | Equivalent `dcover create` option |
47+
|:---------------------------|:----------------------------------|
48+
| `@InTestsMock` | `--mock`, `--disable-mock-inputs` |
49+
| `@InTestsMockConstruction` | `--mock-construction` |
50+
| `@InTestsMockStatic` | `--mock-static` |
5151

5252
The annotations will be respected by Diffblue Cover via both command line and IntelliJ Plugin.
5353
When used from the command line in conjunction with equivalent options then the command line options take priority over the annotations found.
@@ -104,3 +104,157 @@ public class ClassUnderTest {
104104
}
105105
}
106106
```
107+
108+
### Using `@InTestsUseClasses`
109+
110+
The `@InTestsUseClasses` annotation allows the user to recommend specific `Class` literal values to use in tests.
111+
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.
112+
For example the following method is annotated with an example class literal to achieve a positive test:
113+
114+
```java
115+
public static boolean isAnnotation(@InTestsUseClasses(Nullable.class) Class<?> theClass) {
116+
return theClass.isAnnotation();
117+
}
118+
```
119+
120+
### Using `@InTestsUseStrings`
121+
122+
The `@InTestsUseStrings` annotation allows the user to recommend specific `String` values to use in tests.
123+
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.
124+
For example the following method is annotated with some genuine examples of song titles that can be used to achieve coverage:
125+
126+
```java
127+
public static boolean isDayRelatedSongTitle(@InTestsUseStrings({"I Don't Like Mondays", "Here Comes The Weekend"}) String title) {
128+
return Stream.of(DayOfWeek.values())
129+
.map(DayOfWeek::name)
130+
.map(String::toLowerCase)
131+
.anyMatch(title.toLowerCase()::contains);
132+
}
133+
```
134+
135+
### Using `@InTestsUseCharacters`
136+
137+
The `@InTestsUseCharacters` annotation allows the user to recommend specific `char` values to use in tests.
138+
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.
139+
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:
140+
141+
```java
142+
@Nullable
143+
public static Integer toNullableCodePoint(
144+
@InTestsUseCharacters('\uD801') char high,
145+
@InTestsUseCharacters('\uDC37') char low) {
146+
if (Character.isSurrogatePair(high, low)) {
147+
return Character.toCodePoint(high, low);
148+
}
149+
return null;
150+
}
151+
```
152+
153+
### Using `@InTestsUseBytes`
154+
155+
The `@InTestsUseBytes` annotation allows the user to recommend specific `byte` values to use in tests.
156+
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.
157+
For example the following method is annotated to use a specific preferred value:
158+
159+
```java
160+
public static String toUpperHexString(@InTestsUseBytes((byte)0xD1) byte input) {
161+
return Long.toHexString(input).toUpperCase();
162+
}
163+
```
164+
165+
### Using `@InTestsUseShorts`
166+
167+
The `@InTestsUseShorts` annotation allows the user to recommend specific `short` values to use in tests.
168+
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.
169+
For example the following method is annotated to use a specific preferred value:
170+
171+
```java
172+
public static String toUpperHexString(@InTestsUseShorts((short)0xD1FF) short input) {
173+
return Long.toHexString(input).toUpperCase();
174+
}
175+
```
176+
177+
### Using `@InTestsUseIntegers`
178+
179+
The `@InTestsUseIntegers` annotation allows the user to recommend specific `int` values to use in tests.
180+
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.
181+
For example the following method is annotated to use a specific preferred value:
182+
183+
```java
184+
public static String toUpperHexString(@InTestsUseIntegers(0xD1FFB) int input) {
185+
return Long.toHexString(input).toUpperCase();
186+
}
187+
```
188+
189+
### Using `@InTestsUseLongs`
190+
191+
The `@InTestsUseLongs` annotation allows the user to recommend specific `long` values to use in tests.
192+
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.
193+
For example the following method is annotated to use a specific preferred value:
194+
195+
```java
196+
public static String toUpperHexString(@InTestsUseLongs(0xD1FFBL) long input) {
197+
return Long.toHexString(input).toUpperCase();
198+
}
199+
```
200+
201+
### Using `@InTestsUseFloats`
202+
203+
The `@InTestsUseFloats` annotation allows the user to recommend specific `float` values to use in tests.
204+
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.
205+
For example the following method is annotated to use a specific preferred value:
206+
207+
```java
208+
public static boolean isNearPi(@InTestsUseFloats(3.14159f) float input) {
209+
return Float.toString(input).startsWith("3.14");
210+
}
211+
```
212+
213+
### Using `@InTestsUseDoubles`
214+
215+
The `@InTestsUseDoubles` annotation allows the user to recommend specific `double` values to use in tests.
216+
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.
217+
For example the following method is annotated to use a specific preferred value:
218+
219+
```java
220+
public static boolean isNearPi(@InTestsUseDoubles(Math.PI) float input) {
221+
return Double.toString(input).startsWith("3.14");
222+
}
223+
```
224+
225+
### Using `@InterestingTestFactory`
226+
227+
Indicates the annotated method as a useful factory method for use in tests.
228+
Cover will automatically recognise factory methods that simply return a newly created instance, but may not identify more complicated factories.
229+
This annotation allows such factory methods to be manually annotated so that Cover considers them for producing inputs.
230+
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.
231+
By annotating the `ofStaff(String)` with `@InterstingTestFactory` we can tell Cover that this should be considered a good factory method to use in tests.
232+
233+
```java
234+
public String getUserDisplayString(User user) {
235+
if (user.manager) {
236+
return user.username + " (manager)";
237+
}
238+
else {
239+
return user.username;
240+
}
241+
}
242+
243+
class User {
244+
private static Map<String, User> staff = new HashMap<String, User>();
245+
246+
@InterestingTestFactory
247+
public static User ofStaff(String name) {
248+
return staff.computeIfAbsent(name, ignored -> new User(name, false));
249+
}
250+
251+
public final String username;
252+
public final boolean manager;
253+
254+
private User(String username, boolean manager) {
255+
this.username = username;
256+
this.manager = manager;
257+
}
258+
}
259+
```
260+

0 commit comments

Comments
 (0)