0
# JUnit Platform Engine
1

2
The JUnit Platform Engine API provides the foundational infrastructure for implementing custom test engines in the JUnit Platform ecosystem. This library defines the core interfaces and contracts that test engines must implement to integrate with the JUnit Platform launcher, enabling diverse testing approaches to run within a unified platform.
3

4
## Package Information
5

6
- **Package Name**: org.junit.platform:junit-platform-engine
7
- **Package Type**: Maven
8
- **Language**: Java
9
- **Installation**: 
10
  ```xml
11
  <dependency>
12
    <groupId>org.junit.platform</groupId>
13
    <artifactId>junit-platform-engine</artifactId>
14
    <version>1.13.4</version>
15
  </dependency>
16
  ```
17

18
## Core Imports
19

20
```java
21
import org.junit.platform.engine.TestEngine;
22
import org.junit.platform.engine.TestDescriptor;
23
import org.junit.platform.engine.ExecutionRequest;
24
import org.junit.platform.engine.EngineDiscoveryRequest;
25
import org.junit.platform.engine.UniqueId;
26
```
27

28
## Basic Usage
29

30
```java
31
import org.junit.platform.engine.*;
32
import org.junit.platform.engine.support.descriptor.EngineDescriptor;
33

34
// Example: Basic test engine implementation
35
public class MyTestEngine implements TestEngine {
36
    private static final String ENGINE_ID = "my-test-engine";
37
    
38
    @Override
39
    public String getId() {
40
        return ENGINE_ID;
41
    }
42
    
43
    @Override
44
    public TestDescriptor discover(EngineDiscoveryRequest discoveryRequest, 
45
                                 UniqueId uniqueId) {
46
        // Create root descriptor for this engine
47
        TestDescriptor engineDescriptor = new EngineDescriptor(uniqueId, "My Test Engine");
48
        
49
        // Discovery logic: find tests based on selectors and filters
50
        discoveryRequest.getSelectorsByType(ClassSelector.class)
51
            .forEach(selector -> {
52
                // Add discovered tests as children
53
                // engineDescriptor.addChild(createTestDescriptor(...));
54
            });
55
        
56
        return engineDescriptor;
57
    }
58
    
59
    @Override
60
    public void execute(ExecutionRequest request) {
61
        TestDescriptor rootDescriptor = request.getRootTestDescriptor();
62
        EngineExecutionListener listener = request.getEngineExecutionListener();
63
        
64
        // Execute tests and notify listener of results
65
        listener.executionStarted(rootDescriptor);
66
        // ... execute children ...
67
        listener.executionFinished(rootDescriptor, TestExecutionResult.successful());
68
    }
69
}
70
```
71

72
## Architecture
73

74
The JUnit Platform Engine API is built around several key abstractions:
75

76
- **TestEngine**: The main interface that test engines implement to integrate with the platform
77
- **TestDescriptor**: Tree structure representing discovered tests and containers
78
- **Discovery System**: Selectors and filters for finding tests within codebases
79
- **Execution System**: Listeners and contexts for running tests and reporting results
80
- **Support Libraries**: Helper classes for common patterns like hierarchical execution
81
- **Storage System**: Hierarchical, namespaced stores for test-scoped data
82

83
## Capabilities
84

85
### Core Engine Interface
86

87
The fundamental TestEngine interface that all custom test engines must implement to integrate with the JUnit Platform.
88

89
```java { .api }
90
public interface TestEngine {
91
    String getId();
92
    TestDescriptor discover(EngineDiscoveryRequest discoveryRequest, UniqueId uniqueId);
93
    void execute(ExecutionRequest request);
94
    Optional<String> getGroupId();
95
    Optional<String> getArtifactId();
96
    Optional<String> getVersion();
97
}
98
```
99

100
[Engine Implementation](./engine-implementation.md)
101

102
### Test Discovery System
103

104
Comprehensive test discovery system with selectors for finding tests and filters for refining discovery results.
105

106
```java { .api }
107
public interface EngineDiscoveryRequest {
108
    <T extends DiscoverySelector> List<T> getSelectorsByType(Class<T> selectorType);
109
    <T extends DiscoveryFilter<?>> List<T> getFiltersByType(Class<T> filterType);
110
    ConfigurationParameters getConfigurationParameters();
111
    EngineDiscoveryListener getDiscoveryListener();
112
}
113

114
// Factory for creating discovery selectors
115
public final class DiscoverySelectors {
116
    public static ClassSelector selectClass(Class<?> clazz);
117
    public static MethodSelector selectMethod(Class<?> clazz, String methodName);
118
    public static PackageSelector selectPackage(String packageName);
119
    public static UriSelector selectUri(URI uri);
120
    // ... many more selector factory methods
121
}
122
```
123

124
[Test Discovery](./test-discovery.md)
125

126
### Test Execution System
127

128
Test execution infrastructure providing contexts, listeners, and result reporting for test engines.
129

130
```java { .api }
131
public final class ExecutionRequest {
132
    public TestDescriptor getRootTestDescriptor();
133
    public EngineExecutionListener getEngineExecutionListener();
134
    public ConfigurationParameters getConfigurationParameters();
135
    public NamespacedHierarchicalStore<Namespace> getStore();
136
}
137

138
public interface EngineExecutionListener {
139
    void executionStarted(TestDescriptor testDescriptor);
140
    void executionFinished(TestDescriptor testDescriptor, TestExecutionResult result);
141
    void executionSkipped(TestDescriptor testDescriptor, String reason);
142
    void dynamicTestRegistered(TestDescriptor testDescriptor);
143
    void reportingEntryPublished(TestDescriptor testDescriptor, ReportEntry entry);
144
}
145
```
146

147
[Test Execution](./test-execution.md)
148

149
### Test Descriptors and Structure
150

151
Hierarchical test descriptor system for representing discovered tests and containers with metadata, sources, and relationships.
152

153
```java { .api }
154
public interface TestDescriptor {
155
    UniqueId getUniqueId();
156
    String getDisplayName();
157
    Set<TestTag> getTags();
158
    Optional<TestSource> getSource();
159
    void addChild(TestDescriptor child);
160
    void removeChild(TestDescriptor child);
161
    Set<? extends TestDescriptor> getChildren();
162
    Type getType();
163
    
164
    enum Type { CONTAINER, TEST, CONTAINER_AND_TEST }
165
}
166
```
167

168
[Test Descriptors](./test-descriptors.md)
169

170
### Hierarchical Test Engine Support
171

172
Framework for building hierarchical test engines with parallel execution, resource management, and structured execution contexts.
173

174
```java { .api }
175
public abstract class HierarchicalTestEngine<C extends EngineExecutionContext> 
176
        implements TestEngine {
177
    protected abstract C createExecutionContext(ExecutionRequest request);
178
    protected HierarchicalTestExecutorService createExecutorService(ExecutionRequest request);
179
}
180

181
public interface Node<C extends EngineExecutionContext> {
182
    C prepare(C context) throws Exception;
183
    SkipResult shouldBeSkipped(C context) throws Exception;
184
    C before(C context) throws Exception;
185
    C execute(C context, DynamicTestExecutor dynamicTestExecutor) throws Exception;
186
    void after(C context) throws Exception;
187
    void cleanUp(C context) throws Exception;
188
}
189
```
190

191
[Hierarchical Engine Support](./hierarchical-engine.md)
192

193
### Configuration and Storage
194

195
Configuration system and hierarchical storage for test engines to manage parameters and test-scoped data.
196

197
```java { .api }
198
public interface ConfigurationParameters {
199
    Optional<String> get(String key);
200
    Optional<Boolean> getBoolean(String key);
201
    <T> Optional<T> get(String key, Function<String, T> transformer);
202
    Set<String> keySet();
203
}
204

205
public final class NamespacedHierarchicalStore<N> implements AutoCloseable {
206
    public Object get(N namespace, Object key);
207
    public <T> T get(N namespace, Object key, Class<T> requiredType);
208
    public Object put(N namespace, Object key, Object value);
209
    public <K, V> Object getOrComputeIfAbsent(N namespace, K key, Function<K, V> defaultCreator);
210
    public void close() throws Exception;
211
}
212
```
213

214
[Configuration and Storage](./config-storage.md)