0
# JUnit 5 Integration
1

2
Automatic mock server setup and teardown for JUnit 5 tests with annotation-based configuration. Handles both static and instance field injection.
3

4
## Capabilities
5

6
### EnableKubernetesMockClient Annotation
7

8
Primary annotation for enabling automatic Kubernetes mock client setup in JUnit 5 tests.
9

10
```java { .api }
11
/**
12
 * Annotation for enabling KubernetesMockServerExtension JUnit5 extension
13
 * Automatically sets up mock server and injects client instances
14
 */
15
@Target({ TYPE, METHOD, ANNOTATION_TYPE })
16
@Retention(RUNTIME)
17
@ExtendWith(KubernetesMockServerExtension.class)
18
public @interface EnableKubernetesMockClient {
19
    
20
    /**
21
     * Enable HTTPS for the mock server
22
     * @return true to use HTTPS, false for HTTP
23
     */
24
    boolean https() default true;
25
    
26
    /**
27
     * Enable CRUD mode for the mock server
28
     * When true, provides full in-memory Kubernetes API
29
     * When false, uses expectations-based mocking
30
     * @return true for CRUD mode, false for expectations mode
31
     */
32
    boolean crud() default false;
33
    
34
    /**
35
     * Custom builder customizer for the KubernetesClient
36
     * Must have a no-argument constructor
37
     * @return Class implementing Consumer<KubernetesClientBuilder>
38
     */
39
    Class<? extends Consumer<KubernetesClientBuilder>> kubernetesClientBuilderCustomizer() 
40
        default KubernetesClientBuilderCustomizer.class;
41
}
42
```
43

44
**Usage Examples:**
45

46
```java
47
// Basic setup with defaults (HTTPS, expectations mode)
48
@EnableKubernetesMockClient
49
class BasicTest {
50
    KubernetesMockServer server;
51
    KubernetesClient client;
52
}
53

54
// CRUD mode with HTTPS
55
@EnableKubernetesMockClient(crud = true)
56
class CrudTest {
57
    KubernetesMockServer server;
58
    KubernetesClient client;
59
}
60

61
// HTTP-only expectations mode
62
@EnableKubernetesMockClient(https = false)
63
class HttpTest {
64
    KubernetesMockServer server;
65
    KubernetesClient client;
66
}
67

68
// Custom client configuration
69
@EnableKubernetesMockClient(
70
    crud = true, 
71
    kubernetesClientBuilderCustomizer = MyCustomizer.class
72
)
73
class CustomTest {
74
    KubernetesMockServer server;
75
    KubernetesClient client;
76
    
77
    public static class MyCustomizer implements Consumer<KubernetesClientBuilder> {
78
        public MyCustomizer() {} // Required no-arg constructor
79
        
80
        @Override
81
        public void accept(KubernetesClientBuilder builder) {
82
            builder.withRequestTimeout(60000)
83
                   .withNamespace("custom-namespace");
84
        }
85
    }
86
}
87
```
88

89
### KubernetesMockServerExtension
90

91
JUnit 5 extension that handles the lifecycle of mock servers and client injection.
92

93
```java { .api }
94
/**
95
 * JUnit 5 extension implementation for automatic mock server setup
96
 * Handles both static and instance field injection
97
 */
98
public class KubernetesMockServerExtension
99
    implements AfterEachCallback, AfterAllCallback, BeforeEachCallback, BeforeAllCallback {
100
    
101
    /**
102
     * Called before each test method
103
     * Sets up instance-level mock server and client
104
     * @param context JUnit extension context
105
     */
106
    public void beforeEach(ExtensionContext context) throws Exception;
107
    
108
    /**
109
     * Called after each test method
110
     * Cleans up instance-level resources
111
     * @param context JUnit extension context
112
     */
113
    public void afterEach(ExtensionContext context);
114
    
115
    /**
116
     * Called before all test methods in a class
117
     * Sets up static mock server and client if needed
118
     * @param context JUnit extension context
119
     */
120
    public void beforeAll(ExtensionContext context) throws Exception;
121
    
122
    /**
123
     * Called after all test methods in a class
124
     * Cleans up static resources
125
     * @param context JUnit extension context
126
     */
127
    public void afterAll(ExtensionContext context);
128
}
129
```
130

131
### Field Injection
132

133
The extension automatically injects appropriate instances into test class fields based on their types and modifiers.
134

135
**Supported Field Types:**
136

137
```java { .api }
138
// Mock server injection
139
KubernetesMockServer server; // Instance field
140
static KubernetesMockServer server; // Static field
141

142
// Client injection - any of these types work
143
KubernetesClient client;
144
NamespacedKubernetesClient client;
145
Client client; // Base client interface
146

147
// Static client injection
148
static KubernetesClient client;
149
static NamespacedKubernetesClient client;
150
```
151

152
**Field Injection Rules:**
153

154
- Fields must be accessible (package-private, protected, or public)
155
- Field type must match supported types
156
- Static fields are set up once per test class
157
- Instance fields are set up before each test method
158
- Extension handles both server and client lifecycle automatically
159

160
**Usage Examples:**
161

162
```java
163
@EnableKubernetesMockClient
164
class FieldInjectionTest {
165
    // These fields will be automatically injected
166
    KubernetesMockServer server;
167
    KubernetesClient client;
168
    
169
    @Test
170
    void testWithInjectedFields() {
171
        // server and client are ready to use
172
        assertNotNull(server);
173
        assertNotNull(client);
174
        
175
        // Set up expectations
176
        server.expect().get()
177
            .withPath("/api/v1/namespaces")
178
            .andReturn(200, new NamespaceListBuilder().build())
179
            .once();
180
            
181
        // Use client
182
        NamespaceList namespaces = client.namespaces().list();
183
        assertNotNull(namespaces);
184
    }
185
}
186

187
@EnableKubernetesMockClient(crud = true)
188
class StaticFieldTest {
189
    // Static fields shared across all test methods
190
    static KubernetesMockServer server;
191
    static KubernetesClient client;
192
    
193
    @Test
194
    void testOne() {
195
        // Use shared server and client
196
        Pod pod = new PodBuilder().withNewMetadata().withName("test1").endMetadata().build();
197
        client.pods().inNamespace("default").resource(pod).create();
198
    }
199
    
200
    @Test
201
    void testTwo() {
202
        // Same server instance, data persists from previous test
203
        Pod retrieved = client.pods().inNamespace("default").withName("test1").get();
204
        assertNotNull(retrieved);
205
    }
206
}
207
```
208

209
### Custom Client Builder Customization
210

211
Interface for customizing the KubernetesClientBuilder used by the extension.
212

213
```java { .api }
214
/**
215
 * Default customizer that applies no additional configuration
216
 */
217
public class KubernetesClientBuilderCustomizer implements Consumer<KubernetesClientBuilder> {
218
    public KubernetesClientBuilderCustomizer();
219
    
220
    @Override
221
    public void accept(KubernetesClientBuilder kubernetesClientBuilder);
222
}
223

224
// Custom customizer example
225
public class MyCustomizer implements Consumer<KubernetesClientBuilder> {
226
    public MyCustomizer() {} // Required no-arg constructor
227
    
228
    @Override
229
    public void accept(KubernetesClientBuilder builder) {
230
        builder.withRequestTimeout(30000)
231
               .withConnectionTimeout(5000)
232
               .withNamespace("my-namespace")
233
               .withTrustCerts(false);
234
    }
235
}
236
```
237

238
**Usage Examples:**
239

240
```java
241
@EnableKubernetesMockClient(kubernetesClientBuilderCustomizer = TimeoutCustomizer.class)
242
class CustomizedClientTest {
243
    KubernetesMockServer server;
244
    KubernetesClient client; // Will have custom timeouts applied
245
    
246
    public static class TimeoutCustomizer implements Consumer<KubernetesClientBuilder> {
247
        public TimeoutCustomizer() {}
248
        
249
        @Override
250
        public void accept(KubernetesClientBuilder builder) {
251
            builder.withRequestTimeout(60000)
252
                   .withConnectionTimeout(15000);
253
        }
254
    }
255
}
256

257
// Customizer with additional HTTP client configuration
258
public static class HttpCustomizer implements Consumer<KubernetesClientBuilder> {
259
    public HttpCustomizer() {}
260
    
261
    @Override
262
    public void accept(KubernetesClientBuilder builder) {
263
        builder.withHttpClientFactory(new CustomHttpClientFactory())
264
               .withUserAgent("MyTestAgent/1.0");
265
    }
266
}
267
```
268

269
### Lifecycle Management
270

271
The extension automatically manages the complete lifecycle of mock servers and clients:
272

273
**Before Each Test:**
274
1. Creates new `KubernetesMockServer` instance based on annotation configuration
275
2. Initializes and starts the server
276
3. Creates `KubernetesClient` using configured customizer
277
4. Injects instances into appropriate test class fields
278

279
**After Each Test:**
280
1. Destroys the mock server
281
2. Closes the Kubernetes client
282
3. Cleans up resources
283

284
**Static Lifecycle:**
285
- Static fields follow the same pattern but are set up once per test class
286
- Static resources are cleaned up after all tests in the class complete
287
- Useful for sharing state across multiple test methods in CRUD mode