0
# Test Selection
1

2
Comprehensive test selection capabilities supporting classes, packages, methods, files, resources, directories, modules, and URIs with flexible selector syntax.
3

4
## Capabilities
5

6
### @Select Annotation (Experimental)
7

8
General-purpose selector using prefixed selector identifiers for flexible test selection.
9

10
```java { .api }
11
/**
12
 * Specifies which tests to select based on prefixed selector identifiers.
13
 * Repeatable annotation supporting various selector formats.
14
 */
15
@Retention(RetentionPolicy.RUNTIME)
16
@Target(ElementType.TYPE)
17
@Inherited
18
@Documented
19
@API(status = EXPERIMENTAL, since = "1.11")
20
@Repeatable(Selects.class)
21
public @interface Select {
22
    /**
23
     * One or more prefixed selector identifiers to select.
24
     * @return array of selector identifiers
25
     */
26
    String[] value();
27
}
28

29
@Retention(RetentionPolicy.RUNTIME)
30
@Target(ElementType.TYPE)
31
@Inherited
32
@Documented
33
@API(status = EXPERIMENTAL, since = "1.11")
34
public @interface Selects {
35
    Select[] value();
36
}
37
```
38

39
**Usage Examples:**
40

41
```java
42
@Suite
43
@Select("class:com.example.UserTest")
44
@Select("method:com.example.UserTest#testValidUser")
45
@Select("package:com.example.integration")
46
public class FlexibleTestSuite {
47
}
48

49
// Multiple selectors in one annotation
50
@Suite
51
@Select({
52
    "class:com.example.UserTest",
53
    "class:com.example.ProductTest",
54
    "method:com.example.OrderTest#testCreateOrder"
55
})
56
public class MultiSelectSuite {
57
}
58
```
59

60
### @SelectClasses Annotation
61

62
Specifies the classes to select when running a test suite.
63

64
```java { .api }
65
/**
66
 * Specifies the classes to select when running a test suite.
67
 * Can use Class objects or fully qualified class names.
68
 */
69
@Retention(RetentionPolicy.RUNTIME)
70
@Target(ElementType.TYPE)
71
@Inherited
72
@Documented
73
@API(status = MAINTAINED, since = "1.0")
74
public @interface SelectClasses {
75
    /**
76
     * One or more classes to select.
77
     * @return array of Class objects to select
78
     */
79
    Class<?>[] value() default {};
80
    
81
    /**
82
     * One or more classes by fully qualified names.
83
     * @return array of fully qualified class names
84
     * @since 1.10
85
     */
86
    @API(status = EXPERIMENTAL, since = "1.10")
87
    String[] names() default {};
88
}
89
```
90

91
**Usage Examples:**
92

93
```java
94
// Using Class objects
95
@Suite
96
@SelectClasses({UserTest.class, ProductTest.class, OrderTest.class})
97
public class CoreTestSuite {
98
}
99

100
// Using class names (useful for conditional compilation)
101
@Suite
102
@SelectClasses(names = {
103
    "com.example.UserTest",
104
    "com.example.ProductTest",
105
    "com.example.integration.DatabaseTest"
106
})
107
public class NameBasedTestSuite {
108
}
109

110
// Combining both approaches
111
@Suite
112
@SelectClasses(
113
    value = {UserTest.class, ProductTest.class},
114
    names = {"com.example.integration.ExternalApiTest"}
115
)
116
public class HybridTestSuite {
117
}
118
```
119

120
### @SelectPackages Annotation
121

122
Specifies package names to select for test suite execution.
123

124
```java { .api }
125
/**
126
 * Specifies the names of packages to select when running a test suite.
127
 * All test classes in specified packages will be selected.
128
 */
129
@Retention(RetentionPolicy.RUNTIME)
130
@Target(ElementType.TYPE)
131
@Inherited
132
@Documented
133
@API(status = MAINTAINED, since = "1.0")
134
public @interface SelectPackages {
135
    /**
136
     * One or more fully qualified package names to select.
137
     * @return array of package names
138
     */
139
    String[] value();
140
}
141
```
142

143
**Usage Examples:**
144

145
```java
146
// Single package
147
@Suite
148
@SelectPackages("com.example.unit")
149
public class UnitTestSuite {
150
}
151

152
// Multiple packages
153
@Suite
154
@SelectPackages({
155
    "com.example.unit",
156
    "com.example.integration", 
157
    "com.example.performance"
158
})
159
public class ComprehensiveTestSuite {
160
}
161
```
162

163
### @SelectModules Annotation
164

165
Specifies modules to select for test suite execution (Java 9+ module system).
166

167
```java { .api }
168
/**
169
 * Specifies the modules to select when running a test suite.
170
 * Useful for modular Java applications.
171
 */
172
@Retention(RetentionPolicy.RUNTIME)
173
@Target(ElementType.TYPE)
174
@Inherited
175
@Documented
176
@API(status = STABLE, since = "1.10")
177
public @interface SelectModules {
178
    /**
179
     * One or more modules to select.
180
     * @return array of module names
181
     */
182
    String[] value();
183
}
184
```
185

186
**Usage Examples:**
187

188
```java
189
@Suite
190
@SelectModules({"com.example.core", "com.example.api"})
191
public class ModularTestSuite {
192
}
193
```
194

195
### Method Selection Annotations
196

197
Precise method-level test selection with flexible parameter specification.
198

199
```java { .api }
200
/**
201
 * Specifies a method to select when running a test suite.
202
 * Supports various method specification formats.
203
 */
204
@Retention(RetentionPolicy.RUNTIME)
205
@Target(ElementType.TYPE) 
206
@Inherited
207
@Documented
208
@API(status = EXPERIMENTAL, since = "1.10")
209
@Repeatable(SelectMethods.class)
210
public @interface SelectMethod {
211
    /**
212
     * Fully qualified method name (cannot be combined with other attributes).
213
     * Format: "com.example.MyClass#methodName"
214
     * @return fully qualified method name
215
     */
216
    String value() default "";
217
    
218
    /**
219
     * Class in which method is declared (cannot use with typeName()).
220
     * @return class containing the method
221
     */
222
    Class<?> type() default Class.class;
223
    
224
    /**
225
     * Fully qualified class name (cannot use with type()).
226
     * @return fully qualified class name
227
     */
228
    String typeName() default "";
229
    
230
    /**
231
     * Method name (never blank unless value() is used).
232
     * @return method name
233
     */
234
    String name() default "";
235
    
236
    /**
237
     * Parameter types (cannot use with parameterTypeNames()).
238
     * @return array of parameter types
239
     */
240
    Class<?>[] parameterTypes() default {};
241
    
242
    /**
243
     * Parameter types as string (cannot use with parameterTypes()).
244
     * Format: "java.lang.String, int, boolean"
245
     * @return comma-separated parameter type names
246
     */
247
    String parameterTypeNames() default "";
248
}
249

250
@Retention(RetentionPolicy.RUNTIME)
251
@Target(ElementType.TYPE)
252
@Inherited
253
@Documented
254
@API(status = EXPERIMENTAL, since = "1.10")
255
public @interface SelectMethods {
256
    SelectMethod[] value();
257
}
258
```
259

260
**Usage Examples:**
261

262
```java
263
// Using fully qualified method name
264
@Suite
265
@SelectMethod("com.example.UserTest#testValidUser")
266
@SelectMethod("com.example.UserTest#testInvalidUser")
267
public class UserTestMethodSuite {
268
}
269

270
// Using type and method name
271
@Suite
272
@SelectMethod(type = UserTest.class, name = "testValidUser")
273
@SelectMethod(type = ProductTest.class, name = "testProductCreation")
274
public class SpecificMethodSuite {
275
}
276

277
// With parameter types
278
@Suite
279
@SelectMethod(
280
    type = UserTest.class,
281
    name = "testUserWithAge", 
282
    parameterTypes = {String.class, int.class}
283
)
284
public class ParameterizedMethodSuite {
285
}
286

287
// Using type name and parameter type names
288
@Suite
289
@SelectMethod(
290
    typeName = "com.example.UserTest",
291
    name = "testComplexMethod",
292
    parameterTypeNames = "java.lang.String, int, boolean"
293
)
294
public class ComplexMethodSuite {
295
}
296
```
297

298
### File and Resource Selection
299

300
Select tests from specific files, directories, classpath resources, and URIs.
301

302
```java { .api }
303
/**
304
 * Specifies a file to select when running a test suite.
305
 * Supports line and column specification for precise selection.
306
 */
307
@Retention(RetentionPolicy.RUNTIME)
308
@Target(ElementType.TYPE)
309
@Inherited
310
@Documented
311
@API(status = STABLE, since = "1.10")
312
@Repeatable(SelectFiles.class)
313
public @interface SelectFile {
314
    /**
315
     * The file to select.
316
     * @return file path
317
     */
318
    String value();
319
    
320
    /**
321
     * Line number within the file (ignored if ≤ 0).
322
     * @return line number
323
     */
324
    int line() default 0;
325
    
326
    /**
327
     * Column number within the file (ignored if line ignored or ≤ 0).
328
     * @return column number
329
     */
330
    int column() default 0;
331
}
332

333
/**
334
 * Specifies directories to select when running a test suite.
335
 */
336
@API(status = STABLE, since = "1.10")
337
public @interface SelectDirectories {
338
    String[] value();
339
}
340

341
/**
342
 * Specifies URIs to select when running a test suite.
343
 */
344
@API(status = STABLE, since = "1.10")
345
public @interface SelectUris {
346
    String[] value();
347
}
348

349
/**
350
 * Specifies a classpath resource to select when running a test suite.
351
 */
352
@Retention(RetentionPolicy.RUNTIME)
353
@Target(ElementType.TYPE)
354
@Inherited
355
@Documented
356
@API(status = STABLE, since = "1.10")
357
@Repeatable(SelectClasspathResources.class)
358
public @interface SelectClasspathResource {
359
    /**
360
     * The name of the classpath resource to select.
361
     * @return classpath resource name
362
     */
363
    String value();
364
    
365
    /**
366
     * Line number within the resource (ignored if ≤ 0).
367
     * @return line number
368
     */
369
    int line() default 0;
370
    
371
    /**
372
     * Column number within the resource (ignored if line ignored or ≤ 0).
373
     * @return column number
374
     */
375
    int column() default 0;
376
}
377
```
378

379
**Usage Examples:**
380

381
```java
382
// File selection
383
@Suite
384
@SelectFile("/path/to/TestFile.java")
385
@SelectFile(value = "/path/to/SpecificTest.java", line = 25)
386
public class FileBasedTestSuite {
387
}
388

389
// Directory selection
390
@Suite
391
@SelectDirectories({"/src/test/java/unit", "/src/test/java/integration"})
392
public class DirectoryTestSuite {
393
}
394

395
// Classpath resource selection
396
@Suite
397
@SelectClasspathResource("test-config/integration-tests.properties") 
398
@SelectClasspathResource(value = "test-data/user-scenarios.json", line = 10)
399
public class ResourceBasedTestSuite {
400
}
401

402
// URI selection
403
@Suite
404
@SelectUris({
405
    "file:///absolute/path/to/test",
406
    "classpath:/com/example/tests",
407
    "jar:file:/path/to/tests.jar!/com/example"
408
})
409
public class UriTestSuite {
410
}
411
```
412

413
## Selection Best Practices
414

415
### Combining Selectors
416

417
Multiple selection annotations can be combined to create complex test suites:
418

419
```java
420
@Suite
421
@SelectPackages("com.example.core")
422
@SelectClasses({SpecialIntegrationTest.class})
423
@SelectMethod(type = PerformanceTest.class, name = "criticalPerformanceTest")
424
public class ComprehensiveTestSuite {
425
}
426
```
427

428
### Performance Considerations
429

430
- Use `@SelectClasses` for precise control and fastest execution
431
- Use `@SelectPackages` for broad coverage with moderate performance
432
- Use `@SelectMethod` sparingly for very specific test selection
433
- Combine with filtering annotations to refine selection efficiently
434

435
### Maintenance Tips
436

437
- Use `names` attribute in `@SelectClasses` for conditional compilation scenarios
438
- Group related test selections into logical suites
439
- Consider using `@Select` for maximum flexibility in complex scenarios
440
- Document selection criteria in suite class javadoc for maintenance clarity