0
# Quarkus JUnit 5
1

2
Quarkus JUnit 5 is a comprehensive testing extension that provides full JUnit 5 integration for Quarkus applications. It enables developers to write unit tests, integration tests, and native image tests with complete CDI support, dependency injection, mocking capabilities, and application lifecycle management. The extension supports multiple testing modes including in-JVM testing, external artifact testing, and command-line application testing.
3

4
## Package Information
5

6
- **Package Name**: quarkus-junit5
7
- **Package Type**: maven
8
- **Group ID**: io.quarkus
9
- **Artifact ID**: quarkus-junit5
10
- **Language**: Java
11
- **Installation**: Add to Maven dependencies:
12

13
```xml
14
<dependency>
15
    <groupId>io.quarkus</groupId>
16
    <artifactId>quarkus-junit5</artifactId>
17
    <scope>test</scope>
18
</dependency>
19
```
20

21
For Gradle:
22

23
```gradle
24
testImplementation 'io.quarkus:quarkus-junit5'
25
```
26

27
## Core Imports
28

29
```java
30
import io.quarkus.test.junit.QuarkusTest;
31
import io.quarkus.test.junit.QuarkusIntegrationTest;
32
import io.quarkus.test.junit.QuarkusMock;
33
import io.quarkus.test.junit.TestProfile;
34
import io.quarkus.test.junit.QuarkusTestProfile;
35
```
36

37
For main method testing:
38

39
```java
40
import io.quarkus.test.junit.main.QuarkusMainTest;
41
import io.quarkus.test.junit.main.QuarkusMainIntegrationTest;
42
import io.quarkus.test.junit.main.Launch;
43
import io.quarkus.test.junit.main.QuarkusMainLauncher;
44
import io.quarkus.test.junit.main.LaunchResult;
45
```
46

47
For conditional testing:
48

49
```java
50
import io.quarkus.test.junit.DisabledOnIntegrationTest;
51
import io.quarkus.test.junit.DisableIfBuiltWithGraalVMNewerThan;
52
import io.quarkus.test.junit.DisableIfBuiltWithGraalVMOlderThan;
53
import io.quarkus.test.junit.GraalVMVersion;
54
```
55

56
For test callbacks:
57

58
```java
59
import io.quarkus.test.junit.callback.QuarkusTestBeforeEachCallback;
60
import io.quarkus.test.junit.callback.QuarkusTestAfterEachCallback;
61
import io.quarkus.test.junit.callback.QuarkusTestAfterAllCallback;
62
import io.quarkus.test.junit.callback.QuarkusTestContext;
63
import io.quarkus.test.junit.callback.QuarkusTestMethodContext;
64
```
65

66
## Basic Usage
67

68
### Unit Testing with CDI Injection
69

70
```java
71
import io.quarkus.test.junit.QuarkusTest;
72
import jakarta.inject.Inject;
73
import org.junit.jupiter.api.Test;
74

75
@QuarkusTest
76
class UserServiceTest {
77
    
78
    @Inject
79
    UserService userService;
80
    
81
    @Test
82
    void testCreateUser() {
83
        User user = userService.createUser("John", "john@example.com");
84
        assertEquals("John", user.getName());
85
    }
86
}
87
```
88

89
### Integration Testing
90

91
```java
92
import io.quarkus.test.junit.QuarkusIntegrationTest;
93
import org.junit.jupiter.api.Test;
94

95
@QuarkusIntegrationTest
96
class UserServiceIntegrationTest {
97
    
98
    @Test
99
    void testUserEndpoint() {
100
        // Test against built JAR/native image/container
101
        given()
102
            .when().get("/users")
103
            .then()
104
            .statusCode(200);
105
    }
106
}
107
```
108

109
### Mocking CDI Beans
110

111
```java
112
import io.quarkus.test.junit.QuarkusTest;
113
import io.quarkus.test.junit.QuarkusMock;
114
import jakarta.inject.Inject;
115
import org.junit.jupiter.api.BeforeEach;
116
import org.junit.jupiter.api.Test;
117
import org.mockito.Mockito;
118

119
@QuarkusTest 
120
class UserServiceWithMockTest {
121
    
122
    @Inject
123
    UserService userService;
124
    
125
    @Inject 
126
    UserRepository userRepository;
127
    
128
    @BeforeEach
129
    void setup() {
130
        UserRepository mockRepo = Mockito.mock(UserRepository.class);
131
        QuarkusMock.installMockForInstance(mockRepo, userRepository);
132
    }
133
    
134
    @Test
135
    void testWithMock() {
136
        // Test with mocked repository
137
    }
138
}
139
```
140

141
## Architecture
142

143
Quarkus JUnit 5 is built around several key components:
144

145
- **Test Extensions**: JUnit 5 extensions that manage Quarkus application lifecycle during tests
146
- **Annotation System**: Declarative annotations for different testing modes and configurations
147
- **CDI Integration**: Full dependency injection support in test classes
148
- **Mock Support**: Runtime bean replacement for testing isolation
149
- **Profile System**: Test-specific configuration and bean management
150
- **Launcher Providers**: Support for testing different artifact types (JAR, native, container)
151
- **Callback System**: Service provider interfaces for test lifecycle customization
152

153
## Capabilities
154

155
### Core Test Annotations
156

157
Primary annotations for different testing modes including unit tests with CDI injection, integration tests against built artifacts, and main method testing.
158

159
```java { .api }
160
@Target(ElementType.TYPE)
161
@Retention(RetentionPolicy.RUNTIME)
162
@ExtendWith(QuarkusTestExtension.class)
163
public @interface QuarkusTest {
164
}
165

166
@Target(ElementType.TYPE)
167
@Retention(RetentionPolicy.RUNTIME)
168
@ExtendWith({DisabledOnIntegrationTestCondition.class, QuarkusIntegrationTestExtension.class})
169
public @interface QuarkusIntegrationTest {
170
    @Deprecated
171
    interface Context extends DevServicesContext {
172
    }
173
}
174
```
175

176
[Core Testing](./core-testing.md)
177

178
### Test Configuration and Profiles
179

180
Test profile system for managing different configurations, CDI alternatives, and test resources across different test scenarios.
181

182
```java { .api }
183
@Target(ElementType.TYPE)
184
@Retention(RetentionPolicy.RUNTIME)
185
public @interface TestProfile {
186
    Class<? extends QuarkusTestProfile> value();
187
}
188

189
public interface QuarkusTestProfile {
190
    default Map<String, String> getConfigOverrides() { return Collections.emptyMap(); }
191
    default Set<Class<?>> getEnabledAlternatives() { return Collections.emptySet(); }
192
    default String getConfigProfile() { return null; }
193
    default List<TestResourceEntry> testResources() { return Collections.emptyList(); }
194
    default boolean disableGlobalTestResources() { return false; }
195
    default Set<String> tags() { return Collections.emptySet(); }
196
    default String[] commandLineParameters() { return new String[0]; }
197
    default boolean runMainMethod() { return false; }
198
    default boolean disableApplicationLifecycleObservers() { return false; }
199
}
200
```
201

202
[Test Profiles](./test-profiles.md)
203

204
### Mocking and Bean Replacement
205

206
Runtime mock installation for CDI normal scoped beans, supporting both instance-based and type-based mocking with qualifier support.
207

208
```java { .api }
209
public class QuarkusMock {
210
    public static <T> void installMockForInstance(T mock, T instance);
211
    public static <T> void installMockForType(T mock, Class<? super T> instance, Annotation... qualifiers);
212
    public static <T> void installMockForType(T mock, TypeLiteral<? super T> typeLiteral, Annotation... qualifiers);
213
}
214
```
215

216
[Mocking Support](./mocking.md)
217

218
### Main Method Testing
219

220
Testing framework for command-line applications with support for parameter passing, exit code validation, and output capture.
221

222
```java { .api }
223
@Target(ElementType.TYPE)
224
@Retention(RetentionPolicy.RUNTIME)
225
@ExtendWith(QuarkusMainTestExtension.class)
226
public @interface QuarkusMainTest {
227
}
228

229
@Target(ElementType.TYPE)
230
@Retention(RetentionPolicy.RUNTIME)
231
@ExtendWith(QuarkusMainIntegrationTestExtension.class)
232
public @interface QuarkusMainIntegrationTest {
233
}
234

235
@Target(ElementType.METHOD)
236
@Retention(RetentionPolicy.RUNTIME)
237
public @interface Launch {
238
    String[] value() default "";
239
    int exitCode() default 0;
240
}
241

242
public interface QuarkusMainLauncher {
243
    LaunchResult launch(String... args);
244
}
245
```
246

247
[Main Method Testing](./main-method-testing.md)
248

249
### Conditional Test Execution
250

251
Annotations for conditionally enabling or disabling tests based on integration test mode, GraalVM versions, and artifact types.
252

253
```java { .api }
254
@Target({ElementType.TYPE, ElementType.METHOD})
255
@Retention(RetentionPolicy.RUNTIME)
256
public @interface DisabledOnIntegrationTest {
257
    String value() default "";
258
    ArtifactType[] forArtifactTypes() default {ArtifactType.ALL};
259
    
260
    enum ArtifactType {
261
        ALL, JAR, CONTAINER, NATIVE_BINARY
262
    }
263
}
264

265
@Target({ElementType.TYPE, ElementType.METHOD})
266
@Retention(RetentionPolicy.RUNTIME)
267
@ExtendWith(DisableIfBuiltWithGraalVMNewerThanCondition.class)
268
public @interface DisableIfBuiltWithGraalVMNewerThan {
269
    GraalVMVersion value();
270
}
271

272
@Target({ElementType.TYPE, ElementType.METHOD})
273
@Retention(RetentionPolicy.RUNTIME)
274
@ExtendWith(DisableIfBuiltWithGraalVMOlderThanCondition.class)
275
public @interface DisableIfBuiltWithGraalVMOlderThan {
276
    GraalVMVersion value();
277
}
278
```
279

280
[Conditional Testing](./conditional-testing.md)
281

282
### Test Lifecycle Callbacks
283

284
Service provider interfaces for customizing test execution lifecycle with callbacks for various test phases including construction, setup, execution, and teardown.
285

286
```java { .api }
287
public interface QuarkusTestBeforeEachCallback {
288
    void beforeEach(QuarkusTestMethodContext context);
289
}
290

291
public interface QuarkusTestAfterEachCallback {
292
    void afterEach(QuarkusTestMethodContext context);
293
}
294

295
public interface QuarkusTestAfterAllCallback {
296
    void afterAll(QuarkusTestContext context);
297
}
298

299
public interface QuarkusTestBeforeClassCallback {
300
    void beforeClass(Class<?> testClass);
301
}
302

303
public interface QuarkusTestAfterConstructCallback {
304
    void afterConstruct(Object testInstance);
305
}
306

307
public interface QuarkusTestBeforeTestExecutionCallback {
308
    void beforeTestExecution(QuarkusTestMethodContext context);
309
}
310

311
public interface QuarkusTestAfterTestExecutionCallback {
312
    void afterTestExecution(QuarkusTestMethodContext context);
313
}
314
```
315

316
[Test Callbacks](./test-callbacks.md)
317

318
## Types
319

320
### Core Test Context Types
321

322
```java { .api }
323
// Package: io.quarkus.test.junit.callback
324
public class QuarkusTestContext {
325
    public Object getTestInstance();
326
    public List<Object> getOuterInstances();
327
    public TestStatus getTestStatus();
328
}
329

330
public final class QuarkusTestMethodContext extends QuarkusTestContext {
331
    public Method getTestMethod();
332
}
333
```
334

335
### Launch Result Types
336

337
```java { .api }
338
public interface LaunchResult {
339
    default String getOutput() { return String.join("\n", getOutputStream()); }
340
    default String getErrorOutput() { return String.join("\n", getErrorStream()); }
341
    default void echoSystemOut() { System.out.println(getOutput()); }
342
    List<String> getOutputStream();
343
    List<String> getErrorStream();
344
    int exitCode();
345
}
346
```
347

348
### Test Resource Configuration
349

350
```java { .api }
351
// Inner class of QuarkusTestProfile
352
public static final class TestResourceEntry {
353
    public TestResourceEntry(Class<? extends QuarkusTestResourceLifecycleManager> clazz);
354
    public TestResourceEntry(Class<? extends QuarkusTestResourceLifecycleManager> clazz, Map<String, String> args);
355
    public TestResourceEntry(Class<? extends QuarkusTestResourceLifecycleManager> clazz, Map<String, String> args, boolean parallel);
356
    
357
    public Class<? extends QuarkusTestResourceLifecycleManager> getClazz();
358
    public Map<String, String> getArgs();
359
    public boolean isParallel();
360
}
361
```
362

363
### GraalVM Version Enumeration
364

365
```java { .api }
366
public enum GraalVMVersion {
367
    GRAALVM_23_1_0, GRAALVM_24_0_0, GRAALVM_24_0_999, 
368
    GRAALVM_24_1_0, GRAALVM_24_1_999, GRAALVM_24_2_0;
369
    
370
    public GraalVM.Version getVersion();
371
    public String toString();
372
}
373
```