0
# Quarkus JUnit 5 Internal
1

2
An internal JUnit 5 test framework specifically designed for testing the Quarkus framework itself, rather than for end-user consumption. It provides specialized testing utilities, production mode test runners, and integration with Quarkus-specific testing features including build chain management, continuous testing support, and artifact result handling.
3

4
## Package Information
5

6
- **Package Name**: quarkus-junit5-internal
7
- **Group ID**: io.quarkus
8
- **Artifact ID**: quarkus-junit5-internal
9
- **Language**: Java
10
- **Package Manager**: Maven
11
- **Installation**: 
12
  ```xml
13
  <dependency>
14
      <groupId>io.quarkus</groupId>
15
      <artifactId>quarkus-junit5-internal</artifactId>
16
      <version>3.23.0</version>
17
  </dependency>
18
  ```
19

20
## Core Imports
21

22
```java
23
import io.quarkus.test.QuarkusUnitTest;
24
import io.quarkus.test.QuarkusDevModeTest;  
25
import io.quarkus.test.QuarkusProdModeTest;
26
```
27

28
Common annotations:
29

30
```java
31
import io.quarkus.test.LogFile;
32
import io.quarkus.test.ProdBuildResults;
33
```
34

35
Utilities and support classes:
36

37
```java
38
import io.quarkus.test.ClearCache;
39
import io.quarkus.test.LogCollectingTestResource;
40
import io.quarkus.test.ContinuousTestingTestUtils;
41
```
42

43
## Basic Usage
44

45
```java
46
import io.quarkus.test.QuarkusUnitTest;
47
import org.jboss.shrinkwrap.api.ShrinkWrap;
48
import org.jboss.shrinkwrap.api.spec.JavaArchive;
49
import org.junit.jupiter.api.extension.RegisterExtension;
50
import org.junit.jupiter.api.Test;
51

52
public class MyQuarkusTest {
53
    
54
    @RegisterExtension
55
    static final QuarkusUnitTest config = new QuarkusUnitTest()
56
        .setArchiveProducer(() -> ShrinkWrap.create(JavaArchive.class)
57
            .addClasses(MyService.class))
58
        .withConfigurationResource("application-test.properties");
59
    
60
    @Test
61
    public void testSomething() {
62
        // Test Quarkus application functionality
63
    }
64
}
65
```
66

67
## Architecture
68

69
The Quarkus JUnit 5 Internal framework is built around several key components:
70

71
- **Test Extensions**: Three main JUnit 5 extensions (`QuarkusUnitTest`, `QuarkusDevModeTest`, `QuarkusProdModeTest`) that handle different testing scenarios
72
- **Build Chain Integration**: Support for customizing Quarkus build chains during testing via build steps and customizers
73
- **Logging Infrastructure**: Comprehensive logging capture and analysis tools for test verification
74
- **Result Management**: Containers and utilities for managing test execution results and build artifacts
75
- **Lifecycle Management**: Test resource management and cleanup utilities
76

77
## Capabilities
78

79
### Unit Testing
80

81
Core JUnit 5 extension for testing Quarkus internals and extensions with full build customization, dependency management, and configuration override capabilities.
82

83
```java { .api }
84
public class QuarkusUnitTest implements BeforeAllCallback, AfterAllCallback, 
85
    BeforeEachCallback, AfterEachCallback, ParameterResolver, InvocationInterceptor {
86
    
87
    public QuarkusUnitTest();
88
    public static QuarkusUnitTest withSecuredConnection();
89
    
90
    public Supplier<JavaArchive> getArchiveProducer();
91
    public QuarkusUnitTest setArchiveProducer(Supplier<JavaArchive> archiveProducer);
92
    public QuarkusUnitTest withApplicationRoot(Consumer<JavaArchive> applicationRootConsumer);
93
    public QuarkusUnitTest withEmptyApplication();
94
    public QuarkusUnitTest addBuildChainCustomizer(Consumer<BuildChainBuilder> customizer);
95
    public QuarkusUnitTest overrideConfigKey(String key, String value);
96
    public QuarkusUnitTest setExpectedException(Class<? extends Throwable> expectedException);
97
}
98
```
99

100
[Unit Testing](./unit-testing.md)
101

102
### Development Mode Testing
103

104
Test extension for black-box testing of Quarkus development mode with file modification support, hot reload testing, and build system integration.
105

106
```java { .api }
107
public class QuarkusDevModeTest implements BeforeAllCallback, AfterAllCallback, 
108
    BeforeEachCallback, AfterEachCallback, TestInstanceFactory {
109
    
110
    public QuarkusDevModeTest();
111
    
112
    public QuarkusDevModeTest setArchiveProducer(Supplier<JavaArchive> archiveProducer);
113
    public QuarkusDevModeTest withApplicationRoot(Consumer<JavaArchive> applicationRootConsumer);
114
    public void modifySourceFile(String relativePath, Function<String, String> mutator);
115
    public void modifyFile(String relativePath, Function<String, String> mutator);
116
    public void addResourceFile(String path, String data);
117
    public List<LogRecord> getLogRecords();
118
}
119
```
120

121
[Development Mode Testing](./dev-mode-testing.md)
122

123
### Production Mode Testing
124

125
Test extension for producing and testing production-mode jars with native build support, runtime configuration, and process lifecycle management.
126

127
```java { .api }
128
public class QuarkusProdModeTest implements BeforeAllCallback, AfterAllCallback, 
129
    BeforeEachCallback, TestWatcher, InvocationInterceptor {
130
    
131
    public QuarkusProdModeTest();
132
    
133
    public QuarkusProdModeTest setArchiveProducer(Supplier<JavaArchive> archiveProducer);
134
    public QuarkusProdModeTest setBuildNative(boolean buildNative);
135
    public QuarkusProdModeTest setRun(boolean run);
136
    public void start();
137
    public void stop();
138
    public String getStartupConsoleOutput();
139
    public Integer getExitCode();
140
}
141
```
142

143
[Production Mode Testing](./prod-mode-testing.md)
144

145
### Logging and Test Resources
146

147
Comprehensive logging collection, filtering, and test resource management for capturing and analyzing test execution logs.
148

149
```java { .api }
150
public class LogCollectingTestResource implements QuarkusTestResourceLifecycleManager {
151
    public static LogCollectingTestResource current();
152
    public List<LogRecord> getRecords();
153
    public void clear();
154
}
155

156
public class InMemoryLogHandler extends ExtHandler {
157
    public InMemoryLogHandler(Predicate<LogRecord> predicate);
158
    public List<LogRecord> getRecords();
159
}
160
```
161

162
[Logging and Test Resources](./logging-test-resources.md)
163

164
### Build Chain Customization
165

166
Support for customizing Quarkus build chains during testing, including build steps, producers, and consumers for comprehensive build testing.
167

168
```java { .api }
169
public abstract class ProdModeTestBuildStep implements BuildStep {
170
    public ProdModeTestBuildStep(Map<String, Object> testContext);
171
    public Map<String, Object> getTestContext();
172
}
173

174
public class ProdModeTestBuildChainBuilderConsumer implements Consumer<BuildChainBuilder> {
175
    public ProdModeTestBuildChainBuilderConsumer(String buildStepClassName, 
176
        List<String> producesClassNames, List<String> consumesClassNames, 
177
        Map<String, Object> testContext);
178
    public void accept(BuildChainBuilder builder);
179
}
180
```
181

182
[Build Chain Customization](./build-chain-customization.md)
183

184
### Result Containers and Utilities
185

186
Data containers and utility classes for managing test results, continuous testing support, and cache management.
187

188
```java { .api }
189
public class ProdModeTestResults {
190
    public ProdModeTestResults(Path buildDir, Path builtArtifactPath, 
191
        List<ArtifactResult> results, List<LogRecord> retainedBuildLogRecords);
192
    public Path getBuildDir();
193
    public Path getBuiltArtifactPath();
194
    public List<ArtifactResult> getResults();
195
}
196

197
public class ContinuousTestingTestUtils {
198
    public TestStatus waitForNextCompletion();
199
    public static String appProperties(String... props);
200
}
201

202
public class ClearCache {
203
    public static void clearCaches();
204
}
205
```
206

207
[Result Containers and Utilities](./results-utilities.md)
208

209
## Annotations
210

211
### @LogFile
212

213
Marker annotation for injecting log file paths into test fields.
214

215
```java { .api }
216
@Target(ElementType.FIELD)
217
@Retention(RetentionPolicy.RUNTIME)
218
public @interface LogFile {
219
}
220
```
221

222
### @ProdBuildResults
223

224
Marker annotation for injecting production build results into test fields.
225

226
```java { .api }
227
@Target(ElementType.FIELD)
228
@Retention(RetentionPolicy.RUNTIME)
229
public @interface ProdBuildResults {
230
}
231
```
232

233
## Types
234

235
### Build Chain Types
236

237
```java { .api }
238
public static class BuildChainCustomizerEntry {
239
    public BuildChainCustomizerEntry(Class<? extends ProdModeTestBuildStep> buildStepClass,
240
        List<Class<? extends BuildItem>> produces, List<Class<? extends BuildItem>> consumes);
241
    public Class<? extends BuildStep> getBuildStepClass();
242
    public List<Class<? extends BuildItem>> getProduces();
243
    public List<Class<? extends BuildItem>> getConsumes();
244
}
245
```
246

247
### Continuous Testing Types
248

249
```java { .api }
250
public static class TestStatus {
251
    public TestStatus();
252
    public TestStatus(long lastRun, long running, long testsRun, long testsPassed, 
253
        long testsFailed, long testsSkipped, long totalTestsPassed, 
254
        long totalTestsFailed, long totalTestsSkipped);
255
    
256
    // Getter and setter methods for all status fields
257
    public long getLastRun();
258
    public void setLastRun(long lastRun);
259
    public long getRunning();
260
    public void setRunning(long running);
261
    public String toString();
262
}
263
```