0
# Unit Testing
1
2
The `QuarkusUnitTest` class is the main JUnit 5 extension for testing Quarkus internals and extensions. It provides comprehensive support for build customization, dependency management, configuration override, and lifecycle management.
3
4
## Core API
5
6
### Basic Setup
7
8
```java { .api }
9
public class QuarkusUnitTest implements BeforeAllCallback, AfterAllCallback,
10
BeforeEachCallback, AfterEachCallback, ParameterResolver, InvocationInterceptor {
11
12
public QuarkusUnitTest();
13
public static QuarkusUnitTest withSecuredConnection();
14
}
15
```
16
17
### Archive Configuration
18
19
Configure the application archive for testing:
20
21
```java { .api }
22
public Supplier<JavaArchive> getArchiveProducer();
23
public QuarkusUnitTest setArchiveProducer(Supplier<JavaArchive> archiveProducer);
24
public QuarkusUnitTest withApplicationRoot(Consumer<JavaArchive> applicationRootConsumer);
25
public QuarkusUnitTest withEmptyApplication();
26
```
27
28
### Exception Handling
29
30
Configure expected exceptions and assertion handling:
31
32
```java { .api }
33
public QuarkusUnitTest setExpectedException(Class<? extends Throwable> expectedException);
34
public QuarkusUnitTest setExpectedException(Class<? extends Throwable> expectedException, boolean logMessage);
35
public QuarkusUnitTest assertException(Consumer<Throwable> assertException);
36
```
37
38
### Dependencies Management
39
40
Add and manage additional dependencies:
41
42
```java { .api }
43
public QuarkusUnitTest addAdditionalDependency(JavaArchive archive);
44
public QuarkusUnitTest withAdditionalDependency(Consumer<JavaArchive> dependencyConsumer);
45
public QuarkusUnitTest setForcedDependencies(List<Dependency> forcedDependencies);
46
```
47
48
### Build Customization
49
50
Customize the build process and add listeners:
51
52
```java { .api }
53
public QuarkusUnitTest addBuildChainCustomizer(Consumer<BuildChainBuilder> customizer);
54
public QuarkusUnitTest addClassLoaderEventListener(ClassLoaderEventListener listener);
55
public QuarkusUnitTest addBootstrapCustomizer(Consumer<QuarkusBootstrap.Builder> consumer);
56
```
57
58
### Configuration Management
59
60
Override configuration keys and provide configuration resources:
61
62
```java { .api }
63
public QuarkusUnitTest withConfigurationResource(String resourceName);
64
public QuarkusUnitTest overrideConfigKey(String key, String value);
65
public QuarkusUnitTest overrideRuntimeConfigKey(String key, String value);
66
```
67
68
### Logging Configuration
69
70
Configure logging behavior and record handling:
71
72
```java { .api }
73
public QuarkusUnitTest setLogFileName(String logFileName);
74
public QuarkusUnitTest setLogRecordPredicate(Predicate<LogRecord> predicate);
75
public QuarkusUnitTest assertLogRecords(Consumer<List<LogRecord>> asserter);
76
```
77
78
### Command Line Parameters
79
80
Handle command line arguments:
81
82
```java { .api }
83
public String[] getCommandLineParameters();
84
public QuarkusUnitTest setCommandLineParameters(String... commandLineParameters);
85
```
86
87
### Debug Features
88
89
Enable debugging and tracing capabilities:
90
91
```java { .api }
92
public QuarkusUnitTest debugBytecode(boolean debugBytecode);
93
public QuarkusUnitTest traceCategories(String... categories);
94
```
95
96
### Lifecycle Customization
97
98
Customize before/after behavior:
99
100
```java { .api }
101
public QuarkusUnitTest setBeforeAllCustomizer(Runnable beforeAllCustomizer);
102
public QuarkusUnitTest setAfterAllCustomizer(Runnable afterAllCustomizer);
103
public Runnable getAfterUndeployListener();
104
public QuarkusUnitTest setAfterUndeployListener(Runnable afterUndeployListener);
105
```
106
107
### Test Behavior Configuration
108
109
Configure test execution behavior:
110
111
```java { .api }
112
public QuarkusUnitTest setAllowTestClassOutsideDeployment(boolean allowTestClassOutsideDeployment);
113
public QuarkusUnitTest setFlatClassPath(boolean flatClassPath);
114
```
115
116
## Usage Examples
117
118
### Basic Test Setup
119
120
```java
121
import io.quarkus.test.QuarkusUnitTest;
122
import org.jboss.shrinkwrap.api.ShrinkWrap;
123
import org.jboss.shrinkwrap.api.spec.JavaArchive;
124
import org.junit.jupiter.api.extension.RegisterExtension;
125
import org.junit.jupiter.api.Test;
126
127
public class BasicUnitTest {
128
129
@RegisterExtension
130
static final QuarkusUnitTest config = new QuarkusUnitTest()
131
.setArchiveProducer(() -> ShrinkWrap.create(JavaArchive.class)
132
.addClasses(MyService.class, MyConfiguration.class));
133
134
@Test
135
public void testBasicFunctionality() {
136
// Test implementation
137
}
138
}
139
```
140
141
### Test with Configuration Override
142
143
```java
144
@RegisterExtension
145
static final QuarkusUnitTest config = new QuarkusUnitTest()
146
.withApplicationRoot(jar -> jar.addClasses(MyService.class))
147
.overrideConfigKey("my.property", "test-value")
148
.withConfigurationResource("test-application.properties");
149
```
150
151
### Test with Exception Handling
152
153
```java
154
@RegisterExtension
155
static final QuarkusUnitTest config = new QuarkusUnitTest()
156
.withApplicationRoot(jar -> jar.addClasses(FailingService.class))
157
.setExpectedException(RuntimeException.class)
158
.assertException(t -> {
159
assertTrue(t.getMessage().contains("Expected failure"));
160
});
161
```
162
163
### Test with Additional Dependencies
164
165
```java
166
@RegisterExtension
167
static final QuarkusUnitTest config = new QuarkusUnitTest()
168
.withApplicationRoot(jar -> jar.addClasses(MyService.class))
169
.addAdditionalDependency(ShrinkWrap.create(JavaArchive.class)
170
.addClasses(AdditionalTestClass.class));
171
```
172
173
### Test with Build Chain Customization
174
175
```java
176
@RegisterExtension
177
static final QuarkusUnitTest config = new QuarkusUnitTest()
178
.withApplicationRoot(jar -> jar.addClasses(MyService.class))
179
.addBuildChainCustomizer(builder -> {
180
// Custom build chain logic
181
builder.addBuildStep(new MyBuildStep());
182
});
183
```
184
185
### Test with Logging Assertions
186
187
```java
188
@RegisterExtension
189
static final QuarkusUnitTest config = new QuarkusUnitTest()
190
.withApplicationRoot(jar -> jar.addClasses(LoggingService.class))
191
.assertLogRecords(logRecords -> {
192
assertTrue(logRecords.stream()
193
.anyMatch(record -> record.getMessage().contains("Expected log message")));
194
});
195
```
196
197
## Constants
198
199
```java { .api }
200
public static final String THE_BUILD_WAS_EXPECTED_TO_FAIL = "The build was expected to fail";
201
```
202
203
This constant is used internally for build failure messaging and can be referenced in test assertions.