0
# Testing Framework
1

2
Quarkus provides comprehensive testing support with JUnit 5 integration, custom testing annotations, mocking capabilities, and test profiles for different testing scenarios including unit tests, integration tests, and native tests.
3

4
## Core Testing Annotations
5

6
### @QuarkusTest
7

8
```java { .api }
9
@Target(ElementType.TYPE)
10
@Retention(RetentionPolicy.RUNTIME)
11
public @interface QuarkusTest {
12
}
13
```
14

15
Main annotation for Quarkus unit tests. Starts a Quarkus application in test mode with full CDI container and dependency injection support.
16

17
**Usage Example:**
18
```java
19
@QuarkusTest
20
public class UserServiceTest {
21
    
22
    @Inject
23
    UserService userService;
24
    
25
    @Test
26
    public void testCreateUser() {
27
        User user = new User("John", "john@example.com");
28
        User created = userService.create(user);
29
        
30
        assertNotNull(created.getId());
31
        assertEquals("John", created.getName());
32
    }
33
}
34
```
35

36
### @QuarkusIntegrationTest
37

38
```java { .api }
39
@Target(ElementType.TYPE)
40
@Retention(RetentionPolicy.RUNTIME)
41
public @interface QuarkusIntegrationTest {
42
}
43
```
44

45
Annotation for integration tests that run against the packaged application (JAR or native executable).
46

47
**Usage Example:**
48
```java
49
@QuarkusIntegrationTest
50
public class UserResourceIT {
51
    
52
    @Test
53
    public void testGetUser() {
54
        given()
55
            .when().get("/users/1")
56
            .then()
57
                .statusCode(200)
58
                .body("name", equalTo("John Doe"));
59
    }
60
}
61
```
62

63
### @NativeImageTest
64

65
```java { .api }
66
@Target(ElementType.TYPE)
67
@Retention(RetentionPolicy.RUNTIME)
68
public @interface NativeImageTest {
69
}
70
```
71

72
Runs tests against native executable compiled with GraalVM.
73

74
## Test Configuration and Profiles
75

76
### @TestProfile
77

78
```java { .api }
79
@Target(ElementType.TYPE)
80
@Retention(RetentionPolicy.RUNTIME)
81
public @interface TestProfile {
82
    Class<? extends QuarkusTestProfile> value();
83
}
84
```
85

86
Applies a custom test profile to override configuration for specific test classes.
87

88
### QuarkusTestProfile Interface
89

90
```java { .api }
91
public interface QuarkusTestProfile {
92
    Map<String, String> getConfigOverrides();
93
    Set<Class<?>> getEnabledAlternatives();
94
    String getConfigProfile();
95
    List<TestResourceEntry> testResources();
96
    boolean disableGlobalTestResources();
97
    Set<String> tags();
98
    
99
    class TestResourceEntry {
100
        public TestResourceEntry(Class<? extends QuarkusTestResourceLifecycleManager> clazz);
101
        public TestResourceEntry(Class<? extends QuarkusTestResourceLifecycleManager> clazz, 
102
                               Map<String, String> args);
103
    }
104
}
105
```
106

107
Interface for defining custom test profiles with configuration overrides and test resources.
108

109
**Usage Example:**
110
```java
111
public class DatabaseTestProfile implements QuarkusTestProfile {
112
    
113
    @Override
114
    public Map<String, String> getConfigOverrides() {
115
        return Map.of(
116
            "quarkus.datasource.db-kind", "h2",
117
            "quarkus.datasource.jdbc.url", "jdbc:h2:mem:test",
118
            "quarkus.hibernate-orm.database.generation", "drop-and-create"
119
        );
120
    }
121
    
122
    @Override
123
    public String getConfigProfile() {
124
        return "test";
125
    }
126
}
127

128
@QuarkusTest
129
@TestProfile(DatabaseTestProfile.class)
130
public class UserRepositoryTest {
131
    // Tests with H2 in-memory database
132
}
133
```
134

135
## Test Resource Management
136

137
### @QuarkusTestResource
138

139
```java { .api }
140
@Target(ElementType.TYPE)
141
@Retention(RetentionPolicy.RUNTIME)
142
@Repeatable(QuarkusTestResource.List.class)
143
public @interface QuarkusTestResource {
144
    Class<? extends QuarkusTestResourceLifecycleManager> value();
145
    Map<String, String> initArgs() default {};
146
    boolean restrictToAnnotatedClass() default false;
147
    
148
    @Target(ElementType.TYPE)
149
    @Retention(RetentionPolicy.RUNTIME)
150
    @interface List {
151
        QuarkusTestResource[] value();
152
    }
153
}
154
```
155

156
Manages external test resources like databases, message brokers, or containers.
157

158
### QuarkusTestResourceLifecycleManager
159

160
```java { .api }
161
public interface QuarkusTestResourceLifecycleManager {
162
    Map<String, String> start();
163
    void stop();
164
    void inject(TestInjector testInjector);
165
    int order();
166
    
167
    interface TestInjector {
168
        void injectIntoFields(Object testInstance, 
169
                            Map<Class<?>, Function<Class<?>, Object>> valueProducers);
170
    }
171
}
172
```
173

174
Interface for implementing custom test resource lifecycle management.
175

176
**Usage Example:**
177
```java
178
public class PostgreSQLTestResource implements QuarkusTestResourceLifecycleManager {
179
    
180
    private PostgreSQLContainer<?> container;
181
    
182
    @Override
183
    public Map<String, String> start() {
184
        container = new PostgreSQLContainer<>("postgres:13")
185
            .withDatabaseName("testdb")
186
            .withUsername("test")
187
            .withPassword("test");
188
        container.start();
189
        
190
        return Map.of(
191
            "quarkus.datasource.jdbc.url", container.getJdbcUrl(),
192
            "quarkus.datasource.username", container.getUsername(),
193
            "quarkus.datasource.password", container.getPassword()
194
        );
195
    }
196
    
197
    @Override
198
    public void stop() {
199
        if (container != null) {
200
            container.stop();
201
        }
202
    }
203
}
204

205
@QuarkusTest
206
@QuarkusTestResource(PostgreSQLTestResource.class)
207
public class UserRepositoryIT {
208
    // Tests with real PostgreSQL container
209
}
210
```
211

212
## Mocking Support
213

214
### QuarkusMock
215

216
```java { .api }
217
public class QuarkusMock {
218
    public static <T> void installMockForType(T mock, Class<T> type, Annotation... qualifiers);
219
    public static <T> void installMockForInstance(T mock, T instance);
220
    public static void removeMockForType(Class<?> type, Annotation... qualifiers);
221
    public static void removeMockForInstance(Object instance);
222
}
223
```
224

225
Utility class for installing and managing mocks in Quarkus tests.
226

227
**Usage Example:**
228
```java
229
@QuarkusTest
230
public class OrderServiceTest {
231
    
232
    @Mock
233
    PaymentService paymentService;
234
    
235
    @BeforeEach
236
    void setup() {
237
        QuarkusMock.installMockForType(paymentService, PaymentService.class);
238
    }
239
    
240
    @Test
241
    public void testCreateOrder() {
242
        when(paymentService.charge(any(), any())).thenReturn(true);
243
        
244
        Order order = new Order("Product", 100.0);
245
        Order result = orderService.create(order);
246
        
247
        assertNotNull(result);
248
        verify(paymentService).charge(eq(100.0), any());
249
    }
250
}
251
```
252

253
### @InjectMock
254

255
```java { .api }
256
@Target({ElementType.FIELD, ElementType.PARAMETER})
257
@Retention(RetentionPolicy.RUNTIME)
258
public @interface InjectMock {
259
}
260
```
261

262
Automatically creates and injects mocks for CDI beans.
263

264
**Usage Example:**
265
```java
266
@QuarkusTest  
267
public class NotificationServiceTest {
268
    
269
    @InjectMock
270
    EmailService emailService;
271
    
272
    @Inject
273
    NotificationService notificationService;
274
    
275
    @Test
276
    public void testSendNotification() {
277
        notificationService.sendWelcome("user@example.com");
278
        
279
        verify(emailService).send(eq("user@example.com"), contains("Welcome"));
280
    }
281
}
282
```
283

284
## Test Execution Control
285

286
### @DisabledOnIntegrationTest
287

288
```java { .api }
289
@Target({ElementType.TYPE, ElementType.METHOD})
290
@Retention(RetentionPolicy.RUNTIME)
291
public @interface DisabledOnIntegrationTest {
292
}
293
```
294

295
Disables tests when running as integration tests.
296

297
### @EnabledOnIntegrationTest
298

299
```java { .api }
300
@Target({ElementType.TYPE, ElementType.METHOD})
301
@Retention(RetentionPolicy.RUNTIME)
302
public @interface EnabledOnIntegrationTest {
303
}
304
```
305

306
Enables tests only when running as integration tests.
307

308
### @DisabledOnNativeImage
309

310
```java { .api }
311
@Target({ElementType.TYPE, ElementType.METHOD})
312
@Retention(RetentionPolicy.RUNTIME)
313
public @interface DisabledOnNativeImage {
314
}
315
```
316

317
Disables tests when running against native image.
318

319
**Usage Example:**
320
```java
321
@QuarkusTest
322
public class PerformanceTest {
323
    
324
    @Test
325
    @DisabledOnNativeImage  // Skip slow test in native mode
326
    public void testComplexOperation() {
327
        // CPU-intensive test
328
    }
329
    
330
    @Test
331
    @EnabledOnIntegrationTest  // Only run in integration mode
332
    public void testEndToEndWorkflow() {
333
        // Full integration test
334
    }
335
}
336
```
337

338
## HTTP Testing Support
339

340
### TestHTTPEndpoint
341

342
```java { .api }
343
@Target(ElementType.TYPE)
344
@Retention(RetentionPolicy.RUNTIME)
345
public @interface TestHTTPEndpoint {
346
    Class<?> value();
347
}
348
```
349

350
Configures the base URI for REST Assured tests based on a JAX-RS resource class.
351

352
### TestHTTPResource
353

354
```java { .api }
355
@Target({ElementType.FIELD, ElementType.PARAMETER})
356
@Retention(RetentionPolicy.RUNTIME)
357
public @interface TestHTTPResource {
358
    String value() default "";
359
}
360
```
361

362
Injects the URL of HTTP resources for testing.
363

364
**Usage Example:**
365
```java
366
@QuarkusTest
367
@TestHTTPEndpoint(UserResource.class)
368
public class UserResourceTest {
369
    
370
    @TestHTTPResource
371
    URL baseUrl;
372
    
373
    @TestHTTPResource("/{id}")
374
    URL userUrl;
375
    
376
    @Test
377
    public void testGetUser() {
378
        given()
379
            .pathParam("id", 1)
380
            .when().get()
381
            .then()
382
                .statusCode(200)
383
                .body("name", notNullValue());
384
    }
385
}
386
```
387

388
## Security Testing
389

390
### @TestSecurity
391

392
```java { .api }
393
@Target({ElementType.TYPE, ElementType.METHOD})
394
@Retention(RetentionPolicy.RUNTIME)
395
public @interface TestSecurity {
396
    String user() default "";
397
    String[] roles() default {};
398
    String authorizationHeader() default "";
399
}
400
```
401

402
Configures test security context with specified user and roles.
403

404
**Usage Example:**
405
```java
406
@QuarkusTest
407
public class SecureResourceTest {
408
    
409
    @Test
410
    @TestSecurity(user = "admin", roles = {"admin", "user"})
411
    public void testAdminEndpoint() {
412
        given()
413
            .when().get("/admin/users")
414
            .then()
415
                .statusCode(200);
416
    }
417
    
418
    @Test
419
    @TestSecurity(user = "user", roles = {"user"})
420
    public void testUserEndpoint() {
421
        given()
422
            .when().get("/admin/users")
423
            .then()
424
                .statusCode(403);  // Forbidden
425
    }
426
}
427
```
428

429
## Database Testing
430

431
### @TransactionalQuarkusTest
432

433
```java { .api }
434
@Target(ElementType.TYPE)
435
@Retention(RetentionPolicy.RUNTIME)
436
public @interface TransactionalQuarkusTest {
437
}
438
```
439

440
Wraps each test method in a transaction that is rolled back after the test.
441

442
**Usage Example:**
443
```java
444
@TransactionalQuarkusTest
445
public class UserRepositoryTest {
446
    
447
    @Inject
448
    UserRepository repository;
449
    
450
    @Test
451
    public void testCreateUser() {
452
        User user = new User("John", "john@example.com");
453
        repository.persist(user);
454
        
455
        // Transaction will be rolled back after test
456
        assertNotNull(user.getId());
457
    }
458
}
459
```
460

461
## Continuous Testing
462

463
### @ContinuousTest
464

465
```java { .api }
466
@Target({ElementType.TYPE, ElementType.METHOD})
467
@Retention(RetentionPolicy.RUNTIME)
468
public @interface ContinuousTest {
469
}
470
```
471

472
Marks tests to run continuously during development mode.
473

474
### Test Configuration
475

476
```properties
477
# Enable continuous testing
478
quarkus.test.continuous-testing=enabled
479

480
# Include/exclude test tags
481
quarkus.test.include-tags=unit,integration
482
quarkus.test.exclude-tags=slow
483

484
# Disable broken tests
485
quarkus.test.disable-console-input=true
486
```
487

488
Configuration options for continuous testing behavior.