0
# Test Discovery
1

2
Comprehensive test discovery system that enables test engines to find tests using selectors and refine results with filters. The discovery system supports various test sources including classes, methods, packages, files, and URIs.
3

4
## Capabilities
5

6
### EngineDiscoveryRequest Interface
7

8
Provides test engines with discovery configuration including selectors, filters, and configuration parameters.
9

10
```java { .api }
11
/**
12
 * Discovery request providing selectors, filters, and configuration for test discovery.
13
 */
14
public interface EngineDiscoveryRequest {
15
    /**
16
     * Get all discovery selectors of the specified type.
17
     * @param selectorType the type of selectors to retrieve
18
     * @return list of selectors of the specified type
19
     */
20
    <T extends DiscoverySelector> List<T> getSelectorsByType(Class<T> selectorType);
21
    
22
    /**
23
     * Get all discovery filters of the specified type.
24
     * @param filterType the type of filters to retrieve
25
     * @return list of filters of the specified type
26
     */
27
    <T extends DiscoveryFilter<?>> List<T> getFiltersByType(Class<T> filterType);
28
    
29
    /**
30
     * Get configuration parameters for the discovery request.
31
     * @return configuration parameters
32
     */
33
    ConfigurationParameters getConfigurationParameters();
34
    
35
    /**
36
     * Get the discovery listener for reporting discovery events.
37
     * @return discovery listener
38
     */
39
    EngineDiscoveryListener getDiscoveryListener();
40
    
41
    /**
42
     * Get the output directory provider.
43
     * @return output directory provider
44
     */
45
    OutputDirectoryProvider getOutputDirectoryProvider();
46
}
47
```
48

49
### DiscoverySelectors Factory
50

51
Factory class providing static methods for creating various types of discovery selectors.
52

53
```java { .api }
54
/**
55
 * Factory for creating discovery selectors of various types.
56
 */
57
public final class DiscoverySelectors {
58
    // URI-based selectors
59
    public static UriSelector selectUri(URI uri);
60
    public static UriSelector selectUri(String uri);
61
    
62
    // File-based selectors
63
    public static FileSelector selectFile(String path);
64
    public static FileSelector selectFile(File file);
65
    public static FileSelector selectFile(String path, FilePosition position);
66
    public static FileSelector selectFile(File file, FilePosition position);
67
    
68
    // Directory selectors
69
    public static DirectorySelector selectDirectory(String path);
70
    public static DirectorySelector selectDirectory(File directory);
71
    
72
    // Classpath selectors
73
    public static List<ClasspathRootSelector> selectClasspathRoots(Set<Path> classpathRoots);
74
    public static ClasspathResourceSelector selectClasspathResource(String classpathResourceName);
75
    public static ClasspathResourceSelector selectClasspathResource(String classpathResourceName, FilePosition position);
76
    public static ClasspathResourceSelector selectClasspathResource(Set<Resource> classpathResources);
77
    
78
    // Module selectors
79
    public static ModuleSelector selectModule(String moduleName);
80
    public static List<ModuleSelector> selectModules(Set<String> moduleNames);
81
    
82
    // Package selectors
83
    public static PackageSelector selectPackage(String packageName);
84
    
85
    // Class selectors
86
    public static ClassSelector selectClass(Class<?> clazz);
87
    public static ClassSelector selectClass(String className);
88
    public static ClassSelector selectClass(ClassLoader classLoader, String className);
89
    
90
    // Method selectors
91
    public static MethodSelector selectMethod(Class<?> javaClass, Method method);
92
    public static MethodSelector selectMethod(Class<?> javaClass, String methodName);
93
    public static MethodSelector selectMethod(Class<?> javaClass, String methodName, String parameterTypeNames);
94
    public static MethodSelector selectMethod(Class<?> javaClass, String methodName, Class<?>... parameterTypes);
95
    public static MethodSelector selectMethod(String className, String methodName);
96
    public static MethodSelector selectMethod(String className, String methodName, String parameterTypeNames);
97
    public static MethodSelector selectMethod(String className, String methodName, Class<?>... parameterTypes);
98
    public static MethodSelector selectMethod(String fullyQualifiedMethodName);
99
    public static MethodSelector selectMethod(ClassLoader classLoader, String fullyQualifiedMethodName);
100
    public static MethodSelector selectMethod(ClassLoader classLoader, String className, String methodName);
101
    public static MethodSelector selectMethod(ClassLoader classLoader, String className, String methodName, String parameterTypeNames);
102
    
103
    // Nested class selectors
104
    public static NestedClassSelector selectNestedClass(List<Class<?>> enclosingClasses, Class<?> nestedClass);
105
    public static NestedClassSelector selectNestedClass(List<String> enclosingClassNames, String nestedClassName);
106
    public static NestedClassSelector selectNestedClass(ClassLoader classLoader, List<String> enclosingClassNames, String nestedClassName);
107
    
108
    // Nested method selectors
109
    public static NestedMethodSelector selectNestedMethod(List<Class<?>> enclosingClasses, Class<?> nestedClass, Method method);
110
    public static NestedMethodSelector selectNestedMethod(List<Class<?>> enclosingClasses, Class<?> nestedClass, String methodName);
111
    public static NestedMethodSelector selectNestedMethod(List<Class<?>> enclosingClasses, Class<?> nestedClass, String methodName, String parameterTypeNames);
112
    public static NestedMethodSelector selectNestedMethod(List<Class<?>> enclosingClasses, Class<?> nestedClass, String methodName, Class<?>... parameterTypes);
113
    public static NestedMethodSelector selectNestedMethod(List<String> enclosingClassNames, String nestedClassName, String methodName);
114
    public static NestedMethodSelector selectNestedMethod(List<String> enclosingClassNames, String nestedClassName, String methodName, String parameterTypeNames);
115
    public static NestedMethodSelector selectNestedMethod(List<String> enclosingClassNames, String nestedClassName, String methodName, Class<?>... parameterTypes);
116
    public static NestedMethodSelector selectNestedMethod(ClassLoader classLoader, List<String> enclosingClassNames, String nestedClassName, String methodName);
117
    public static NestedMethodSelector selectNestedMethod(ClassLoader classLoader, List<String> enclosingClassNames, String nestedClassName, String methodName, String parameterTypeNames);
118
    
119
    // Unique ID selectors
120
    public static UniqueIdSelector selectUniqueId(UniqueId uniqueId);
121
    public static UniqueIdSelector selectUniqueId(String uniqueId);
122
    
123
    // Iteration selectors (for parameterized tests)
124
    public static IterationSelector selectIteration(DiscoverySelector parentSelector, int... iterationIndices);
125
    
126
    // Parsing methods
127
    public static Optional<? extends DiscoverySelector> parse(String identifier);
128
    public static Optional<? extends DiscoverySelector> parse(DiscoverySelectorIdentifier identifier);
129
    public static Stream<? extends DiscoverySelector> parseAll(String... identifiers);
130
    public static Stream<? extends DiscoverySelector> parseAll(Collection<DiscoverySelectorIdentifier> identifiers);
131
}
132
```
133

134
**Usage Example:**
135

136
```java
137
import org.junit.platform.engine.discovery.*;
138

139
// Discover all tests in specific classes
140
List<ClassSelector> classSelectors = Arrays.asList(
141
    DiscoverySelectors.selectClass(MyTestClass.class),
142
    DiscoverySelectors.selectClass("com.example.AnotherTestClass")
143
);
144

145
// Discover specific test methods
146
MethodSelector methodSelector = DiscoverySelectors.selectMethod(
147
    MyTestClass.class, "testSomething"
148
);
149

150
// Discover tests in packages
151
PackageSelector packageSelector = DiscoverySelectors.selectPackage("com.example.tests");
152

153
// Process selectors in engine
154
@Override
155
public TestDescriptor discover(EngineDiscoveryRequest discoveryRequest, UniqueId uniqueId) {
156
    EngineDescriptor engineDescriptor = new EngineDescriptor(uniqueId, "My Engine");
157
    
158
    // Process class selectors
159
    for (ClassSelector selector : discoveryRequest.getSelectorsByType(ClassSelector.class)) {
160
        Class<?> testClass = selector.getJavaClass();
161
        // Create descriptors for discovered tests
162
    }
163
    
164
    // Process method selectors
165
    for (MethodSelector selector : discoveryRequest.getSelectorsByType(MethodSelector.class)) {
166
        Method testMethod = selector.getJavaMethod();
167
        // Create descriptors for specific methods
168
    }
169
    
170
    return engineDescriptor;
171
}
172
```
173

174
### Discovery Filters
175

176
Filters for refining discovery results by including or excluding tests based on class names, package names, and other criteria.
177

178
```java { .api }
179
/**
180
 * Base interface for discovery filters.
181
 * @param T the type being filtered
182
 */
183
public interface DiscoveryFilter<T> extends Filter<T> {
184
    // Inherits apply method from Filter interface
185
}
186

187
/**
188
 * Abstract base class for class name filters.
189
 */
190
public abstract class ClassNameFilter implements DiscoveryFilter<Class<?>> {
191
    protected ClassNameFilter(String pattern);
192
    protected ClassNameFilter(String... patterns);
193
    protected ClassNameFilter(List<String> patterns);
194
}
195

196
/**
197
 * Include filter for class names using regex patterns.
198
 */
199
public class IncludeClassNameFilter extends ClassNameFilter {
200
    public IncludeClassNameFilter(String pattern);
201
    public IncludeClassNameFilter(String... patterns);
202
    public IncludeClassNameFilter(List<String> patterns);
203
}
204

205
/**
206
 * Exclude filter for class names using regex patterns.
207
 */
208
public class ExcludeClassNameFilter extends ClassNameFilter {
209
    public ExcludeClassNameFilter(String pattern);
210
    public ExcludeClassNameFilter(String... patterns);
211
    public ExcludeClassNameFilter(List<String> patterns);
212
}
213

214
/**
215
 * Abstract base class for package name filters.
216
 */
217
public abstract class PackageNameFilter implements DiscoveryFilter<String> {
218
    protected PackageNameFilter(String pattern);
219
    protected PackageNameFilter(String... patterns);
220
    protected PackageNameFilter(List<String> patterns);
221
}
222

223
/**
224
 * Include filter for package names using regex patterns.
225
 */
226
public class IncludePackageNameFilter extends PackageNameFilter {
227
    public IncludePackageNameFilter(String pattern);
228
    public IncludePackageNameFilter(String... patterns);
229
    public IncludePackageNameFilter(List<String> patterns);
230
}
231

232
/**
233
 * Exclude filter for package names using regex patterns.
234
 */
235
public class ExcludePackageNameFilter extends PackageNameFilter {
236
    public ExcludePackageNameFilter(String pattern);
237
    public ExcludePackageNameFilter(String... patterns);
238
    public ExcludePackageNameFilter(List<String> patterns);
239
}
240
```
241

242
### Individual Selector Classes
243

244
Specific selector implementations for different types of test sources.
245

246
```java { .api }
247
/**
248
 * Selector for class-based test discovery.
249
 */
250
public class ClassSelector implements DiscoverySelector {
251
    public Class<?> getJavaClass();
252
    public String getClassName();
253
    public ClassLoader getClassLoader();
254
}
255

256
/**
257
 * Selector for method-based test discovery.
258
 */
259
public class MethodSelector implements DiscoverySelector {
260
    public Class<?> getJavaClass();
261
    public Method getJavaMethod();
262
    public String getClassName();
263
    public String getMethodName();
264
    public String getMethodParameterTypes();
265
    public ClassLoader getClassLoader();
266
}
267

268
/**
269
 * Selector for package-based test discovery.
270
 */
271
public class PackageSelector implements DiscoverySelector {
272
    public String getPackageName();
273
}
274

275
/**
276
 * Selector for URI-based test discovery.
277
 */
278
public class UriSelector implements DiscoverySelector {
279
    public URI getUri();
280
}
281

282
/**
283
 * Selector for file-based test discovery.
284
 */
285
public class FileSelector implements DiscoverySelector {
286
    public Path getPath();
287
    public File getFile();
288
    public Optional<FilePosition> getPosition();
289
}
290

291
/**
292
 * Selector for directory-based test discovery.
293
 */
294
public class DirectorySelector implements DiscoverySelector {
295
    public Path getPath();
296
    public File getDirectory();
297
}
298

299
/**
300
 * Selector for unique ID-based test discovery.
301
 */
302
public class UniqueIdSelector implements DiscoverySelector {
303
    public UniqueId getUniqueId();
304
}
305
```
306

307
### File Position Support
308

309
Represents positions within files for precise test location.
310

311
```java { .api }
312
/**
313
 * Position within a file (line and column numbers).
314
 */
315
public class FilePosition {
316
    /**
317
     * Create a file position from line number.
318
     * @param line the line number (1-based)
319
     * @return FilePosition instance
320
     */
321
    public static FilePosition from(int line);
322
    
323
    /**
324
     * Create a file position from line and column numbers.
325
     * @param line the line number (1-based)
326
     * @param column the column number (1-based)
327
     * @return FilePosition instance
328
     */
329
    public static FilePosition from(int line, int column);
330
    
331
    /**
332
     * Get the line number.
333
     * @return line number (1-based)
334
     */
335
    public int getLine();
336
    
337
    /**
338
     * Get the column number.
339
     * @return optional column number (1-based)
340
     */
341
    public Optional<Integer> getColumn();
342
}
343
```
344

345
### Discovery Listeners
346

347
Interface for receiving discovery events and issues during the discovery process.
348

349
```java { .api }
350
/**
351
 * Listener for discovery events.
352
 */
353
public interface EngineDiscoveryListener {
354
    /**
355
     * Called when a selector is skipped during discovery.
356
     * @param selector the skipped selector
357
     * @param reason the reason for skipping
358
     */
359
    void selectorProcessed(DiscoverySelector selector);
360
    
361
    /**
362
     * Called when an issue is encountered during discovery.
363
     * @param issue the discovery issue
364
     */
365
    void discoveryIssue(DiscoveryIssue issue);
366
}
367

368
/**
369
 * Represents an issue encountered during discovery.
370
 */
371
public interface DiscoveryIssue {
372
    /**
373
     * Get the issue message.
374
     * @return the issue message
375
     */
376
    String getMessage();
377
    
378
    /**
379
     * Get the associated throwable.
380
     * @return optional throwable
381
     */
382
    Optional<Throwable> getThrowable();
383
}
384
```