0
# JUnit Platform Launcher
1

2
JUnit Platform Launcher provides programmatic APIs for discovering and executing tests on the JUnit Platform. It serves as the foundational layer that enables test frameworks to register test engines, discover test cases, and execute them in a controlled manner. This API is primarily used by IDEs, build tools, and custom test runners to integrate with the JUnit 5 testing framework.
3

4
## Package Information
5

6
- **Package Name**: org.junit.platform:junit-platform-launcher
7
- **Package Type**: maven
8
- **Language**: Java
9
- **Installation**: Add to your Maven or Gradle dependencies
10

11
Maven:
12
```xml
13
<dependency>
14
    <groupId>org.junit.platform</groupId>
15
    <artifactId>junit-platform-launcher</artifactId>
16
    <version>1.12.2</version>
17
</dependency>
18
```
19

20
Gradle:
21
```kotlin
22
implementation("org.junit.platform:junit-platform-launcher:1.12.2")
23
```
24

25
## Core Imports
26

27
```java
28
import org.junit.platform.launcher.Launcher;
29
import org.junit.platform.launcher.LauncherSession;
30
import org.junit.platform.launcher.TestPlan;
31
import org.junit.platform.launcher.TestExecutionListener;
32
import org.junit.platform.launcher.core.LauncherFactory;
33
import org.junit.platform.launcher.core.LauncherDiscoveryRequestBuilder;
34
```
35

36
## Basic Usage
37

38
```java
39
import org.junit.platform.launcher.*;
40
import org.junit.platform.launcher.core.*;
41
import static org.junit.platform.engine.discovery.DiscoverySelectors.*;
42

43
// Create a launcher and discovery request
44
Launcher launcher = LauncherFactory.create();
45

46
LauncherDiscoveryRequest request = LauncherDiscoveryRequestBuilder.request()
47
    .selectors(selectPackage("com.example.tests"))
48
    .build();
49

50
// Discover and execute tests
51
TestPlan testPlan = launcher.discover(request);
52
launcher.execute(testPlan, new MyTestExecutionListener());
53

54
// Or execute directly from request
55
launcher.execute(request, new MyTestExecutionListener());
56
```
57

58
## Architecture
59

60
The JUnit Platform Launcher is built around several key components:
61

62
- **Launcher Interface**: Main entry point for test discovery and execution operations
63
- **Session Management**: `LauncherSession` provides lifecycle management for repeated test operations
64
- **Discovery System**: Request builders and listeners for flexible test discovery configuration
65
- **Execution System**: Event-driven test execution with comprehensive listener support
66
- **Filtering System**: Multiple filter types for precise test selection (engines, tags, methods)
67
- **Factory Pattern**: `LauncherFactory` provides clean instantiation with configuration support
68

69
## Capabilities
70

71
### Core Test Operations
72

73
Primary interfaces for discovering and executing tests, including both one-shot operations and session-based repeated execution patterns.
74

75
```java { .api }
76
// Main launcher interface
77
interface Launcher {
78
    void registerLauncherDiscoveryListeners(LauncherDiscoveryListener... listeners);
79
    void registerTestExecutionListeners(TestExecutionListener... listeners);
80
    TestPlan discover(LauncherDiscoveryRequest request);
81
    void execute(LauncherDiscoveryRequest request, TestExecutionListener... listeners);
82
    void execute(TestPlan testPlan, TestExecutionListener... listeners);
83
}
84

85
// Session-based operations
86
interface LauncherSession extends AutoCloseable {
87
    Launcher getLauncher();
88
    void close();
89
}
90
```
91

92
[Core Test Operations](./core-operations.md)
93

94
### Discovery and Request Building
95

96
Comprehensive APIs for building discovery requests with selectors, filters, and configuration parameters. Supports flexible test selection patterns.
97

98
```java { .api }
99
class LauncherDiscoveryRequestBuilder {
100
    static LauncherDiscoveryRequestBuilder request();
101
    LauncherDiscoveryRequestBuilder selectors(DiscoverySelector... selectors);
102
    LauncherDiscoveryRequestBuilder filters(Filter<?>... filters);
103
    LauncherDiscoveryRequestBuilder configurationParameter(String key, String value);
104
    LauncherDiscoveryRequest build();
105
}
106

107
interface LauncherDiscoveryRequest extends EngineDiscoveryRequest {
108
    List<EngineFilter> getEngineFilters();
109
    List<PostDiscoveryFilter> getPostDiscoveryFilters();
110
    LauncherDiscoveryListener getDiscoveryListener();
111
}
112
```
113

114
[Discovery and Request Building](./discovery-requests.md)
115

116
### Event Listeners and Monitoring
117

118
Rich listener interfaces for monitoring test discovery and execution events. Supports custom reporting and integration with external systems.
119

120
```java { .api }
121
interface TestExecutionListener {
122
    void testPlanExecutionStarted(TestPlan testPlan);
123
    void testPlanExecutionFinished(TestPlan testPlan);
124
    void executionStarted(TestIdentifier testIdentifier);
125
    void executionFinished(TestIdentifier testIdentifier, TestExecutionResult result);
126
    void executionSkipped(TestIdentifier testIdentifier, String reason);
127
    void dynamicTestRegistered(TestIdentifier testIdentifier);
128
}
129

130
interface LauncherDiscoveryListener extends EngineDiscoveryListener {
131
    void launcherDiscoveryStarted(LauncherDiscoveryRequest request);
132
    void launcherDiscoveryFinished(LauncherDiscoveryRequest request);
133
}
134
```
135

136
[Event Listeners and Monitoring](./listeners.md)
137

138
### Test Plan and Identification
139

140
Comprehensive test plan representation with hierarchical test structure support and metadata access.
141

142
```java { .api }
143
class TestPlan {
144
    Set<TestIdentifier> getRoots();
145
    Optional<TestIdentifier> getParent(TestIdentifier child);
146
    Set<TestIdentifier> getChildren(TestIdentifier parent);
147
    Set<TestIdentifier> getDescendants(TestIdentifier parent);
148
    boolean containsTests();
149
    long countTestIdentifiers(Predicate<? super TestIdentifier> predicate);
150
}
151

152
class TestIdentifier implements Serializable {
153
    String getUniqueId();
154
    String getDisplayName();
155
    boolean isTest();
156
    boolean isContainer();
157
    Optional<TestSource> getSource();
158
    Set<TestTag> getTags();
159
}
160
```
161

162
[Test Plan and Identification](./test-plan.md)
163

164
### Filtering and Selection
165

166
Advanced filtering capabilities for precise test selection including engine filters, tag expressions, and method patterns.
167

168
```java { .api }
169
class EngineFilter implements Filter<TestEngine> {
170
    static EngineFilter includeEngines(String... engineIds);
171
    static EngineFilter excludeEngines(String... engineIds);
172
    FilterResult apply(TestEngine testEngine);
173
}
174

175
class TagFilter {
176
    static PostDiscoveryFilter includeTags(String... tagExpressions);
177
    static PostDiscoveryFilter excludeTags(String... tagExpressions);
178
}
179

180
interface MethodFilter extends PostDiscoveryFilter {
181
    static MethodFilter includeMethodNamePatterns(String... patterns);
182
    static MethodFilter excludeMethodNamePatterns(String... patterns);
183
}
184
```
185

186
[Filtering and Selection](./filters.md)
187

188
### Configuration and Factory
189

190
Flexible launcher configuration and factory patterns supporting both default and custom configurations with auto-registration control.
191

192
```java { .api }
193
class LauncherFactory {
194
    static LauncherSession openSession();
195
    static LauncherSession openSession(LauncherConfig config);
196
    static Launcher create();
197
    static Launcher create(LauncherConfig config);
198
}
199

200
interface LauncherConfig {
201
    boolean isTestEngineAutoRegistrationEnabled();
202
    boolean isLauncherSessionListenerAutoRegistrationEnabled();
203
    Collection<TestEngine> getAdditionalTestEngines();
204
    Collection<TestExecutionListener> getAdditionalTestExecutionListeners();
205
    static Builder builder();
206
}
207
```
208

209
[Configuration and Factory](./configuration.md)