0
# Core Test Operations
1

2
Core interfaces for discovering and executing tests, providing both one-shot operations and session-based patterns for repeated execution.
3

4
## Capabilities
5

6
### Launcher Interface
7

8
Main entry point for client code to discover and execute tests. Provides methods for registering listeners, discovering test plans, and executing tests.
9

10
```java { .api }
11
/**
12
 * Main entry point for discovering and executing tests
13
 */
14
interface Launcher {
15
    /**
16
     * Register discovery listeners for this launcher
17
     * @param listeners - LauncherDiscoveryListener instances to register
18
     */
19
    void registerLauncherDiscoveryListeners(LauncherDiscoveryListener... listeners);
20
    
21
    /**
22
     * Register test execution listeners for this launcher
23
     * @param listeners - TestExecutionListener instances to register
24
     */
25
    void registerTestExecutionListeners(TestExecutionListener... listeners);
26
    
27
    /**
28
     * Discover tests based on the supplied request
29
     * @param launcherDiscoveryRequest - LauncherDiscoveryRequest specifying discovery parameters
30
     * @return TestPlan representing the discovered tests
31
     */
32
    TestPlan discover(LauncherDiscoveryRequest launcherDiscoveryRequest);
33
    
34
    /**
35
     * Execute tests from a discovery request with optional listeners
36
     * @param launcherDiscoveryRequest - LauncherDiscoveryRequest specifying what to execute
37
     * @param listeners - Additional TestExecutionListener instances
38
     */
39
    void execute(LauncherDiscoveryRequest launcherDiscoveryRequest, TestExecutionListener... listeners);
40
    
41
    /**
42
     * Execute a pre-built test plan with optional listeners
43
     * @param testPlan - TestPlan to execute
44
     * @param listeners - Additional TestExecutionListener instances
45
     */
46
    void execute(TestPlan testPlan, TestExecutionListener... listeners);
47
}
48
```
49

50
**Usage Examples:**
51

52
```java
53
import org.junit.platform.launcher.*;
54
import org.junit.platform.launcher.core.*;
55
import static org.junit.platform.engine.discovery.DiscoverySelectors.*;
56

57
// Create launcher
58
Launcher launcher = LauncherFactory.create();
59

60
// Register global listeners
61
launcher.registerTestExecutionListeners(new SummaryGeneratingListener());
62

63
// Build discovery request
64
LauncherDiscoveryRequest request = LauncherDiscoveryRequestBuilder.request()
65
    .selectors(selectPackage("com.example.tests"))
66
    .build();
67

68
// Discover tests first, then execute
69
TestPlan testPlan = launcher.discover(request);
70
launcher.execute(testPlan);
71

72
// Or execute directly from request
73
launcher.execute(request, new MyCustomListener());
74
```
75

76
### LauncherSession Interface
77

78
Entry point for repeatedly discovering and executing tests within a managed session. Implements AutoCloseable for proper resource management.
79

80
```java { .api }
81
/**
82
 * Entry point for repeatedly discovering and executing tests
83
 * Implements AutoCloseable for proper resource management
84
 */
85
interface LauncherSession extends AutoCloseable {
86
    /**
87
     * Get the associated launcher for this session
88
     * @return Launcher instance for this session
89
     */
90
    Launcher getLauncher();
91
    
92
    /**
93
     * Close this session and notify all registered listeners
94
     */
95
    void close();
96
}
97
```
98

99
**Usage Examples:**
100

101
```java
102
import org.junit.platform.launcher.*;
103
import org.junit.platform.launcher.core.*;
104

105
// Session-based usage with try-with-resources
106
try (LauncherSession session = LauncherFactory.openSession()) {
107
    Launcher launcher = session.getLauncher();
108
    
109
    // Multiple discovery/execution cycles within the same session
110
    for (String testPackage : testPackages) {
111
        LauncherDiscoveryRequest request = LauncherDiscoveryRequestBuilder.request()
112
            .selectors(selectPackage(testPackage))
113
            .build();
114
            
115
        launcher.execute(request);
116
    }
117
} // Session automatically closed here
118
```
119

120
### LauncherSessionListener Interface
121

122
Listener interface for session lifecycle events. Allows tracking of session opening and closing for resource management and monitoring.
123

124
```java { .api }
125
/**
126
 * Listener interface for launcher session events
127
 * @since 1.10
128
 * @apiNote This interface is marked as @API(status = STABLE)
129
 */
130
interface LauncherSessionListener {
131
    /** No-op implementation of LauncherSessionListener */
132
    LauncherSessionListener NOOP = new LauncherSessionListener() {};
133
    /**
134
     * Called when a launcher session is opened
135
     * @param session - The LauncherSession that was opened
136
     */
137
    default void launcherSessionOpened(LauncherSession session) {}
138
    
139
    /**
140
     * Called when a launcher session is closed
141
     * @param session - The LauncherSession that was closed
142
     */
143
    default void launcherSessionClosed(LauncherSession session) {}
144
}
145
```
146

147
### LauncherInterceptor Interface
148

149
Interceptor for test discovery and execution in launcher sessions. Provides hook points for custom behavior during test operations.
150

151
```java { .api }
152
/**
153
 * Interceptor for test discovery and execution in launcher sessions
154
 * @since 1.10
155
 * @apiNote ⚠️ EXPERIMENTAL API - This interface is marked as @API(status = EXPERIMENTAL)
156
 * and may change in future releases without notice.
157
 */
158
interface LauncherInterceptor {
159
    /**
160
     * Intercept invocations during launcher operations
161
     * @param invocation - The Invocation to potentially modify or monitor
162
     * @return Result of the invocation
163
     */
164
    <T> T intercept(Invocation<T> invocation);
165
    
166
    /**
167
     * Represents an invocation in the interceptor chain
168
     */
169
    interface Invocation<T> {
170
        /**
171
         * Proceed with the invocation
172
         * @return Result of the invocation
173
         */
174
        T proceed();
175
    }
176
    
177
    /**
178
     * Close this interceptor and release any resources
179
     */
180
    void close();
181
}
182
```
183

184
## Service Provider Integration
185

186
The launcher supports service provider interface (SPI) for automatic registration of components:
187

188
- `LauncherSessionListener` implementations are auto-discovered via SPI
189
- `LauncherInterceptor` implementations are auto-discovered via SPI
190
- Custom `TestEngine` implementations are loaded automatically
191
- Configuration parameters control auto-registration behavior
192

193
## Error Handling
194

195
Launcher operations may throw:
196

197
- `PreconditionViolationException` - When preconditions are not met
198
- `TestAbortedException` - When tests are aborted
199
- Various runtime exceptions during test discovery or execution
200

201
Always handle exceptions appropriately when using launcher APIs, especially in integration scenarios.