0
# JUnit Jupiter Engine
1

2
JUnit Jupiter Engine provides the TestEngine implementation for discovering and executing Jupiter-based tests on the JUnit Platform. It serves as the execution engine that runs modern Java unit tests written using the JUnit Jupiter programming model, supporting advanced features like parameterized tests, dynamic tests, nested test classes, and a comprehensive extension system.
3

4
## Package Information
5

6
- **Package Name**: junit-jupiter-engine
7
- **Package Type**: Maven
8
- **Language**: Java
9
- **Group ID**: org.junit.jupiter
10
- **Artifact ID**: junit-jupiter-engine
11
- **Installation**: Add to Maven dependencies:
12

13
```xml
14
<dependency>
15
    <groupId>org.junit.jupiter</groupId>
16
    <artifactId>junit-jupiter-engine</artifactId>
17
    <version>5.13.4</version>
18
    <scope>test</scope>
19
</dependency>
20
```
21

22
For Gradle:
23

24
```gradle
25
testImplementation 'org.junit.jupiter:junit-jupiter-engine:5.13.4'
26
```
27

28
## Core Imports
29

30
```java
31
import org.junit.jupiter.engine.Constants;
32
```
33

34
## Basic Usage
35

36
The JUnit Jupiter Engine operates as a service provider automatically discovered by the JUnit Platform. Users typically interact with it through configuration rather than direct API usage:
37

38
```java
39
import org.junit.jupiter.engine.Constants;
40
import org.junit.platform.engine.ConfigurationParameters;
41

42
// Configure parallel execution
43
System.setProperty(Constants.PARALLEL_EXECUTION_ENABLED_PROPERTY_NAME, "true");
44

45
// Configure timeout settings
46
System.setProperty(Constants.DEFAULT_TEST_METHOD_TIMEOUT_PROPERTY_NAME, "5s");
47

48
// Configure extension auto-detection
49
System.setProperty(Constants.EXTENSIONS_AUTODETECTION_ENABLED_PROPERTY_NAME, "true");
50
```
51

52
## Architecture
53

54
The JUnit Jupiter Engine follows a service provider pattern where:
55

56
- **TestEngine Service**: The engine implements `org.junit.platform.engine.TestEngine` and is automatically discovered by the JUnit Platform
57
- **Internal Implementation**: All implementation classes are marked as internal API and should not be used directly
58
- **Configuration-Based Usage**: Users configure the engine through system properties and configuration parameters
59
- **Platform Integration**: The engine integrates with IDEs, build tools, and continuous integration systems through the JUnit Platform
60

61
## Capabilities
62

63
### Configuration Constants
64

65
The engine provides configuration property name constants for customizing test execution behavior. All constants are `public static final String` fields used as keys for system properties or configuration parameters.
66

67
```java { .api }
68
public final class Constants {
69
    // Extension Configuration
70
    public static final String EXTENSIONS_AUTODETECTION_ENABLED_PROPERTY_NAME = "junit.jupiter.extensions.autodetection.enabled";
71
    public static final String EXTENSIONS_AUTODETECTION_INCLUDE_PROPERTY_NAME = "junit.jupiter.extensions.autodetection.include";
72
    public static final String EXTENSIONS_AUTODETECTION_EXCLUDE_PROPERTY_NAME = "junit.jupiter.extensions.autodetection.exclude";
73
    
74
    @API(status = MAINTAINED, since = "5.13.3")
75
    public static final String EXTENSIONS_TIMEOUT_THREAD_DUMP_ENABLED_PROPERTY_NAME = "junit.jupiter.extensions.timeout.thread.dump.enabled";
76

77
    // Condition Configuration
78
    public static final String DEACTIVATE_CONDITIONS_PATTERN_PROPERTY_NAME = "junit.jupiter.conditions.deactivate";
79
    public static final String DEACTIVATE_ALL_CONDITIONS_PATTERN = "*";
80

81
    // Display Name Configuration
82
    public static final String DEFAULT_DISPLAY_NAME_GENERATOR_PROPERTY_NAME = "junit.jupiter.displayname.generator.default";
83

84
    // Test Instance Lifecycle
85
    public static final String DEFAULT_TEST_INSTANCE_LIFECYCLE_PROPERTY_NAME = "junit.jupiter.testinstance.lifecycle.default";
86

87
    // Parallel Execution
88
    @API(status = STABLE, since = "5.10")
89
    public static final String PARALLEL_EXECUTION_ENABLED_PROPERTY_NAME = "junit.jupiter.execution.parallel.enabled";
90
    @API(status = STABLE, since = "5.10")
91
    public static final String DEFAULT_PARALLEL_EXECUTION_MODE = "junit.jupiter.execution.parallel.mode.default";
92
    @API(status = STABLE, since = "5.10")
93
    public static final String DEFAULT_CLASSES_EXECUTION_MODE_PROPERTY_NAME = "junit.jupiter.execution.parallel.mode.classes.default";
94

95
    // Parallel Configuration Strategy
96
    @API(status = STABLE, since = "5.10")
97
    public static final String PARALLEL_CONFIG_STRATEGY_PROPERTY_NAME = "junit.jupiter.execution.parallel.config.strategy";
98
    @API(status = STABLE, since = "5.10")
99
    public static final String PARALLEL_CONFIG_FIXED_PARALLELISM_PROPERTY_NAME = "junit.jupiter.execution.parallel.config.fixed.parallelism";
100
    @API(status = MAINTAINED, since = "5.13.3")
101
    public static final String PARALLEL_CONFIG_FIXED_MAX_POOL_SIZE_PROPERTY_NAME = "junit.jupiter.execution.parallel.config.fixed.max-pool-size";
102
    @API(status = MAINTAINED, since = "5.13.3")
103
    public static final String PARALLEL_CONFIG_FIXED_SATURATE_PROPERTY_NAME = "junit.jupiter.execution.parallel.config.fixed.saturate";
104
    @API(status = STABLE, since = "5.10")
105
    public static final String PARALLEL_CONFIG_DYNAMIC_FACTOR_PROPERTY_NAME = "junit.jupiter.execution.parallel.config.dynamic.factor";
106
    @API(status = STABLE, since = "5.10")
107
    public static final String PARALLEL_CONFIG_CUSTOM_CLASS_PROPERTY_NAME = "junit.jupiter.execution.parallel.config.custom.class";
108

109
    // Timeout Configuration
110
    @API(status = STABLE, since = "5.10")
111
    public static final String DEFAULT_TIMEOUT_PROPERTY_NAME = "junit.jupiter.execution.timeout.default";
112
    @API(status = STABLE, since = "5.10")
113
    public static final String DEFAULT_TESTABLE_METHOD_TIMEOUT_PROPERTY_NAME = "junit.jupiter.execution.timeout.testable.method.default";
114
    @API(status = STABLE, since = "5.10")
115
    public static final String DEFAULT_TEST_METHOD_TIMEOUT_PROPERTY_NAME = "junit.jupiter.execution.timeout.test.method.default";
116
    @API(status = STABLE, since = "5.10")
117
    public static final String DEFAULT_TEST_TEMPLATE_METHOD_TIMEOUT_PROPERTY_NAME = "junit.jupiter.execution.timeout.testtemplate.method.default";
118
    @API(status = STABLE, since = "5.10")
119
    public static final String DEFAULT_TEST_FACTORY_METHOD_TIMEOUT_PROPERTY_NAME = "junit.jupiter.execution.timeout.testfactory.method.default";
120
    @API(status = STABLE, since = "5.10")
121
    public static final String DEFAULT_LIFECYCLE_METHOD_TIMEOUT_PROPERTY_NAME = "junit.jupiter.execution.timeout.lifecycle.method.default";
122
    @API(status = STABLE, since = "5.10")
123
    public static final String DEFAULT_BEFORE_ALL_METHOD_TIMEOUT_PROPERTY_NAME = "junit.jupiter.execution.timeout.beforeall.method.default";
124
    @API(status = STABLE, since = "5.10")
125
    public static final String DEFAULT_BEFORE_EACH_METHOD_TIMEOUT_PROPERTY_NAME = "junit.jupiter.execution.timeout.beforeeach.method.default";
126
    @API(status = STABLE, since = "5.10")
127
    public static final String DEFAULT_AFTER_EACH_METHOD_TIMEOUT_PROPERTY_NAME = "junit.jupiter.execution.timeout.aftereach.method.default";
128
    @API(status = STABLE, since = "5.10")
129
    public static final String DEFAULT_AFTER_ALL_METHOD_TIMEOUT_PROPERTY_NAME = "junit.jupiter.execution.timeout.afterall.method.default";
130
    @API(status = STABLE, since = "5.10")
131
    public static final String TIMEOUT_MODE_PROPERTY_NAME = "junit.jupiter.execution.timeout.mode";
132
    @API(status = MAINTAINED, since = "5.13.3")
133
    public static final String DEFAULT_TIMEOUT_THREAD_MODE_PROPERTY_NAME = "junit.jupiter.execution.timeout.thread.mode.default";
134

135
    // Test Ordering
136
    @API(status = STABLE, since = "5.9")
137
    public static final String DEFAULT_TEST_METHOD_ORDER_PROPERTY_NAME = "junit.jupiter.testmethod.order.default";
138
    @API(status = STABLE, since = "5.9")
139
    public static final String DEFAULT_TEST_CLASS_ORDER_PROPERTY_NAME = "junit.jupiter.testclass.order.default";
140

141
    // Temporary Directory Configuration
142
    @API(status = MAINTAINED, since = "5.13.3")
143
    public static final String DEFAULT_TEMP_DIR_FACTORY_PROPERTY_NAME = "junit.jupiter.tempdir.factory.default";
144
    @Deprecated
145
    @API(status = DEPRECATED, since = "5.8")
146
    public static final String TEMP_DIR_SCOPE_PROPERTY_NAME = "junit.jupiter.tempdir.scope";
147

148
    // AutoCloseable Configuration
149
    @API(status = MAINTAINED, since = "5.13.3")
150
    public static final String CLOSING_STORED_AUTO_CLOSEABLE_ENABLED_PROPERTY_NAME = "junit.jupiter.closing.autoclose.enabled";
151

152
    // Extension Context Configuration
153
    @API(status = MAINTAINED, since = "5.13.3")
154
    public static final String DEFAULT_TEST_CLASS_INSTANCE_CONSTRUCTION_EXTENSION_CONTEXT_SCOPE_PROPERTY_NAME = "junit.jupiter.testclass.instance.construction.extensioncontext.scope.default";
155
}
156
```
157

158
**Usage Examples:**
159

160
Configure parallel execution:
161
```java
162
// Enable parallel execution
163
System.setProperty(Constants.PARALLEL_EXECUTION_ENABLED_PROPERTY_NAME, "true");
164

165
// Set dynamic parallel strategy with custom factor
166
System.setProperty(Constants.PARALLEL_CONFIG_STRATEGY_PROPERTY_NAME, "dynamic");
167
System.setProperty(Constants.PARALLEL_CONFIG_DYNAMIC_FACTOR_PROPERTY_NAME, "2.0");
168
```
169

170
Configure timeouts:
171
```java
172
// Set default timeout for all test methods
173
System.setProperty(Constants.DEFAULT_TEST_METHOD_TIMEOUT_PROPERTY_NAME, "30s");
174

175
// Set timeout for lifecycle methods
176
System.setProperty(Constants.DEFAULT_BEFORE_EACH_METHOD_TIMEOUT_PROPERTY_NAME, "10s");
177
```
178

179
Configure extensions:
180
```java
181
// Enable auto-detection of extensions
182
System.setProperty(Constants.EXTENSIONS_AUTODETECTION_ENABLED_PROPERTY_NAME, "true");
183

184
// Include specific extension patterns
185
System.setProperty(Constants.EXTENSIONS_AUTODETECTION_INCLUDE_PROPERTY_NAME, "org.example.*");
186

187
// Enable thread dump on timeout
188
System.setProperty(Constants.EXTENSIONS_TIMEOUT_THREAD_DUMP_ENABLED_PROPERTY_NAME, "true");
189
```
190

191
## Important Notes
192

193
### Internal Implementation
194
- The actual `JupiterTestEngine` class is marked as `@API(status = INTERNAL)` and should not be used directly
195
- All descriptor, execution, configuration, and extension classes are internal implementation details
196
- The engine is designed to be used through the JUnit Platform service discovery mechanism
197

198
### Service Provider Pattern
199
- The engine provides `org.junit.platform.engine.TestEngine` service
200
- Automatically discovered by the JUnit Platform at runtime
201
- No direct instantiation or method calls required
202

203
### Configuration
204
- All configuration is done through system properties or JUnit Platform configuration parameters
205
- Property names are provided as constants in the `Constants` class
206
- Changes to configuration properties affect the engine's behavior globally