0
# Quarkus Test Common
1
2
Common test utilities and framework for Quarkus applications, providing core testing infrastructure including application launchers, test isolation, configuration management, and integration with REST Assured for HTTP testing. This library serves as the foundational layer for the Quarkus test framework ecosystem, enabling comprehensive testing of Quarkus applications across different deployment modes and runtime environments.
3
4
## Package Information
5
6
- **Package Name**: quarkus-test-common
7
- **Package Type**: maven
8
- **Group ID**: io.quarkus
9
- **Language**: Java
10
- **Installation**:
11
```xml
12
<dependency>
13
<groupId>io.quarkus</groupId>
14
<artifactId>quarkus-test-common</artifactId>
15
<version>3.26.2</version>
16
<scope>test</scope>
17
</dependency>
18
```
19
20
## Core Imports
21
22
```java
23
import io.quarkus.test.common.QuarkusTestResource;
24
import io.quarkus.test.common.QuarkusTestResourceLifecycleManager;
25
import io.quarkus.test.common.http.TestHTTPResource;
26
import io.quarkus.test.common.http.TestHTTPEndpoint;
27
```
28
29
Common test annotations:
30
31
```java
32
import io.quarkus.test.Mock;
33
import io.quarkus.test.InjectMock;
34
import io.quarkus.test.TestTransaction;
35
import io.quarkus.test.TestReactiveTransaction;
36
import io.quarkus.test.ActivateSessionContext;
37
import io.quarkus.test.common.WithTestResource;
38
import io.quarkus.test.common.TestResourceScope;
39
```
40
41
## Basic Usage
42
43
```java
44
import io.quarkus.test.common.QuarkusTestResource;
45
import io.quarkus.test.common.QuarkusTestResourceLifecycleManager;
46
import io.quarkus.test.common.http.TestHTTPResource;
47
import io.quarkus.test.Mock;
48
import io.quarkus.test.InjectMock;
49
import org.junit.jupiter.api.Test;
50
51
// Define a test resource for external dependencies
52
@QuarkusTestResource(DatabaseTestResource.class)
53
public class MyServiceTest {
54
55
@TestHTTPResource("/api/users")
56
URL usersEndpoint;
57
58
@InjectMock
59
MyService mockService;
60
61
@Test
62
public void testUserEndpoint() {
63
// Test implementation using injected HTTP resource and mock
64
// The database test resource is automatically managed
65
}
66
}
67
68
// Example test resource implementation
69
public class DatabaseTestResource implements QuarkusTestResourceLifecycleManager {
70
@Override
71
public Map<String, String> start() {
72
// Start test database container
73
return Map.of("quarkus.datasource.jdbc.url", "jdbc:testcontainers:postgresql://...");
74
}
75
76
@Override
77
public void stop() {
78
// Clean up resources
79
}
80
}
81
```
82
83
## Architecture
84
85
The Quarkus test framework is built around several key components:
86
87
- **Test Resource Management**: Sophisticated lifecycle management for external dependencies (databases, message brokers, etc.) with scoping control
88
- **HTTP Testing Support**: Automatic URL injection and endpoint configuration for REST API testing
89
- **Test Annotations**: Core annotations for mocking, transactions, and session context management
90
- **Launcher Infrastructure**: Support for testing different artifact types (JVM, native, container)
91
- **Utility Classes**: Helper classes for path mapping, system properties, and test context management
92
93
This design enables comprehensive testing of Quarkus applications with automatic resource management, simplified HTTP endpoint testing, and support for various runtime environments including native compilation and containerized deployments.
94
95
## Capabilities
96
97
### Test Resource Management
98
99
Comprehensive lifecycle management for external test dependencies like databases, message brokers, and external services. Supports sophisticated scoping strategies and parallel resource startup.
100
101
```java { .api }
102
@Target(ElementType.TYPE)
103
@Retention(RetentionPolicy.RUNTIME)
104
@Repeatable(QuarkusTestResource.List.class)
105
public @interface QuarkusTestResource {
106
Class<? extends QuarkusTestResourceLifecycleManager> value();
107
ResourceArg[] initArgs() default {};
108
boolean parallel() default false;
109
boolean restrictToAnnotatedClass() default false;
110
}
111
112
@Target(ElementType.TYPE)
113
@Retention(RetentionPolicy.RUNTIME)
114
@Repeatable(WithTestResource.List.class)
115
public @interface WithTestResource {
116
Class<? extends QuarkusTestResourceLifecycleManager> value();
117
ResourceArg[] initArgs() default {};
118
boolean parallel() default false;
119
TestResourceScope scope() default TestResourceScope.MATCHING_RESOURCES;
120
}
121
122
public enum TestResourceScope {
123
RESTRICTED_TO_CLASS, // Complete isolation, restart for each test
124
MATCHING_RESOURCES, // Restart only when resources differ
125
GLOBAL // Apply to all tests in suite
126
}
127
128
public interface QuarkusTestResourceLifecycleManager {
129
Map<String, String> start();
130
void stop();
131
default void setContext(Context context) {}
132
default void init(Map<String, String> initArgs) {}
133
default void inject(Object testInstance) {}
134
default void inject(TestInjector testInjector) {}
135
default int order() { return 0; }
136
}
137
```
138
139
[Test Resource Management](./test-resources.md)
140
141
### HTTP Testing Support
142
143
Specialized support for HTTP endpoint testing with automatic URL injection and endpoint configuration. Integrates seamlessly with REST Assured and other HTTP testing libraries.
144
145
```java { .api }
146
@Target({ElementType.FIELD})
147
@Retention(RetentionPolicy.RUNTIME)
148
public @interface TestHTTPResource {
149
String value() default "";
150
@Deprecated(since = "3.10", forRemoval = true)
151
boolean ssl() default false;
152
boolean tls() default false;
153
boolean management() default false;
154
}
155
156
@Target({ElementType.TYPE, ElementType.METHOD, ElementType.FIELD})
157
@Retention(RetentionPolicy.RUNTIME)
158
public @interface TestHTTPEndpoint {
159
Class<?> value();
160
}
161
```
162
163
[HTTP Testing](./http-testing.md)
164
165
### Core Test Annotations
166
167
Essential annotations for mocking, transaction management, and session context control in Quarkus tests.
168
169
```java { .api }
170
@Target({ElementType.TYPE, ElementType.METHOD, ElementType.FIELD})
171
@Retention(RetentionPolicy.RUNTIME)
172
@Stereotype
173
public @interface Mock {}
174
175
@Target({ElementType.FIELD, ElementType.PARAMETER})
176
@Retention(RetentionPolicy.RUNTIME)
177
public @interface InjectMock {}
178
179
@Target({ElementType.METHOD})
180
@Retention(RetentionPolicy.RUNTIME)
181
@InterceptorBinding
182
public @interface TestTransaction {}
183
184
@Target({ElementType.METHOD})
185
@Retention(RetentionPolicy.RUNTIME)
186
@InterceptorBinding
187
public @interface TestReactiveTransaction {}
188
189
@Target({ElementType.METHOD})
190
@Retention(RetentionPolicy.RUNTIME)
191
@InterceptorBinding
192
public @interface ActivateSessionContext {}
193
```
194
195
[Test Annotations](./test-annotations.md)
196
197
### Launcher Infrastructure
198
199
Interfaces and implementations for launching and managing different types of Quarkus artifacts during testing, including JVM, native, and containerized deployments.
200
201
```java { .api }
202
public interface ArtifactLauncher<T> extends Closeable {
203
void init(T initContext);
204
void start() throws IOException;
205
LaunchResult runToCompletion(String[] args);
206
void includeAsSysProps(Map<String, String> systemProps);
207
boolean listensOnSsl();
208
void close() throws IOException;
209
}
210
211
public static class LaunchResult {
212
public LaunchResult(int statusCode, byte[] output, byte[] stderror) {}
213
public int getStatusCode() {}
214
public byte[] getOutput() {}
215
public byte[] getStderror() {}
216
}
217
```
218
219
[Launcher Infrastructure](./launchers.md)
220
221
### Test Context and Status
222
223
Access to test execution context, Dev Services properties, and test failure status for advanced test scenarios and resource cleanup.
224
225
```java { .api }
226
public class TestStatus {
227
public TestStatus(Throwable testErrorCause) {}
228
public Throwable getTestErrorCause() {}
229
public boolean isTestFailed() {}
230
}
231
232
public interface DevServicesContext {
233
Map<String, String> devServicesProperties();
234
Optional<String> containerNetworkId();
235
}
236
```
237
238
[Test Context](./test-context.md)
239
240
### Utilities
241
242
Helper classes for common testing scenarios including path mapping, system property management, and annotation processing.
243
244
```java { .api }
245
public class RestorableSystemProperties implements Closeable {
246
public static RestorableSystemProperties setProperties(
247
Map<String, String> props,
248
String... additionalKeysToSave
249
) {}
250
public void close() {}
251
}
252
253
public class PathTestHelper {
254
public static Path getTestClassesLocation(Class<?> testClass) {}
255
public static Path getAppClassLocationForTestLocation(Path testClassLocationPath) {}
256
public static boolean isTestClass(String className, ClassLoader classLoader, Path testLocation) {}
257
}
258
```
259
260
[Utilities](./utilities.md)
261
262
## Types
263
264
```java { .api }
265
@Target(ElementType.TYPE)
266
@Retention(RetentionPolicy.RUNTIME)
267
public @interface ResourceArg {
268
String name();
269
String value();
270
}
271
272
public enum TestResourceScope {
273
RESTRICTED_TO_CLASS,
274
MATCHING_RESOURCES,
275
GLOBAL
276
}
277
278
public class ListeningAddress {
279
public ListeningAddress(Integer port, String protocol) {}
280
public Integer getPort() {}
281
public String getProtocol() {}
282
public boolean isSsl() {}
283
}
284
```