0
# Configuration and Factory
1

2
Flexible launcher configuration and factory patterns supporting both default and custom configurations with auto-registration control and service provider integration.
3

4
## Capabilities
5

6
### LauncherFactory Class
7

8
Factory for creating Launcher instances with optional custom configuration. Provides both session-based and direct launcher creation.
9

10
```java { .api }
11
/**
12
 * Factory for creating Launcher instances
13
 */
14
class LauncherFactory {
15
    /**
16
     * Open launcher session with default configuration
17
     * @return LauncherSession with default settings
18
     */
19
    static LauncherSession openSession();
20
    
21
    /**
22
     * Open launcher session with custom configuration
23
     * @param config - LauncherConfig specifying custom settings
24
     * @return LauncherSession with custom configuration
25
     */
26
    static LauncherSession openSession(LauncherConfig config);
27
    
28
    /**
29
     * Create launcher with default configuration
30
     * @return Launcher instance with default settings
31
     */
32
    static Launcher create();
33
    
34
    /**
35
     * Create launcher with custom configuration
36
     * @param config - LauncherConfig specifying custom settings
37
     * @return Launcher instance with custom configuration
38
     */
39
    static Launcher create(LauncherConfig config);
40
}
41
```
42

43
**Usage Examples:**
44

45
```java
46
import org.junit.platform.launcher.core.*;
47

48
// Default launcher
49
Launcher defaultLauncher = LauncherFactory.create();
50

51
// Session-based usage
52
try (LauncherSession session = LauncherFactory.openSession()) {
53
    Launcher launcher = session.getLauncher();
54
    // Use launcher for multiple operations
55
}
56

57
// Custom configuration
58
LauncherConfig config = LauncherConfig.builder()
59
    .enableTestEngineAutoRegistration(false)
60
    .addTestEngines(new MyCustomTestEngine())
61
    .addTestExecutionListeners(new MyCustomListener())
62
    .build();
63

64
Launcher customLauncher = LauncherFactory.create(config);
65
```
66

67
### LauncherConfig Interface
68

69
Configuration API for creating Launchers with fine-grained control over auto-registration and additional components.
70

71
```java { .api }
72
/**
73
 * Configuration API for creating Launchers
74
 */
75
interface LauncherConfig {
76
    /**
77
     * Check if test engine auto-registration is enabled
78
     * @return true if auto-registration enabled, false otherwise
79
     */
80
    boolean isTestEngineAutoRegistrationEnabled();
81
    
82
    /**
83
     * Check if launcher session listener auto-registration is enabled
84
     * @return true if auto-registration enabled, false otherwise
85
     */
86
    boolean isLauncherSessionListenerAutoRegistrationEnabled();
87
    
88
    /**
89
     * Check if launcher discovery listener auto-registration is enabled
90
     * @return true if auto-registration enabled, false otherwise
91
     */
92
    boolean isLauncherDiscoveryListenerAutoRegistrationEnabled();
93
    
94
    /**
95
     * Check if test execution listener auto-registration is enabled
96
     * @return true if auto-registration enabled, false otherwise
97
     */
98
    boolean isTestExecutionListenerAutoRegistrationEnabled();
99
    
100
    /**
101
     * Check if post-discovery filter auto-registration is enabled
102
     * @return true if auto-registration enabled, false otherwise
103
     */
104
    boolean isPostDiscoveryFilterAutoRegistrationEnabled();
105
    
106
    /**
107
     * Get additional test engines to register
108
     * @return Collection of TestEngine instances
109
     */
110
    Collection<TestEngine> getAdditionalTestEngines();
111
    
112
    /**
113
     * Get additional launcher session listeners to register
114
     * @return Collection of LauncherSessionListener instances
115
     */
116
    Collection<LauncherSessionListener> getAdditionalLauncherSessionListeners();
117
    
118
    /**
119
     * Get additional launcher discovery listeners to register
120
     * @return Collection of LauncherDiscoveryListener instances
121
     */
122
    Collection<LauncherDiscoveryListener> getAdditionalLauncherDiscoveryListeners();
123
    
124
    /**
125
     * Get additional test execution listeners to register
126
     * @return Collection of TestExecutionListener instances
127
     */
128
    Collection<TestExecutionListener> getAdditionalTestExecutionListeners();
129
    
130
    /**
131
     * Get additional post-discovery filters to register
132
     * @return Collection of PostDiscoveryFilter instances
133
     */
134
    Collection<PostDiscoveryFilter> getAdditionalPostDiscoveryFilters();
135
    
136
    /**
137
     * Create new configuration builder
138
     * @return LauncherConfig.Builder instance
139
     */
140
    static Builder builder();
141
}
142
```
143

144
### LauncherConfig.Builder Class
145

146
Builder for creating LauncherConfig instances with fluent API.
147

148
```java { .api }
149
/**
150
 * Builder for creating LauncherConfig instances
151
 */
152
interface Builder {
153
    /**
154
     * Enable or disable test engine auto-registration
155
     * @param enabled - Whether to enable auto-registration
156
     * @return This builder for method chaining
157
     */
158
    Builder enableTestEngineAutoRegistration(boolean enabled);
159
    
160
    /**
161
     * Enable or disable launcher session listener auto-registration
162
     * @param enabled - Whether to enable auto-registration
163
     * @return This builder for method chaining
164
     */
165
    Builder enableLauncherSessionListenerAutoRegistration(boolean enabled);
166
    
167
    /**
168
     * Enable or disable launcher discovery listener auto-registration
169
     * @param enabled - Whether to enable auto-registration
170
     * @return This builder for method chaining
171
     */
172
    Builder enableLauncherDiscoveryListenerAutoRegistration(boolean enabled);
173
    
174
    /**
175
     * Enable or disable test execution listener auto-registration
176
     * @param enabled - Whether to enable auto-registration
177
     * @return This builder for method chaining
178
     */
179
    Builder enableTestExecutionListenerAutoRegistration(boolean enabled);
180
    
181
    /**
182
     * Enable or disable post-discovery filter auto-registration
183
     * @param enabled - Whether to enable auto-registration
184
     * @return This builder for method chaining
185
     */
186
    Builder enablePostDiscoveryFilterAutoRegistration(boolean enabled);
187
    
188
    /**
189
     * Add additional test engines
190
     * @param testEngines - TestEngine instances to add
191
     * @return This builder for method chaining
192
     */
193
    Builder addTestEngines(TestEngine... testEngines);
194
    
195
    /**
196
     * Add additional launcher session listeners
197
     * @param listeners - LauncherSessionListener instances to add
198
     * @return This builder for method chaining
199
     */
200
    Builder addLauncherSessionListeners(LauncherSessionListener... listeners);
201
    
202
    /**
203
     * Add additional launcher discovery listeners
204
     * @param listeners - LauncherDiscoveryListener instances to add
205
     * @return This builder for method chaining
206
     */
207
    Builder addLauncherDiscoveryListeners(LauncherDiscoveryListener... listeners);
208
    
209
    /**
210
     * Add additional test execution listeners
211
     * @param listeners - TestExecutionListener instances to add
212
     * @return This builder for method chaining
213
     */
214
    Builder addTestExecutionListeners(TestExecutionListener... listeners);
215
    
216
    /**
217
     * Add additional post-discovery filters
218
     * @param filters - PostDiscoveryFilter instances to add
219
     * @return This builder for method chaining
220
     */
221
    Builder addPostDiscoveryFilters(PostDiscoveryFilter... filters);
222
    
223
    /**
224
     * Build the LauncherConfig
225
     * @return Configured LauncherConfig instance
226
     */
227
    LauncherConfig build();
228
}
229
```
230

231
**Usage Examples:**
232

233
```java
234
import org.junit.platform.launcher.core.*;
235
import org.junit.platform.launcher.listeners.*;
236

237
// Disable auto-registration and provide custom components
238
LauncherConfig customConfig = LauncherConfig.builder()
239
    .enableTestEngineAutoRegistration(false)
240
    .enableTestExecutionListenerAutoRegistration(false)
241
    .addTestEngines(new MyCustomEngine())
242
    .addTestExecutionListeners(
243
        new SummaryGeneratingListener(),
244
        LoggingListener.forJavaUtilLogging()
245
    )
246
    .build();
247

248
// Selective auto-registration
249
LauncherConfig selectiveConfig = LauncherConfig.builder()
250
    .enableTestEngineAutoRegistration(true)           // Enable engine discovery
251
    .enableTestExecutionListenerAutoRegistration(false) // Disable listener discovery
252
    .addTestExecutionListeners(new MySpecificListener()) // Add specific listeners
253
    .build();
254

255
// Complete custom configuration
256
LauncherConfig fullCustomConfig = LauncherConfig.builder()
257
    .enableTestEngineAutoRegistration(false)
258
    .enableLauncherSessionListenerAutoRegistration(false)
259
    .enableLauncherDiscoveryListenerAutoRegistration(false)
260
    .enableTestExecutionListenerAutoRegistration(false)
261
    .enablePostDiscoveryFilterAutoRegistration(false)
262
    .addTestEngines(
263
        new JupiterTestEngine(),
264
        new MyCustomEngine()
265
    )
266
    .addLauncherSessionListeners(new MySessionListener())
267
    .addLauncherDiscoveryListeners(
268
        LauncherDiscoveryListeners.logging(),
269
        new MyDiscoveryListener()
270
    )
271
    .addTestExecutionListeners(
272
        new SummaryGeneratingListener(),
273
        new MyExecutionListener()
274
    )
275
    .addPostDiscoveryFilters(new MyCustomFilter())
276
    .build();
277

278
// Use with factory
279
Launcher launcher = LauncherFactory.create(fullCustomConfig);
280
```
281

282
### LauncherConstants Class
283

284
Collection of constants related to Launcher configuration parameters.
285

286
```java { .api }
287
/**
288
 * Collection of constants related to Launcher configuration
289
 */
290
class LauncherConstants {
291
    /** Property name for capturing stdout during test execution */
292
    String CAPTURE_STDOUT_PROPERTY_NAME = "junit.platform.output.capture.stdout";
293
    
294
    /** Property name for capturing stderr during test execution */
295
    String CAPTURE_STDERR_PROPERTY_NAME = "junit.platform.output.capture.stderr";
296
    
297
    /** Property name for maximum buffer size when capturing output */
298
    String CAPTURE_MAX_BUFFER_PROPERTY_NAME = "junit.platform.output.capture.maxBuffer";
299
    
300
    /** Default maximum buffer size for capturing output (1MB) */
301
    int CAPTURE_MAX_BUFFER_DEFAULT = 1024 * 1024;
302
    
303
    /** Property name for deactivating listeners matching a pattern */
304
    String DEACTIVATE_LISTENERS_PATTERN_PROPERTY_NAME = "junit.platform.listeners.deactivate";
305
    
306
    /** Pattern for deactivating all listeners */
307
    String DEACTIVATE_ALL_LISTENERS_PATTERN = "*";
308
    
309
    /** Property name for enabling launcher interceptors */
310
    String ENABLE_LAUNCHER_INTERCEPTORS = "junit.platform.launcher.interceptors.enabled";
311
    
312
    /** Property name for enabling dry run mode (discovery only) */
313
    String DRY_RUN_PROPERTY_NAME = "junit.platform.execution.dryrun";
314
    
315
    /** Property name for specifying output directory */
316
    String OUTPUT_DIR_PROPERTY_NAME = "junit.platform.output.dir";
317
    
318
    /** Property name for enabling stacktrace pruning */
319
    String STACKTRACE_PRUNING_ENABLED_PROPERTY_NAME = "junit.platform.stacktrace.pruning.enabled";
320
    
321
    /** Report entry key for captured stdout */
322
    String STDOUT_REPORT_ENTRY_KEY = "stdout";
323
    
324
    /** Report entry key for captured stderr */
325
    String STDERR_REPORT_ENTRY_KEY = "stderr";
326
    
327
    /** Placeholder for unique numbers in output directory names */
328
    String OUTPUT_DIR_UNIQUE_NUMBER_PLACEHOLDER = "{unique-number}";
329
}
330
```
331

332
**Usage Examples:**
333

334
```java
335
import org.junit.platform.launcher.LauncherConstants;
336
import org.junit.platform.launcher.core.LauncherDiscoveryRequestBuilder;
337

338
// Configure request with launcher constants
339
LauncherDiscoveryRequest request = LauncherDiscoveryRequestBuilder.request()
340
    .selectors(selectPackage("com.example"))
341
    .configurationParameter(LauncherConstants.CAPTURE_STDOUT_PROPERTY_NAME, "true")
342
    .configurationParameter(LauncherConstants.CAPTURE_STDERR_PROPERTY_NAME, "true")
343
    .configurationParameter(LauncherConstants.OUTPUT_DIR_PROPERTY_NAME, "/tmp/test-output")
344
    .build();
345

346
// Dry run mode (discovery only, no execution)
347
LauncherDiscoveryRequest dryRunRequest = LauncherDiscoveryRequestBuilder.request()
348
    .selectors(selectPackage("com.example"))
349
    .configurationParameter(LauncherConstants.DRY_RUN_PROPERTY_NAME, "true")
350
    .build();
351

352
// Disable specific listeners
353
LauncherDiscoveryRequest filteredRequest = LauncherDiscoveryRequestBuilder.request()
354
    .selectors(selectPackage("com.example"))
355
    .configurationParameter(
356
        LauncherConstants.DEACTIVATE_LISTENERS_PATTERN_PROPERTY_NAME, 
357
        "org.example.SlowListener"
358
    )
359
    .build();
360
```
361

362
## Service Provider Interface (SPI)
363

364
The launcher uses Java's ServiceLoader mechanism for auto-registration of components:
365

366
### Test Engines
367
Create `META-INF/services/org.junit.platform.engine.TestEngine`:
368
```text
369
com.example.MyCustomTestEngine
370
com.example.AnotherTestEngine
371
```
372

373
### Test Execution Listeners
374
Create `META-INF/services/org.junit.platform.launcher.TestExecutionListener`:
375
```text
376
com.example.MyExecutionListener
377
com.example.ReportingListener
378
```
379

380
### Launcher Session Listeners
381
Create `META-INF/services/org.junit.platform.launcher.LauncherSessionListener`:
382
```text
383
com.example.MySessionListener
384
```
385

386
### Discovery Listeners
387
Create `META-INF/services/org.junit.platform.launcher.LauncherDiscoveryListener`:
388
```text
389
com.example.MyDiscoveryListener
390
```
391

392
### Post-Discovery Filters
393
Create `META-INF/services/org.junit.platform.launcher.PostDiscoveryFilter`:
394
```text
395
com.example.MyCustomFilter
396
```
397

398
## Configuration Precedence
399

400
Configuration sources are processed in this order (highest to lowest precedence):
401

402
1. **Programmatic Configuration** - LauncherConfig builder settings
403
2. **System Properties** - JVM system properties
404
3. **Configuration Parameters** - LauncherDiscoveryRequest configuration
405
4. **Auto-discovered Components** - ServiceLoader-discovered implementations
406
5. **Default Values** - Built-in defaults
407

408
## Environment Variables and System Properties
409

410
Key system properties that affect launcher behavior:
411

412
- `junit.platform.output.capture.stdout` - Capture stdout output
413
- `junit.platform.output.capture.stderr` - Capture stderr output
414
- `junit.platform.listeners.deactivate` - Deactivate listeners by pattern
415
- `junit.platform.launcher.interceptors.enabled` - Enable interceptors
416
- `junit.platform.execution.dryrun` - Enable dry run mode
417
- `junit.platform.output.dir` - Set output directory
418

419
## Custom Component Integration
420

421
Example of creating and integrating custom components:
422

423
```java
424
// Custom test engine
425
public class MyTestEngine implements TestEngine {
426
    @Override
427
    public String getId() { return "my-engine"; }
428
    
429
    @Override
430
    public TestDescriptor discover(EngineDiscoveryRequest discoveryRequest, UniqueId uniqueId) {
431
        // Implementation
432
    }
433
    
434
    @Override
435
    public void execute(ExecutionRequest executionRequest) {
436
        // Implementation
437
    }
438
}
439

440
// Custom listener
441
public class MyExecutionListener implements TestExecutionListener {
442
    @Override
443
    public void executionStarted(TestIdentifier testIdentifier) {
444
        // Custom logic
445
    }
446
    
447
    @Override
448
    public void executionFinished(TestIdentifier testIdentifier, TestExecutionResult result) {
449
        // Custom logic
450
    }
451
}
452

453
// Integration via configuration
454
LauncherConfig config = LauncherConfig.builder()
455
    .addTestEngines(new MyTestEngine())
456
    .addTestExecutionListeners(new MyExecutionListener())
457
    .build();
458

459
Launcher launcher = LauncherFactory.create(config);
460
```