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
```