0
# Response Building
1

2
Comprehensive response generation with support for static content, delays, transformations, fault injection, and proxying capabilities for realistic API simulation and testing scenarios.
3

4
## Capabilities
5

6
### ResponseDefinitionBuilder Class
7

8
Main builder class for creating HTTP response definitions with extensive configuration options.
9

10
```java { .api }
11
/**
12
 * Builder for HTTP response definitions
13
 */
14
class ResponseDefinitionBuilder {
15
    // Static Factory Methods
16
    /** Create basic response builder */
17
    static ResponseDefinitionBuilder aResponse();
18
    
19
    /** Create response builder from existing definition */
20
    static ResponseDefinitionBuilder like(ResponseDefinition responseDefinition);
21
    
22
    /** Create JSON response with object serialization */
23
    static ResponseDefinitionBuilder jsonResponse(Object body);
24
    
25
    /** Create empty response builder */
26
    static ResponseDefinitionBuilder responseDefinition();
27
    
28
    /** Create 200 OK JSON response */
29
    static ResponseDefinitionBuilder okForJson(Object body);
30
    
31
    /** Create 200 OK empty JSON response */
32
    static ResponseDefinitionBuilder okForEmptyJson();
33
    
34
    // Status and Headers
35
    /** Set HTTP status code */
36
    ResponseDefinitionBuilder withStatus(int status);
37
    
38
    /** Set HTTP status message */
39
    ResponseDefinitionBuilder withStatusMessage(String message);
40
    
41
    /** Add single response header */
42
    ResponseDefinitionBuilder withHeader(String key, String... values);
43
    
44
    /** Set all response headers */
45
    ResponseDefinitionBuilder withHeaders(HttpHeaders headers);
46
    
47
    // Response Body
48
    /** Set response body from string */
49
    ResponseDefinitionBuilder withBody(String body);
50
    
51
    /** Set response body from byte array */
52
    ResponseDefinitionBuilder withBody(byte[] body);
53
    
54
    /** Set JSON response body from JsonNode */
55
    ResponseDefinitionBuilder withJsonBody(JsonNode jsonBody);
56
    
57
    /** Set response body from file */
58
    ResponseDefinitionBuilder withBodyFile(String fileName);
59
    
60
    /** Set Base64-encoded response body */
61
    ResponseDefinitionBuilder withBase64Body(String base64Body);
62
    
63
    // Delays and Performance
64
    /** Set fixed delay before response */
65
    ResponseDefinitionBuilder withFixedDelay(Integer milliseconds);
66
    
67
    /** Set random delay with distribution */
68
    ResponseDefinitionBuilder withRandomDelay(DelayDistribution distribution);
69
    
70
    /** Set log-normal random delay */
71
    ResponseDefinitionBuilder withLogNormalRandomDelay(double median, double sigma);
72
    
73
    /** Set uniform random delay */
74
    ResponseDefinitionBuilder withUniformRandomDelay(int lower, int upper);
75
    
76
    /** Set chunked response with dribble delay */
77
    ResponseDefinitionBuilder withChunkedDribbleDelay(int chunks, int totalDuration);
78
    
79
    // Response Transformation
80
    /** Add response transformers */
81
    ResponseDefinitionBuilder withTransformers(String... transformerNames);
82
    
83
    /** Set transformer parameters */
84
    ResponseDefinitionBuilder withTransformerParameters(Map<String, Object> parameters);
85
    
86
    /** Add single transformer with parameter */
87
    ResponseDefinitionBuilder withTransformer(String name, String key, Object value);
88
    
89
    // Fault Simulation
90
    /** Inject network fault */
91
    ResponseDefinitionBuilder withFault(Fault fault);
92
    
93
    /** Control gzip compression */
94
    ResponseDefinitionBuilder withGzipDisabled(boolean disabled);
95
    
96
    // Proxying
97
    /** Proxy request to another server */
98
    ProxyResponseDefinitionBuilder proxiedFrom(String proxyBaseUrl);
99
}
100
```
101

102
**Usage Examples:**
103

104
```java
105
// Basic response
106
stubFor(get(urlEqualTo("/api/health"))
107
    .willReturn(aResponse()
108
        .withStatus(200)
109
        .withHeader("Content-Type", "application/json")
110
        .withBody("{\"status\": \"healthy\"}")));
111

112
// File-based response with delay
113
stubFor(get(urlEqualTo("/api/users"))
114
    .willReturn(aResponse()
115
        .withStatus(200)
116
        .withHeader("Content-Type", "application/json")
117
        .withBodyFile("users.json")
118
        .withFixedDelay(500)));
119

120
// Response with random delay
121
stubFor(get(urlEqualTo("/api/slow"))
122
    .willReturn(aResponse()
123
        .withStatus(200)
124
        .withUniformRandomDelay(1000, 3000)
125
        .withBody("Slow response")));
126
```
127

128
### Quick Response Factory Methods
129

130
Static factory methods for common HTTP responses.
131

132
```java { .api }
133
/**
134
 * Quick response factory methods in WireMock class
135
 */
136
// Success Responses
137
/** HTTP 200 OK response */
138
static ResponseDefinitionBuilder ok();
139

140
/** HTTP 200 OK with body */
141
static ResponseDefinitionBuilder ok(String body);
142

143
/** HTTP 200 OK JSON response */
144
static ResponseDefinitionBuilder okJson(String body);
145

146
/** HTTP 200 OK XML response */
147
static ResponseDefinitionBuilder okXml(String body);
148

149
/** HTTP 201 Created response */
150
static ResponseDefinitionBuilder created();
151

152
/** HTTP 204 No Content response */
153
static ResponseDefinitionBuilder noContent();
154

155
// Client Error Responses
156
/** HTTP 400 Bad Request response */
157
static ResponseDefinitionBuilder badRequest();
158

159
/** HTTP 401 Unauthorized response */
160
static ResponseDefinitionBuilder unauthorized();
161

162
/** HTTP 403 Forbidden response */
163
static ResponseDefinitionBuilder forbidden();
164

165
/** HTTP 404 Not Found response */
166
static ResponseDefinitionBuilder notFound();
167

168
// Server Error Responses
169
/** HTTP 500 Internal Server Error response */
170
static ResponseDefinitionBuilder serverError();
171

172
// Custom Status
173
/** Custom HTTP status response */
174
static ResponseDefinitionBuilder status(int status);
175
```
176

177
**Usage Examples:**
178

179
```java
180
// Quick success responses
181
stubFor(get(urlEqualTo("/api/status"))
182
    .willReturn(ok("System is running")));
183

184
stubFor(post(urlEqualTo("/api/users"))
185
    .willReturn(created()
186
        .withHeader("Location", "/api/users/123")));
187

188
// Quick error responses
189
stubFor(get(urlEqualTo("/api/forbidden"))
190
    .willReturn(forbidden()));
191

192
stubFor(get(urlEqualTo("/api/missing"))
193
    .willReturn(notFound()
194
        .withBody("Resource not found")));
195
```
196

197
### ProxyResponseDefinitionBuilder Class
198

199
Extended response builder for proxy configurations with request manipulation.
200

201
```java { .api }
202
/**
203
 * Extended response builder for proxy configurations
204
 */
205
class ProxyResponseDefinitionBuilder extends ResponseDefinitionBuilder {
206
    /** Add header to proxy request */
207
    ProxyResponseDefinitionBuilder withAdditionalRequestHeader(String key, String value);
208
    
209
    /** Remove header from proxy request */
210
    ProxyResponseDefinitionBuilder withRemoveRequestHeader(String key);
211
    
212
    /** Remove URL prefix before proxying */
213
    ProxyResponseDefinitionBuilder withProxyUrlPrefixToRemove(String prefix);
214
}
215
```
216

217
**Usage Examples:**
218

219
```java
220
// Basic proxying
221
stubFor(any(anyUrl())
222
    .willReturn(aResponse()
223
        .proxiedFrom("https://api.example.com")));
224

225
// Proxy with request modification
226
stubFor(get(urlMatching("/api/.*"))
227
    .willReturn(aResponse()
228
        .proxiedFrom("https://backend.example.com")
229
        .withAdditionalRequestHeader("X-Forwarded-By", "WireMock")
230
        .withRemoveRequestHeader("X-Internal-Token")
231
        .withProxyUrlPrefixToRemove("/api")));
232
```
233

234
### Delay Distribution Types
235

236
Various delay distribution implementations for realistic response timing simulation.
237

238
```java { .api }
239
/**
240
 * Delay distribution interfaces and implementations
241
 */
242
interface DelayDistribution {
243
    /** Sample delay value from distribution */
244
    long sampleMillis();
245
}
246

247
class UniformDistribution implements DelayDistribution {
248
    /** Create uniform distribution between min and max */
249
    UniformDistribution(int lower, int upper);
250
    
251
    long sampleMillis();
252
}
253

254
class LogNormal implements DelayDistribution {
255
    /** Create log-normal distribution */
256
    LogNormal(double median, double sigma);
257
    
258
    long sampleMillis();
259
}
260

261
class ChunkedDribbleDelay {
262
    /** Create chunked delay specification */
263
    ChunkedDribbleDelay(int chunks, int totalDuration);
264
    
265
    int getChunks();
266
    int getTotalDuration();
267
}
268
```
269

270
**Usage Examples:**
271

272
```java
273
// Custom delay distributions
274
stubFor(get(urlEqualTo("/api/variable"))
275
    .willReturn(aResponse()
276
        .withRandomDelay(new UniformDistribution(100, 1000))
277
        .withStatus(200)));
278

279
stubFor(get(urlEqualTo("/api/realistic"))
280
    .willReturn(aResponse()
281
        .withLogNormalRandomDelay(200.0, 0.1)
282
        .withStatus(200)));
283

284
// Chunked response with dribble
285
stubFor(get(urlEqualTo("/api/stream"))
286
    .willReturn(aResponse()
287
        .withChunkedDribbleDelay(5, 2000)
288
        .withBody("Streaming data...")));
289
```
290

291
### Fault Injection
292

293
Network-level fault simulation for testing error handling and resilience.
294

295
```java { .api }
296
/**
297
 * Network fault simulation
298
 */
299
enum Fault {
300
    /** Reset connection from peer side */
301
    CONNECTION_RESET_BY_PEER,
302
    
303
    /** Send empty response and close connection */
304
    EMPTY_RESPONSE,
305
    
306
    /** Send malformed HTTP chunk */
307
    MALFORMED_RESPONSE_CHUNK,
308
    
309
    /** Send random data then close connection */
310
    RANDOM_DATA_THEN_CLOSE
311
}
312

313
interface FaultInjector {
314
    /** Inject connection reset by peer */
315
    void connectionResetByPeer();
316
    
317
    /** Send empty response and close */
318
    void emptyResponseAndCloseConnection();
319
    
320
    /** Send malformed response chunk */
321
    void malformedResponseChunk();
322
    
323
    /** Send random data and close */
324
    void randomDataAndCloseConnection();
325
}
326
```
327

328
**Usage Examples:**
329

330
```java
331
// Fault injection for resilience testing
332
stubFor(get(urlEqualTo("/api/unreliable"))
333
    .willReturn(aResponse()
334
        .withFault(Fault.CONNECTION_RESET_BY_PEER)));
335

336
stubFor(get(urlEqualTo("/api/corrupt"))
337
    .willReturn(aResponse()
338
        .withFault(Fault.MALFORMED_RESPONSE_CHUNK)));
339

340
stubFor(post(urlEqualTo("/api/timeout"))
341
    .willReturn(aResponse()
342
        .withFault(Fault.EMPTY_RESPONSE)));
343
```
344

345
### Response Support Types
346

347
Supporting types for response configuration and metadata.
348

349
```java { .api }
350
class ResponseDefinition {
351
    int getStatus();
352
    String getStatusMessage();
353
    byte[] getBody();
354
    String getBodyFileName();
355
    HttpHeaders getHeaders();
356
    Integer getFixedDelayMilliseconds();
357
    DelayDistribution getDelayDistribution();
358
    ChunkedDribbleDelay getChunkedDribbleDelay();
359
    String getProxyBaseUrl();
360
    Fault getFault();
361
    List<String> getTransformers();
362
    Map<String, Object> getTransformerParameters();
363
    boolean wasConfigured();
364
}
365

366
class HttpHeaders {
367
    static HttpHeaders httpHeaders();
368
    HttpHeaders plus(HttpHeader header);
369
    HttpHeaders plus(String key, String... values);
370
    HttpHeader getHeader(String key);
371
    List<HttpHeader> all();
372
    Set<String> keys();
373
    int size();
374
    boolean isEmpty();
375
}
376

377
class HttpHeader {
378
    static HttpHeader httpHeader(String key, String... values);
379
    String key();
380
    String firstValue();
381
    List<String> values();
382
    boolean isPresent();
383
    boolean isSingleValued();
384
    boolean hasValueMatching(StringValuePattern valuePattern);
385
}
386

387
class Meta {
388
    int getTotal();
389
}
390
```