0
# Test Selection
1

2
Comprehensive test selection capabilities providing flexible methods to specify which tests to include in a suite through classes, packages, methods, files, directories, URIs, modules, and classpath resources.
3

4
## Capabilities
5

6
### @SelectClasses Annotation
7

8
Specifies classes to select for the test suite, supporting both direct class references and string-based class names.
9

10
```java { .api }
11
/**
12
 * Specifies classes to select for test suite execution.
13
 * Supports both direct class references and fully qualified class names.
14
 * Can combine both approaches in a single annotation.
15
 * 
16
 * @since 1.0
17
 */
18
@Retention(RetentionPolicy.RUNTIME)
19
@Target(ElementType.TYPE)
20
@Inherited
21
@Documented
22
@API(status = MAINTAINED)
23
public @interface SelectClasses {
24
    /**
25
     * One or more classes to select for test execution.
26
     * @return array of classes to select
27
     */
28
    Class<?>[] value() default {};
29
    
30
    /**
31
     * Fully qualified class names to select.
32
     * Useful for private/package-private classes not directly referenceable.
33
     * @return array of fully qualified class names
34
     * @since 1.10
35
     */
36
    @API(status = EXPERIMENTAL, since = "1.10") 
37
    String[] names() default {};
38
}
39
```
40

41
**Usage Examples:**
42

43
```java
44
// Direct class references
45
@Suite
46
@SelectClasses({UserTest.class, ProductTest.class, OrderTest.class})
47
class BusinessSuite {
48
}
49

50
// String-based class names
51
@Suite
52
@SelectClasses(names = {
53
    "com.example.internal.PrivateTest",
54
    "com.example.util.PackagePrivateTest"
55
})
56
class InternalTestSuite {
57
}
58

59
// Combined approach
60
@Suite
61
@SelectClasses(
62
    value = {UserTest.class, ProductTest.class},
63
    names = {"com.example.internal.PrivateUserTest"}
64
)
65
class CombinedClassSuite {
66
}
67
```
68

69
### @SelectPackages Annotation
70

71
Specifies packages to select for test suite execution, enabling package-based test discovery.
72

73
```java { .api }
74
/**
75
 * Specifies packages to select for test suite execution.
76
 * Discovers all classes within specified packages according to 
77
 * configured include/exclude filters.
78
 * 
79
 * @since 1.0
80
 */
81
@Retention(RetentionPolicy.RUNTIME)
82
@Target(ElementType.TYPE)
83
@Inherited
84
@Documented
85
@API(status = MAINTAINED)
86
public @interface SelectPackages {
87
    /**
88
     * One or more fully qualified package names to select.
89
     * @return array of package names to include in test discovery
90
     */
91
    String[] value();
92
}
93
```
94

95
**Usage Examples:**
96

97
```java
98
// Single package selection
99
@Suite
100
@SelectPackages("com.example.integration")
101
class IntegrationSuite {
102
}
103

104
// Multiple package selection
105
@Suite
106
@SelectPackages({
107
    "com.example.unit",
108
    "com.example.integration", 
109
    "com.example.e2e"
110
})
111
class ComprehensiveSuite {
112
}
113

114
// Package selection with filtering
115
@Suite
116
@SelectPackages("com.example")
117
@IncludeClassNamePatterns(".*Test")
118
@ExcludeClassNamePatterns(".*AbstractTest")
119
class FilteredPackageSuite {
120
}
121
```
122

123
### @SelectMethod Annotation
124

125
Specifies individual methods to select for test suite execution with flexible method identification options.
126

127
```java { .api }
128
/**
129
 * Specifies a method to select for test suite execution.
130
 * Supports multiple identification strategies: fully qualified names,
131
 * class/method combinations, and parameter type specifications.
132
 * 
133
 * @since 1.10
134
 */
135
@Retention(RetentionPolicy.RUNTIME)
136
@Target(ElementType.TYPE)
137
@Inherited
138
@Documented
139
@Repeatable(SelectMethods.class)
140
@API(status = EXPERIMENTAL, since = "1.10")
141
public @interface SelectMethod {
142
    /**
143
     * Fully qualified method name in format:
144
     * [fully.qualified.ClassName]#[methodName]
145
     * [fully.qualified.ClassName]#[methodName](parameter type list)
146
     * Cannot be combined with other attributes.
147
     * @return fully qualified method identifier
148
     */
149
    String value() default "";
150
    
151
    /**
152
     * Class containing the method to select.
153
     * Mutually exclusive with typeName().
154
     * @return class containing the target method
155
     */
156
    Class<?> type() default Class.class;
157
    
158
    /**
159
     * Fully qualified class name containing the method.
160
     * Alternative to type() for classes not directly referenceable.
161
     * Mutually exclusive with type().
162
     * @return fully qualified class name
163
     */
164
    String typeName() default "";
165
    
166
    /**
167
     * Name of the method to select.
168
     * Used with type() or typeName().
169
     * @return method name
170
     */
171
    String name() default "";
172
    
173
    /**
174
     * Parameter types for method overload resolution.
175
     * Mutually exclusive with parameterTypeNames().
176
     * @return array of parameter types
177
     */
178
    Class<?>[] parameterTypes() default {};
179
    
180
    /**
181
     * Parameter type names for method overload resolution.
182
     * Alternative to parameterTypes() using string names.
183
     * Mutually exclusive with parameterTypes().
184
     * @return comma-separated parameter type names
185
     */
186
    String parameterTypeNames() default "";
187
}
188

189
/**
190
 * Container annotation for multiple @SelectMethod declarations.
191
 * @since 1.10
192
 */
193
@Retention(RetentionPolicy.RUNTIME)
194
@Target(ElementType.TYPE)
195
@Inherited
196
@Documented
197
@API(status = EXPERIMENTAL, since = "1.10")
198
public @interface SelectMethods {
199
    SelectMethod[] value();
200
}
201
```
202

203
**Usage Examples:**
204

205
```java
206
// Fully qualified method names
207
@Suite
208
@SelectMethod("com.example.UserTest#testCreateUser")
209
@SelectMethod("com.example.UserTest#testUpdateUser(com.example.User)")
210
class UserMethodSuite {
211
}
212

213
// Class and method name combinations
214
@Suite
215
@SelectMethod(type = UserTest.class, name = "testCreateUser")
216
@SelectMethod(type = ProductTest.class, name = "testValidateProduct")
217
class CrossClassMethodSuite {
218
}
219

220
// String-based class names with parameter types
221
@Suite
222
@SelectMethod(
223
    typeName = "com.example.internal.ServiceTest",
224
    name = "testComplexOperation",
225
    parameterTypeNames = "java.lang.String, int, boolean"
226
)
227
class InternalMethodSuite {
228
}
229

230
// Overloaded method selection
231
@Suite
232
@SelectMethod(
233
    type = CalculatorTest.class, 
234
    name = "testAdd",
235
    parameterTypes = {int.class, int.class}
236
)
237
@SelectMethod(
238
    type = CalculatorTest.class,
239
    name = "testAdd", 
240
    parameterTypes = {double.class, double.class}
241
)
242
class OverloadedMethodSuite {
243
}
244
```
245

246
### @Select Annotation (Generic Selector)
247

248
Selects tests based on prefixed selector identifiers, providing a unified interface for various selection strategies.
249

250
```java { .api }
251
/**
252
 * Selects tests based on prefixed selector identifiers.
253
 * Uses DiscoverySelectors.parse(String) for parsing selector syntax.
254
 * Supports class:, method:, package:, file:, directory:, uri:, module: prefixes.
255
 * 
256
 * @since 1.11
257
 */
258
@Retention(RetentionPolicy.RUNTIME)
259
@Target(ElementType.TYPE)
260
@Inherited
261
@Documented
262
@Repeatable(Selects.class)
263
@API(status = EXPERIMENTAL, since = "1.11")
264
public @interface Select {
265
    /**
266
     * One or more prefixed selector identifiers.
267
     * @return array of selector identifiers to parse and apply
268
     */
269
    String[] value();
270
}
271

272
/**
273
 * Container annotation for multiple @Select declarations.
274
 * @since 1.11
275
 */
276
@Retention(RetentionPolicy.RUNTIME)
277
@Target(ElementType.TYPE)
278
@Inherited
279
@Documented
280
@API(status = EXPERIMENTAL, since = "1.11")
281
public @interface Selects {
282
    Select[] value();
283
}
284
```
285

286
**Usage Examples:**
287

288
```java
289
// Mixed selector types
290
@Suite
291
@Select({
292
    "class:com.example.UserTest",
293
    "method:com.example.ProductTest#testValidation",
294
    "package:com.example.integration"
295
})
296
class MixedSelectorSuite {
297
}
298

299
// File and directory selectors
300
@Suite
301
@Select({
302
    "file:src/test/java/UserTest.java",
303
    "directory:src/test/java/integration"
304
})
305
class FileBasedSuite {
306
}
307
```
308

309
### File and Resource Selection
310

311
Annotations for selecting tests based on file system paths and classpath resources.
312

313
```java { .api }
314
/**
315
 * Specifies a file to select for test suite execution.
316
 * @since 1.8
317
 */
318
@Retention(RetentionPolicy.RUNTIME)
319
@Target(ElementType.TYPE)
320
@Inherited
321
@Documented
322
@Repeatable(SelectFiles.class)
323
@API(status = STABLE, since = "1.10")
324
public @interface SelectFile {
325
    /**
326
     * The file to select for test execution.
327
     * @return file path to select
328
     */
329
    String value();
330
    
331
    /**
332
     * Line number within the file (ignored if ≤ 0).
333
     * @return line number for precise selection
334
     */
335
    int line() default 0;
336
    
337
    /**
338
     * Column number within the file (ignored if line ignored or ≤ 0).
339
     * @return column number for precise selection  
340
     */
341
    int column() default 0;
342
}
343

344
/**
345
 * Container for multiple @SelectFile declarations.
346
 * @since 1.8
347
 */
348
@Retention(RetentionPolicy.RUNTIME)
349
@Target(ElementType.TYPE)
350
@Inherited
351
@Documented
352
@API(status = STABLE, since = "1.10")
353
public @interface SelectFiles {
354
    SelectFile[] value();
355
}
356

357
/**
358
 * Specifies directories to select for test suite execution.
359
 * @since 1.8
360
 */
361
@Retention(RetentionPolicy.RUNTIME)
362
@Target(ElementType.TYPE)
363
@Inherited
364
@Documented
365
@API(status = STABLE, since = "1.10")
366
public @interface SelectDirectories {
367
    /**
368
     * One or more directories to select for test discovery.
369
     * @return array of directory paths
370
     */
371
    String[] value();
372
}
373

374
/**
375
 * Specifies a classpath resource to select for test suite execution.
376
 * @since 1.8
377
 */
378
@Retention(RetentionPolicy.RUNTIME)
379
@Target(ElementType.TYPE)
380
@Inherited
381
@Documented
382
@Repeatable(SelectClasspathResources.class)
383
@API(status = STABLE, since = "1.10")
384
public @interface SelectClasspathResource {
385
    /**
386
     * Name of classpath resource to select.
387
     * @return classpath resource name
388
     */
389
    String value();
390
    
391
    /**
392
     * Line number within the resource (ignored if ≤ 0).
393
     * @return line number for precise selection
394
     */
395
    int line() default 0;
396
    
397
    /**
398
     * Column number within the resource (ignored if line ignored or ≤ 0).
399
     * @return column number for precise selection
400
     */
401
    int column() default 0;
402
}
403

404
/**
405
 * Container for multiple @SelectClasspathResource declarations.
406
 * @since 1.8
407
 */
408
@Retention(RetentionPolicy.RUNTIME)
409
@Target(ElementType.TYPE)
410
@Inherited
411
@Documented
412
@API(status = STABLE, since = "1.10")
413
public @interface SelectClasspathResources {
414
    SelectClasspathResource[] value();
415
}
416
```
417

418
**Usage Examples:**
419

420
```java
421
// File selection with line numbers
422
@Suite
423
@SelectFile(value = "src/test/java/UserTest.java", line = 45)
424
@SelectFile("src/test/java/ProductTest.java")
425
class FileBasedSuite {
426
}
427

428
// Directory selection
429
@Suite
430
@SelectDirectories({
431
    "src/test/java/unit",
432
    "src/test/java/integration"
433
})
434
class DirectoryBasedSuite {
435
}
436

437
// Classpath resource selection
438
@Suite
439
@SelectClasspathResource("test-scenarios.json")
440
@SelectClasspathResource(value = "integration-tests.xml", line = 25)
441
class ResourceBasedSuite {
442
}
443
```
444

445
### Module and URI Selection
446

447
Advanced selection capabilities for modular systems and URI-based test identification.
448

449
```java { .api }
450
/**
451
 * Specifies modules to select for test suite execution.
452
 * @since 1.8
453
 */
454
@Retention(RetentionPolicy.RUNTIME)
455
@Target(ElementType.TYPE)
456
@Inherited
457
@Documented
458
@API(status = STABLE, since = "1.10")
459
public @interface SelectModules {
460
    /**
461
     * One or more modules to select for test discovery.
462
     * @return array of module names
463
     */
464
    String[] value();
465
}
466

467
/**
468
 * Specifies URIs to select for test suite execution.
469
 * @since 1.8
470
 */
471
@Retention(RetentionPolicy.RUNTIME)
472
@Target(ElementType.TYPE)
473
@Inherited
474
@Documented
475
@API(status = STABLE, since = "1.10")
476
public @interface SelectUris {
477
    /**
478
     * One or more URIs to select for test discovery.
479
     * @return array of URI strings
480
     */
481
    String[] value();
482
}
483
```
484

485
**Usage Examples:**
486

487
```java
488
// Module selection for modular applications
489
@Suite
490
@SelectModules({
491
    "com.example.core",
492
    "com.example.integration"
493
})
494
class ModularSuite {
495
}
496

497
// URI-based selection
498
@Suite
499
@SelectUris({
500
    "classpath:com/example/tests/",
501
    "file:///absolute/path/to/tests/"
502
})
503
class UriBasedSuite {
504
}
505
```
506

507
## Selection Strategy Patterns
508

509
### Explicit Class Selection
510

511
Direct specification of test classes:
512

513
```java
514
@Suite
515
@SelectClasses({
516
    UserServiceTest.class,
517
    UserRepositoryTest.class,
518
    UserControllerTest.class
519
})
520
class UserModuleSuite {
521
}
522
```
523

524
### Package-Based Discovery
525

526
Package selection with filtering:
527

528
```java
529
@Suite
530
@SelectPackages("com.example")
531
@IncludeClassNamePatterns(".*IntegrationTest")
532
@ExcludeClassNamePatterns(".*AbstractIntegrationTest")
533
class IntegrationSuite {
534
}
535
```
536

537
### Method-Level Precision
538

539
Specific method selection:
540

541
```java
542
@Suite
543
@SelectMethod(type = ServiceTest.class, name = "testCriticalFeature")
544
@SelectMethod("com.example.UtilTest#testSpecialCase(java.lang.String)")
545
class CriticalFeatureSuite {
546
}
547
```
548

549
### Mixed Selection Strategy
550

551
Combining multiple selection approaches:
552

553
```java
554
@Suite
555
@SelectClasses({CoreTest.class})              // Explicit classes
556
@SelectPackages("com.example.integration")    // Package discovery
557
@SelectMethod(type = UtilTest.class, name = "specialTest")  // Specific methods
558
@SelectFiles("src/test/resources/scenarios.feature")        // File-based tests
559
class ComprehensiveSelectionSuite {
560
}
561
```