0
# HTTP Stubbing
1

2
Request-response mapping system with fluent API for creating sophisticated HTTP service simulations. Supports all HTTP methods, advanced request matching, and flexible response generation for comprehensive API mocking scenarios.
3

4
## Capabilities
5

6
### WireMock Client Class
7

8
Primary client API for configuring stubs and managing WireMock server interactions.
9

10
```java { .api }
11
/**
12
 * Main client API class for WireMock server interaction
13
 */
14
class WireMock {
15
    // Static Configuration Methods
16
    /** Create new WireMock builder instance */
17
    static WireMockBuilder create();
18
    
19
    /** Configure default instance for localhost with specified port */
20
    static void configureFor(int port);
21
    
22
    /** Configure default instance with host and port */
23
    static void configureFor(String host, int port);
24
    
25
    /** Configure default instance with host, port, and URL prefix */
26
    static void configureFor(String host, int port, String urlPathPrefix);
27
    
28
    /** Configure default instance with full connection details */
29
    static void configureFor(String scheme, String host, int port, String urlPathPrefix);
30
    
31
    /** Set specific client as default */
32
    static void configureFor(WireMock client);
33
    
34
    // HTTP Method Builders
35
    /** Create GET request matcher */
36
    static MappingBuilder get(UrlPattern urlPattern);
37
    
38
    /** Create POST request matcher */
39
    static MappingBuilder post(UrlPattern urlPattern);
40
    
41
    /** Create PUT request matcher */
42
    static MappingBuilder put(UrlPattern urlPattern);
43
    
44
    /** Create DELETE request matcher */
45
    static MappingBuilder delete(UrlPattern urlPattern);
46
    
47
    /** Create PATCH request matcher */
48
    static MappingBuilder patch(UrlPattern urlPattern);
49
    
50
    /** Create HEAD request matcher */
51
    static MappingBuilder head(UrlPattern urlPattern);
52
    
53
    /** Create OPTIONS request matcher */
54
    static MappingBuilder options(UrlPattern urlPattern);
55
    
56
    /** Create TRACE request matcher */
57
    static MappingBuilder trace(UrlPattern urlPattern);
58
    
59
    /** Match any HTTP method */
60
    static MappingBuilder any(UrlPattern urlPattern);
61
    
62
    /** Match both GET and HEAD methods */
63
    static MappingBuilder getOrHead(UrlPattern urlPattern);
64
    
65
    // Stub Management
66
    /** Create stub mapping (primary method) */
67
    static void givenThat(MappingBuilder mappingBuilder);
68
    
69
    /** Create stub mapping (alias for givenThat) */
70
    static void stubFor(MappingBuilder mappingBuilder);
71
    
72
    /** Edit existing stub mapping */
73
    static void editStub(MappingBuilder mappingBuilder);
74
    
75
    /** Remove stub by mapping builder */
76
    static void removeStub(MappingBuilder mappingBuilder);
77
    
78
    /** Remove stub by stub mapping object */
79
    static void removeStub(StubMapping stubMapping);
80
    
81
    /** Remove stub by UUID */
82
    static void removeStub(UUID id);
83
    
84
    /** List all configured stub mappings */
85
    static ListStubMappingsResult listAllStubMappings();
86
    
87
    /** Get specific stub mapping by ID */
88
    static SingleStubMappingResult getSingleStubMapping(UUID id);
89
}
90
```
91

92
**Usage Examples:**
93

94
```java
95
import static com.github.tomakehurst.wiremock.client.WireMock.*;
96

97
// Configure WireMock client
98
configureFor("localhost", 8089);
99

100
// Simple GET stub
101
stubFor(get(urlEqualTo("/api/users"))
102
    .willReturn(aResponse()
103
        .withStatus(200)
104
        .withHeader("Content-Type", "application/json")
105
        .withBody("[{\"id\": 1, \"name\": \"John\"}]")));
106

107
// POST stub with request body matching
108
stubFor(post(urlEqualTo("/api/users"))
109
    .withHeader("Content-Type", equalTo("application/json"))
110
    .withRequestBody(matchingJsonPath("$.name"))
111
    .willReturn(aResponse()
112
        .withStatus(201)
113
        .withHeader("Location", "/api/users/123")
114
        .withBody("{\"id\": 123, \"name\": \"John\"}")));
115

116
// Dynamic response with delays
117
stubFor(get(urlMatching("/api/users/[0-9]+"))
118
    .willReturn(aResponse()
119
        .withStatus(200)
120
        .withFixedDelay(500)
121
        .withBodyFile("user-template.json")));
122
```
123

124
### MappingBuilder Interface
125

126
Main interface for building request-response mappings with comprehensive matching options.
127

128
```java { .api }
129
/**
130
 * Interface for building request-response mappings
131
 */
132
interface MappingBuilder {
133
    // Request Matching
134
    /** Match request scheme (http/https) */
135
    MappingBuilder withScheme(String scheme);
136
    
137
    /** Match host header */
138
    MappingBuilder withHost(StringValuePattern hostPattern);
139
    
140
    /** Match port number */
141
    MappingBuilder withPort(int port);
142
    
143
    /** Match client IP address */
144
    MappingBuilder withClientIp(StringValuePattern hostPattern);
145
    
146
    /** Match single header value */
147
    MappingBuilder withHeader(String key, StringValuePattern pattern);
148
    
149
    /** Match multiple header values */
150
    MappingBuilder withHeader(String key, MultiValuePattern pattern);
151
    
152
    /** Match path parameter by name */
153
    MappingBuilder withPathParam(String name, StringValuePattern pattern);
154
    
155
    /** Match single query parameter */
156
    MappingBuilder withQueryParam(String key, StringValuePattern pattern);
157
    
158
    /** Match multiple query parameter values */
159
    MappingBuilder withQueryParam(String key, MultiValuePattern pattern);
160
    
161
    /** Match single form parameter */
162
    MappingBuilder withFormParam(String key, StringValuePattern pattern);
163
    
164
    /** Match multiple form parameter values */
165
    MappingBuilder withFormParam(String key, MultiValuePattern pattern);
166
    
167
    /** Match request body content */
168
    MappingBuilder withRequestBody(ContentPattern<?> bodyPattern);
169
    
170
    /** Match multipart request body */
171
    MappingBuilder withMultipartRequestBody(MultipartValuePatternBuilder builder);
172
    
173
    /** Match HTTP Basic authentication */
174
    MappingBuilder withBasicAuth(String username, String password);
175
    
176
    /** Match cookie value */
177
    MappingBuilder withCookie(String name, StringValuePattern pattern);
178
    
179
    // Configuration Methods
180
    /** Set mapping priority (lower numbers = higher priority) */
181
    MappingBuilder atPriority(Integer priority);
182
    
183
    /** Set mapping UUID */
184
    MappingBuilder withId(UUID id);
185
    
186
    /** Set mapping name for identification */
187
    MappingBuilder withName(String name);
188
    
189
    /** Make mapping persistent across resets */
190
    MappingBuilder persistent();
191
    
192
    /** Add metadata to mapping */
193
    MappingBuilder withMetadata(Map<String, ?> metadata);
194
    
195
    /** Add metadata to mapping */
196
    MappingBuilder withMetadata(Metadata metadata);
197
    
198
    /** Add custom request matcher */
199
    MappingBuilder andMatching(ValueMatcher<Request> requestMatcher);
200
    
201
    /** Add named custom request matcher */
202
    MappingBuilder andMatching(String matcherName);
203
    
204
    // Response Configuration
205
    /** Set response definition */
206
    MappingBuilder willReturn(ResponseDefinitionBuilder responseDefBuilder);
207
    
208
    // Scenario Configuration
209
    /** Associate mapping with scenario */
210
    MappingBuilder inScenario(String scenarioName);
211
    
212
    // Extension Points
213
    /** Add post-serve action */
214
    MappingBuilder withPostServeAction(String extensionName, Parameters parameters);
215
    
216
    /** Add serve event listener */
217
    MappingBuilder withServeEventListener(String extensionName, Parameters parameters);
218
}
219
```
220

221
### ScenarioMappingBuilder Interface
222

223
Extended mapping builder with scenario state management capabilities.
224

225
```java { .api }
226
/**
227
 * Extended mapping builder with scenario support
228
 */
229
interface ScenarioMappingBuilder extends MappingBuilder {
230
    /** Require specific scenario state to match */
231
    ScenarioMappingBuilder whenScenarioStateIs(String stateName);
232
    
233
    /** Set new scenario state after successful match */
234
    ScenarioMappingBuilder willSetStateTo(String stateName);
235
}
236
```
237

238
**Usage Examples:**
239

240
```java
241
// Stateful behavior with scenarios
242
stubFor(get(urlEqualTo("/api/start"))
243
    .inScenario("User Journey")
244
    .whenScenarioStateIs(Scenario.STARTED)
245
    .willReturn(aResponse().withStatus(200))
246
    .willSetStateTo("AUTHENTICATED"));
247

248
stubFor(get(urlEqualTo("/api/profile"))
249
    .inScenario("User Journey")
250
    .whenScenarioStateIs("AUTHENTICATED")
251
    .willReturn(aResponse()
252
        .withStatus(200)
253
        .withBodyFile("user-profile.json")));
254
```
255

256
### WireMockBuilder Class
257

258
Builder for creating configured WireMock client instances.
259

260
```java { .api }
261
/**
262
 * Builder for configuring WireMock client instances
263
 */
264
class WireMockBuilder {
265
    /** Set port number */
266
    WireMockBuilder port(int port);
267
    
268
    /** Set hostname */
269
    WireMockBuilder host(String host);
270
    
271
    /** Set URL scheme */
272
    WireMockBuilder scheme(String scheme);
273
    
274
    /** Set HTTP scheme */
275
    WireMockBuilder http();
276
    
277
    /** Set HTTPS scheme */
278
    WireMockBuilder https();
279
    
280
    /** Set URL path prefix */
281
    WireMockBuilder urlPathPrefix(String urlPathPrefix);
282
    
283
    /** Set custom host header */
284
    WireMockBuilder hostHeader(String hostHeader);
285
    
286
    /** Set proxy host */
287
    WireMockBuilder proxyHost(String proxyHost);
288
    
289
    /** Set proxy port */
290
    WireMockBuilder proxyPort(int proxyPort);
291
    
292
    /** Set client authenticator */
293
    WireMockBuilder authenticator(ClientAuthenticator authenticator);
294
    
295
    /** Set basic authentication */
296
    WireMockBuilder basicAuthenticator(String username, String password);
297
    
298
    /** Create configured WireMock instance */
299
    WireMock build();
300
}
301
```
302

303
**Usage Examples:**
304

305
```java
306
// Custom WireMock client
307
WireMock customClient = WireMock.create()
308
    .scheme("https")
309
    .host("wiremock.example.com")
310
    .port(443)
311
    .urlPathPrefix("/mock")
312
    .basicAuthenticator("admin", "password")
313
    .build();
314

315
// Use custom client
316
customClient.register(get(urlEqualTo("/test"))
317
    .willReturn(aResponse().withStatus(200)));
318
```
319

320
### BasicMappingBuilder Implementation
321

322
Concrete implementation providing all mapping builder functionality.
323

324
```java { .api }
325
/**
326
 * Concrete implementation of MappingBuilder and ScenarioMappingBuilder
327
 */
328
class BasicMappingBuilder implements MappingBuilder, ScenarioMappingBuilder {
329
    /** Create mapping builder for specific HTTP method and URL pattern */
330
    BasicMappingBuilder(RequestMethod method, UrlPattern urlPattern);
331
    
332
    /** Build final StubMapping from configured builder */
333
    StubMapping build();
334
}
335
```
336

337
### Stub Management Types
338

339
```java { .api }
340
class StubMapping {
341
    UUID getId();
342
    String getName();
343
    RequestPattern getRequest();
344
    ResponseDefinition getResponse();
345
    Integer getPriority();
346
    boolean isPersistent();
347
    String getScenarioName();
348
    String getRequiredScenarioState();
349
    String getNewScenarioState();
350
    Metadata getMetadata();
351
    List<PostServeActionDefinition> getPostServeActions();
352
    List<ServeEventListenerDefinition> getServeEventListeners();
353
    long getInsertionIndex();
354
    boolean isDirty();
355
}
356

357
class ListStubMappingsResult {
358
    List<StubMapping> getMappings();
359
    Meta getMeta();
360
}
361

362
class SingleStubMappingResult {
363
    StubMapping getItem();
364
    Meta getMeta();
365
}
366

367
class Metadata {
368
    static Metadata metadata();
369
    Metadata attr(String key, Object value);
370
    Object getAttribute(String key);
371
    Map<String, Object> getAttributes();
372
}
373

374
enum RequestMethod {
375
    GET, POST, PUT, DELETE, PATCH, HEAD, OPTIONS, TRACE, ANY
376
}
377
```