0
# JUnit Jupiter API
1
2
JUnit Jupiter API is the core testing framework for Java applications, providing comprehensive annotations, assertions, and test lifecycle management. It offers modern testing capabilities including conditional execution, parameterized tests, parallel execution, and an extensible architecture through its Extension Model.
3
4
## Package Information
5
6
- **Package Name**: junit-jupiter-api
7
- **Package Type**: maven
8
- **Language**: Java
9
- **Installation**: `<dependency><groupId>org.junit.jupiter</groupId><artifactId>junit-jupiter-api</artifactId><version>5.12.2</version></dependency>`
10
- **Module**: org.junit.jupiter.api
11
12
## Core Imports
13
14
```java
15
import org.junit.jupiter.api.*;
16
import static org.junit.jupiter.api.Assertions.*;
17
```
18
19
For specific functionality:
20
21
```java
22
// Core test annotations
23
import org.junit.jupiter.api.Test;
24
import org.junit.jupiter.api.BeforeEach;
25
import org.junit.jupiter.api.AfterEach;
26
import org.junit.jupiter.api.BeforeAll;
27
import org.junit.jupiter.api.AfterAll;
28
29
// Assertions and assumptions
30
import org.junit.jupiter.api.Assertions;
31
import org.junit.jupiter.api.Assumptions;
32
33
// Conditional execution
34
import org.junit.jupiter.api.condition.EnabledOnOs;
35
import org.junit.jupiter.api.condition.DisabledOnOs;
36
37
// Extensions
38
import org.junit.jupiter.api.extension.ExtendWith;
39
```
40
41
## Basic Usage
42
43
```java
44
import org.junit.jupiter.api.*;
45
import static org.junit.jupiter.api.Assertions.*;
46
47
class CalculatorTest {
48
49
private Calculator calculator;
50
51
@BeforeEach
52
void setUp() {
53
calculator = new Calculator();
54
}
55
56
@Test
57
@DisplayName("Addition of two positive numbers")
58
void testAddition() {
59
int result = calculator.add(2, 3);
60
assertEquals(5, result, "2 + 3 should equal 5");
61
}
62
63
@Test
64
void testDivisionByZero() {
65
assertThrows(ArithmeticException.class, () -> {
66
calculator.divide(10, 0);
67
}, "Division by zero should throw ArithmeticException");
68
}
69
70
@AfterEach
71
void tearDown() {
72
calculator = null;
73
}
74
}
75
```
76
77
## Architecture
78
79
JUnit Jupiter API is built around several key components:
80
81
- **Annotation-Driven Testing**: Core annotations (@Test, @BeforeEach, etc.) for declarative test configuration
82
- **Assertion Engine**: Static methods in Assertions class for comprehensive test validation
83
- **Lifecycle Management**: Hooks for test setup and teardown at method and class levels
84
- **Extension Framework**: Pluggable architecture for custom test behavior and integrations
85
- **Conditional Execution**: Runtime environment-based test enabling/disabling
86
- **Parallel Execution**: Thread-safe test execution with resource management
87
- **Module System**: Java 9+ module support with exported packages
88
89
## Capabilities
90
91
### Core Testing Framework
92
93
Essential testing annotations, assertions, and lifecycle management for writing Java tests. Provides the foundation for all JUnit Jupiter testing scenarios.
94
95
```java { .api }
96
// Core test lifecycle annotations
97
@Test
98
@BeforeEach
99
@AfterEach
100
@BeforeAll
101
@AfterAll
102
103
// Test organization and metadata
104
@DisplayName(String value)
105
@Disabled(String value)
106
@Tag(String value)
107
@Nested
108
```
109
110
```java { .api }
111
import java.time.Duration;
112
import org.junit.jupiter.api.function.Executable;
113
114
// Core assertions (static methods in Assertions class)
115
static void assertTrue(boolean condition);
116
static void assertTrue(boolean condition, String message);
117
static void assertFalse(boolean condition);
118
static void assertEquals(Object expected, Object actual);
119
static void assertNotEquals(Object unexpected, Object actual);
120
static <T extends Throwable> T assertThrows(Class<T> expectedType, Executable executable);
121
static void assertTimeout(Duration timeout, Executable executable);
122
static void assertAll(Executable... executables);
123
```
124
125
[Core Testing Framework](./core-testing.md)
126
127
### Conditional Test Execution
128
129
Runtime environment-based test control for platform-specific, JRE-specific, and custom conditional testing scenarios.
130
131
```java { .api }
132
// Operating system conditions
133
@EnabledOnOs(OS.LINUX)
134
@DisabledOnOs({OS.WINDOWS, OS.MAC})
135
136
// JRE version conditions
137
@EnabledOnJre(JRE.JAVA_11)
138
@EnabledForJreRange(min = JRE.JAVA_8, max = JRE.JAVA_17)
139
140
// System properties and environment variables
141
@EnabledIfSystemProperty(named = "os.arch", matches = ".*64.*")
142
@EnabledIfEnvironmentVariable(named = "ENV", matches = "ci")
143
144
// Custom method conditions
145
@EnabledIf("customCondition")
146
@DisabledIf("customCondition")
147
```
148
149
[Conditional Execution](./conditional-execution.md)
150
151
### Extension Framework
152
153
Comprehensive extension system for custom test behavior, dependency injection, lifecycle callbacks, and test monitoring.
154
155
```java { .api }
156
// Extension registration
157
@ExtendWith(MyExtension.class)
158
@RegisterExtension
159
static final MyExtension extension = new MyExtension();
160
161
// Core extension interfaces
162
interface Extension { }
163
interface BeforeAllCallback extends Extension {
164
void beforeAll(ExtensionContext context);
165
}
166
interface ParameterResolver extends Extension {
167
boolean supportsParameter(ParameterContext parameterContext, ExtensionContext extensionContext);
168
Object resolveParameter(ParameterContext parameterContext, ExtensionContext extensionContext);
169
}
170
171
// Extension context
172
interface ExtensionContext {
173
Optional<ExtensionContext> getParent();
174
String getDisplayName();
175
Set<String> getTags();
176
Store getStore(Namespace namespace);
177
}
178
```
179
180
[Extension Framework](./extension-framework.md)
181
182
### Parallel Execution and I/O Support
183
184
Thread-safe test execution with resource management, temporary directory support, and execution control annotations.
185
186
```java { .api }
187
// Parallel execution control
188
@Execution(ExecutionMode.CONCURRENT)
189
@Execution(ExecutionMode.SAME_THREAD)
190
@Isolated
191
192
// Resource management
193
@ResourceLock(value = "shared.resource", mode = ResourceAccessMode.READ)
194
@ResourceLock(value = "exclusive.resource", mode = ResourceAccessMode.READ_WRITE)
195
196
// Temporary directory support
197
@TempDir
198
Path tempDirectory;
199
200
@TempDir(cleanup = CleanupMode.ALWAYS)
201
File tempDir;
202
```
203
204
[Parallel Execution and I/O Support](./parallel-io.md)
205
206
## Types
207
208
### Core Interfaces
209
210
```java { .api }
211
interface TestInfo {
212
String getDisplayName();
213
Set<String> getTags();
214
Optional<Class<?>> getTestClass();
215
Optional<Method> getTestMethod();
216
}
217
218
interface TestReporter {
219
void publishEntry(Map<String, String> map);
220
void publishEntry(String key, String value);
221
}
222
223
interface RepetitionInfo {
224
int getCurrentRepetition();
225
int getTotalRepetitions();
226
}
227
```
228
229
### Functional Interfaces
230
231
```java { .api }
232
@FunctionalInterface
233
interface Executable {
234
void execute() throws Throwable;
235
}
236
237
@FunctionalInterface
238
interface ThrowingSupplier<T> {
239
T get() throws Throwable;
240
}
241
242
@FunctionalInterface
243
interface ThrowingConsumer<T> {
244
void accept(T t) throws Throwable;
245
}
246
```
247
248
### Enums
249
250
```java { .api }
251
enum TestInstance.Lifecycle {
252
PER_METHOD, PER_CLASS
253
}
254
255
enum OS {
256
AIX, FREEBSD, LINUX, MAC, OPENBSD, SOLARIS, WINDOWS, OTHER;
257
258
static OS current();
259
boolean isCurrentOs();
260
}
261
262
enum ExecutionMode {
263
SAME_THREAD, CONCURRENT
264
}
265
266
enum ResourceAccessMode {
267
READ, READ_WRITE
268
}
269
270
enum CleanupMode {
271
DEFAULT, ALWAYS, ON_SUCCESS, NEVER
272
}
273
```