0
# Core Testing
1

2
The core testing capabilities provide the primary annotations for different testing modes in Quarkus applications.
3

4
## Unit Testing with @QuarkusTest
5

6
The `@QuarkusTest` annotation enables full CDI support in unit tests, running within the same JVM as the test with complete application context.
7

8
```java { .api }
9
@Target(ElementType.TYPE)
10
@Retention(RetentionPolicy.RUNTIME)
11
@ExtendWith(QuarkusTestExtension.class)
12
@Tag("io.quarkus.test.junit.QuarkusTest")
13
public @interface QuarkusTest {
14
}
15
```
16

17
### Usage Example
18

19
```java
20
import io.quarkus.test.junit.QuarkusTest;
21
import jakarta.inject.Inject;
22
import org.junit.jupiter.api.Test;
23
import static org.junit.jupiter.api.Assertions.*;
24

25
@QuarkusTest
26
class ProductServiceTest {
27
    
28
    @Inject
29
    ProductService productService;
30
    
31
    @Inject
32
    EntityManager entityManager;
33
    
34
    @Test
35
    void testCreateProduct() {
36
        Product product = productService.createProduct("Laptop", 999.99);
37
        assertNotNull(product.getId());
38
        assertEquals("Laptop", product.getName());
39
    }
40
    
41
    @Test
42
    @Transactional
43
    void testProductPersistence() {
44
        Product product = new Product("Phone", 599.99);
45
        entityManager.persist(product);
46
        entityManager.flush();
47
        
48
        Product found = entityManager.find(Product.class, product.getId());
49
        assertEquals("Phone", found.getName());
50
    }
51
}
52
```
53

54
**Key Features:**
55
- Full CDI dependency injection with `@Inject`
56
- Transaction support with `@Transactional`  
57
- Configuration property injection with `@ConfigProperty`
58
- Dev services integration (automatic test databases, etc.)
59
- Mock support via `QuarkusMock`
60

61
## Integration Testing with @QuarkusIntegrationTest
62

63
The `@QuarkusIntegrationTest` annotation runs tests against built application artifacts (JAR files, native images, or containers) in separate processes.
64

65
```java { .api }
66
@Target(ElementType.TYPE)
67
@Retention(RetentionPolicy.RUNTIME)
68
@ExtendWith({DisabledOnIntegrationTestCondition.class, QuarkusIntegrationTestExtension.class})
69
public @interface QuarkusIntegrationTest {
70
    
71
    /**
72
     * @deprecated Use DevServicesContext instead
73
     */
74
    @Deprecated
75
    interface Context extends DevServicesContext {
76
    }
77
}
78
```
79

80
### Usage Example
81

82
```java
83
import io.quarkus.test.junit.QuarkusIntegrationTest;
84
import io.restassured.RestAssured;
85
import org.junit.jupiter.api.Test;
86
import static io.restassured.RestAssured.given;
87
import static org.hamcrest.CoreMatchers.is;
88

89
@QuarkusIntegrationTest
90
class ProductEndpointIT {
91
    
92
    @Test
93
    void testGetProducts() {
94
        given()
95
            .when().get("/api/products")
96
            .then()
97
                .statusCode(200)
98
                .body("size()", is(0));
99
    }
100
    
101
    @Test
102
    void testCreateProduct() {
103
        given()
104
            .contentType("application/json")
105
            .body("{\"name\":\"Tablet\",\"price\":299.99}")
106
            .when().post("/api/products")
107
            .then()
108
                .statusCode(201);
109
    }
110
    
111
    @Test
112
    void testHealthCheck() {
113
        given()
114
            .when().get("/q/health")
115
            .then()
116
                .statusCode(200)
117
                .body("status", is("UP"));
118
    }
119
}
120
```
121

122
**Key Features:**
123
- Tests against production-like artifacts
124
- Supports JAR, native image, and container testing
125
- HTTP-based testing with REST Assured
126
- No CDI injection (tests run in separate process)
127
- Automatic artifact detection and launching
128
- Dev services integration for external dependencies
129

130
## Test Execution Modes
131

132
### JVM Mode vs Native Mode
133
- **JVM Mode**: Tests run against standard JVM bytecode
134
- **Native Mode**: Tests run against GraalVM native images  
135
- **Container Mode**: Tests run against containerized applications
136

137
### Artifact Type Detection
138
The framework automatically detects and launches the appropriate artifact type:
139

140
1. **Native Binary**: If `target/[app-name]-runner` exists
141
2. **Container**: If container image was built during build process
142
3. **JAR**: Falls back to `java -jar target/quarkus-app/quarkus-run.jar`
143

144
### Test Isolation
145
- `@QuarkusTest`: Tests share application instance (faster, but less isolation)
146
- `@QuarkusIntegrationTest`: Each test class gets fresh application instance (slower, but better isolation)
147

148
## Error Handling
149

150
Common exceptions and error scenarios:
151

152
```java
153
// Configuration errors
154
@ConfigProperty(name = "nonexistent.property")
155
String value; // Throws DeploymentException if property not found
156

157
// CDI injection errors  
158
@Inject
159
NonExistentBean bean; // Throws UnsatisfiedResolutionException
160

161
// Test resource errors
162
@QuarkusTestResource(DatabaseResource.class)
163
class MyTest {
164
    // Throws TestResourceException if resource fails to start
165
}
166
```
167

168
## Testing Best Practices
169

170
### Test Class Organization
171
```java
172
// Base test class with @QuarkusTest
173
@QuarkusTest
174
class UserServiceTest {
175
    // Unit test methods
176
}
177

178
// Integration test extends base class
179
@QuarkusIntegrationTest  
180
class UserServiceIT extends UserServiceTest {
181
    // Same test methods run against built artifact
182
}
183
```
184

185
### Resource Management
186
```java
187
@QuarkusTest
188
class DatabaseTest {
189
    
190
    @TestTransaction  // Automatic rollback
191
    @Test
192
    void testDataModification() {
193
        // Changes are rolled back after test
194
    }
195
    
196
    @Test
197
    void testReadOnlyOperation() {
198
        // No transaction needed for read-only tests
199
    }
200
}
201
```