0
# WireMock
1

2
WireMock is a comprehensive HTTP service mocking and service virtualization library designed for testing and development environments. It provides a flexible HTTP server that can simulate REST APIs and web services for unit testing, integration testing, and development. WireMock offers advanced request matching capabilities, flexible response generation, and extensive extensibility for complex testing scenarios.
3

4
## Package Information
5

6
- **Package Name**: wiremock
7
- **Package Type**: maven
8
- **Language**: Java
9
- **Installation**: `org.wiremock:wiremock:3.13.1`
10
- **Main Class**: `wiremock.Run`
11

12
## Core Imports
13

14
### Essential Imports
15

16
```java
17
// Core server and client classes
18
import com.github.tomakehurst.wiremock.WireMockServer;
19
import com.github.tomakehurst.wiremock.client.WireMock;
20
import com.github.tomakehurst.wiremock.core.WireMockConfiguration;
21

22
// Static imports for fluent API
23
import static com.github.tomakehurst.wiremock.client.WireMock.*;
24
import static com.github.tomakehurst.wiremock.core.WireMockConfiguration.wireMockConfig;
25
```
26

27
### JUnit Testing Imports
28

29
```java
30
// JUnit 4 integration
31
import com.github.tomakehurst.wiremock.junit.WireMockRule;
32
import com.github.tomakehurst.wiremock.junit.WireMockClassRule;
33

34
// JUnit 5 integration
35
import com.github.tomakehurst.wiremock.junit5.WireMockExtension;
36
import com.github.tomakehurst.wiremock.junit5.WireMockTest;
37
```
38

39
### Advanced Pattern Matching
40

41
```java
42
// Request pattern matching
43
import com.github.tomakehurst.wiremock.matching.RequestPatternBuilder;
44
import com.github.tomakehurst.wiremock.matching.StringValuePattern;
45
import com.github.tomakehurst.wiremock.matching.UrlPattern;
46

47
// Fault injection
48
import com.github.tomakehurst.wiremock.http.Fault;
49

50
// Request logging and verification
51
import com.github.tomakehurst.wiremock.verification.LoggedRequest;
52
import com.github.tomakehurst.wiremock.stubbing.ServeEvent;
53
```
54

55
### Extension Development
56

57
```java
58
// Extension interfaces
59
import com.github.tomakehurst.wiremock.extension.Extension;
60
import com.github.tomakehurst.wiremock.extension.ResponseTransformerV2;
61
import com.github.tomakehurst.wiremock.extension.ServeEventListener;
62
import com.github.tomakehurst.wiremock.extension.Parameters;
63
```
64

65
## Basic Usage
66

67
### Programmatic Usage
68

69
```java
70
import com.github.tomakehurst.wiremock.WireMockServer;
71
import com.github.tomakehurst.wiremock.client.WireMock;
72
import static com.github.tomakehurst.wiremock.client.WireMock.*;
73
import static com.github.tomakehurst.wiremock.core.WireMockConfiguration.wireMockConfig;
74

75
// Start WireMock server
76
WireMockServer wireMockServer = new WireMockServer(wireMockConfig().port(8089));
77
wireMockServer.start();
78

79
// Configure WireMock client
80
WireMock.configureFor("localhost", 8089);
81

82
// Create a simple stub
83
stubFor(get(urlEqualTo("/api/users/123"))
84
    .willReturn(aResponse()
85
        .withStatus(200)
86
        .withHeader("Content-Type", "application/json")
87
        .withBody("{\"id\": 123, \"name\": \"John Doe\"}")));
88

89
// Verify requests
90
verify(getRequestedFor(urlEqualTo("/api/users/123")));
91

92
// Shutdown server
93
wireMockServer.stop();
94
```
95

96
### Standalone Command-Line Usage
97

98
```bash
99
# Start standalone server
100
java -jar wiremock-standalone-3.13.1.jar --port 8080
101

102
# With HTTPS support
103
java -jar wiremock-standalone-3.13.1.jar --port 8080 --https-port 8443
104

105
# With proxy mode
106
java -jar wiremock-standalone-3.13.1.jar --port 8080 --proxy-all="https://api.example.com"
107

108
# Record mappings
109
java -jar wiremock-standalone-3.13.1.jar --port 8080 --record-mappings --proxy-all="https://api.example.com"
110
```
111

112
## Architecture
113

114
WireMock Standalone is built around several key components:
115

116
- **Server Core**: `WireMockServer` class that manages HTTP server lifecycle and configuration
117
- **Client API**: `WireMock` class providing fluent API for stub creation and request verification
118
- **Request Matching**: Comprehensive pattern matching system for URLs, headers, bodies, and custom matchers
119
- **Response Generation**: Flexible response building with static content, files, templates, and proxying
120
- **Extension System**: Plugin architecture for custom transformers, filters, and event listeners
121
- **JUnit Integration**: Test rules and extensions for seamless testing framework integration
122
- **Standalone Runner**: Command-line interface for running WireMock as a standalone service
123

124
## Capabilities
125

126
### Server Configuration and Lifecycle
127

128
Core server management functionality for starting, configuring, and controlling WireMock instances with extensive configuration options.
129

130
```java { .api }
131
class WireMockServer implements Container, Stubbing, Admin {
132
    WireMockServer(Options options);
133
    WireMockServer(int port);
134
    void start();
135
    void stop();
136
    int port();
137
    boolean isRunning();
138
}
139

140
class WireMockConfiguration implements Options {
141
    // Factory Method
142
    static WireMockConfiguration wireMockConfig();
143
    
144
    // Basic Configuration
145
    WireMockConfiguration port(int portNumber);
146
    WireMockConfiguration httpsPort(Integer httpsPort);
147
    WireMockConfiguration bindAddress(String bindAddress);
148
    WireMockConfiguration timeout(long timeout);
149
    
150
    // SSL/TLS Configuration
151
    WireMockConfiguration keystorePath(String keystorePath);
152
    WireMockConfiguration keystorePassword(String keystorePassword);
153
    WireMockConfiguration trustStorePath(String trustStorePath);
154
    WireMockConfiguration needClientAuth(boolean needClientAuth);
155
    
156
    // Proxy Configuration
157
    WireMockConfiguration enableBrowserProxying(boolean enabled);
158
    WireMockConfiguration proxyVia(String host, int port);
159
    WireMockConfiguration trustAllProxyTargets(boolean trustAll);
160
    
161
    // Performance Configuration
162
    WireMockConfiguration containerThreads(Integer containerThreads);
163
    WireMockConfiguration jettyAcceptors(Integer jettyAcceptors);
164
    WireMockConfiguration asynchronousResponseEnabled(boolean enabled);
165
    
166
    // Extension Configuration
167
    WireMockConfiguration extensions(Extension... extensions);
168
    WireMockConfiguration extensionScanningEnabled(boolean enabled);
169
    
170
    // File and Logging
171
    WireMockConfiguration usingFilesUnderDirectory(String directory);
172
    WireMockConfiguration usingFilesUnderClasspath(String classpathDirectoryName);
173
    WireMockConfiguration notifier(Notifier notifier);
174
}
175
```
176

177
[Server Configuration](./server-configuration.md)
178

179
### HTTP Request Stubbing
180

181
Request-response mapping system with fluent API for creating sophisticated HTTP service simulations.
182

183
```java { .api }
184
class WireMock {
185
    // Configuration
186
    static void configureFor(String host, int port);
187
    static void configureFor(String scheme, String host, int port, String urlPathPrefix);
188
    
189
    // HTTP Method Builders
190
    static MappingBuilder get(UrlPattern urlPattern);
191
    static MappingBuilder post(UrlPattern urlPattern);
192
    static MappingBuilder put(UrlPattern urlPattern);
193
    static MappingBuilder delete(UrlPattern urlPattern);
194
    static MappingBuilder patch(UrlPattern urlPattern);
195
    static MappingBuilder head(UrlPattern urlPattern);
196
    static MappingBuilder options(UrlPattern urlPattern);
197
    static MappingBuilder trace(UrlPattern urlPattern);
198
    static MappingBuilder any(UrlPattern urlPattern);
199
    
200
    // Stub Management
201
    static void givenThat(MappingBuilder mappingBuilder);
202
    static void stubFor(MappingBuilder mappingBuilder);
203
    static void editStub(MappingBuilder mappingBuilder);
204
    static void removeStub(MappingBuilder mappingBuilder);
205
    
206
    // Response Shortcuts
207
    static ResponseDefinitionBuilder aResponse();
208
    static ResponseDefinitionBuilder ok();
209
    static ResponseDefinitionBuilder created();
210
    static ResponseDefinitionBuilder notFound();
211
    static ResponseDefinitionBuilder serverError();
212
    
213
    // Recording
214
    static void startRecording(String targetBaseUrl);
215
    static void startRecording(RecordSpec recordSpec);
216
    static SnapshotRecordResult stopRecording();
217
    static SnapshotRecordResult snapshotRecord();
218
    
219
    // Request Inspection
220
    static List<ServeEvent> getAllServeEvents();
221
    static List<LoggedRequest> findAll(RequestPatternBuilder requestPatternBuilder);
222
    static List<LoggedRequest> findAllUnmatchedRequests();
223
}
224

225
interface MappingBuilder {
226
    MappingBuilder withHeader(String key, StringValuePattern pattern);
227
    MappingBuilder withRequestBody(ContentPattern<?> bodyPattern);
228
    MappingBuilder willReturn(ResponseDefinitionBuilder responseDefBuilder);
229
}
230
```
231

232
[HTTP Stubbing](./http-stubbing.md)
233

234
### Request and Response Matching
235

236
Advanced pattern matching capabilities for precise request identification and response generation.
237

238
```java { .api }
239
// URL Pattern Methods
240
static UrlPattern urlEqualTo(String testUrl);
241
static UrlPattern urlMatching(String urlRegex);
242
static UrlPattern urlPathEqualTo(String testUrl);
243
static UrlPattern urlPathMatching(String urlRegex);
244
static UrlPattern urlPathTemplate(String pathTemplate);
245
static UrlPattern anyUrl();
246

247
// String Value Patterns
248
static StringValuePattern equalTo(String value);
249
static StringValuePattern equalToIgnoreCase(String value);
250
static StringValuePattern containing(String value);
251
static StringValuePattern notContaining(String value);
252
static StringValuePattern matching(String regex);
253
static StringValuePattern notMatching(String regex);
254
static StringValuePattern absent();
255

256
// JSON/XML Patterns
257
static StringValuePattern equalToJson(String value);
258
static StringValuePattern matchingJsonPath(String jsonPath);
259
static StringValuePattern equalToXml(String value);
260
static StringValuePattern matchingXPath(String xpath);
261

262
// Date/Time Patterns
263
static StringValuePattern before(String dateTime);
264
static StringValuePattern after(String dateTime);
265
static StringValuePattern equalToDateTime(String dateTime);
266
static StringValuePattern beforeNow();
267
static StringValuePattern afterNow();
268

269
// Logical Patterns
270
static LogicalAnd and(StringValuePattern... matchers);
271
static LogicalOr or(StringValuePattern... matchers);
272
static NotPattern not(StringValuePattern unexpectedPattern);
273
```
274

275
[Request Matching](./request-matching.md)
276

277
### Response Building and Configuration
278

279
Comprehensive response generation with support for static content, delays, transformations, and fault injection.
280

281
```java { .api }
282
class ResponseDefinitionBuilder {
283
    static ResponseDefinitionBuilder aResponse();
284
    ResponseDefinitionBuilder withStatus(int status);
285
    ResponseDefinitionBuilder withHeader(String key, String... values);
286
    ResponseDefinitionBuilder withBody(String body);
287
    ResponseDefinitionBuilder withFixedDelay(Integer milliseconds);
288
    ResponseDefinitionBuilder withFault(Fault fault);
289
    ResponseDefinitionBuilder proxiedFrom(String proxyBaseUrl);
290
}
291
```
292

293
[Response Building](./response-building.md)
294

295
### Request Verification and Testing
296

297
Request verification system with count matching, pattern matching, and detailed error reporting for test assertions.
298

299
```java { .api }
300
// Verification Methods
301
static void verify(RequestPatternBuilder requestPatternBuilder);
302
static void verify(int count, RequestPatternBuilder requestPatternBuilder);
303
static void verify(CountMatchingStrategy strategy, RequestPatternBuilder pattern);
304

305
// Count Matching Strategies
306
static CountMatchingStrategy lessThan(int expected);
307
static CountMatchingStrategy exactly(int expected);
308
static CountMatchingStrategy moreThan(int expected);
309

310
// Request Inspection
311
static List<LoggedRequest> findAll(RequestPatternBuilder requestPatternBuilder);
312
static List<LoggedRequest> findUnmatchedRequests();
313
```
314

315
[Request Verification](./request-verification.md)
316

317
### JUnit Integration
318

319
Seamless integration with JUnit 4 and JUnit 5 testing frameworks with lifecycle management and parameter injection.
320

321
```java { .api }
322
// JUnit 4 Integration
323
class WireMockRule extends WireMockServer implements TestRule {
324
    WireMockRule();
325
    WireMockRule(int port);
326
    WireMockRule(Options options);
327
}
328

329
// JUnit 5 Integration
330
class WireMockExtension extends DslWrapper {
331
    static Builder newInstance();
332
    
333
    static class Builder {
334
        Builder options(Options options);
335
        Builder failOnUnmatchedRequests(boolean fail);
336
        WireMockExtension build();
337
    }
338
}
339

340
@WireMockTest
341
public @interface WireMockTest {
342
    int httpPort() default 0;
343
    boolean httpsEnabled() default false;
344
    int httpsPort() default 0;
345
}
346
```
347

348
[JUnit Integration](./junit-integration.md)
349

350
### Extension System
351

352
Plugin architecture for extending WireMock functionality with custom transformers, filters, and event listeners.
353

354
```java { .api }
355
interface Extension {
356
    String getName();
357
    void start();
358
    void stop();
359
}
360

361
interface ResponseTransformerV2 extends Extension {
362
    Response transform(Response response, ServeEvent serveEvent);
363
}
364

365
interface ServeEventListener extends Extension {
366
    void beforeMatch(ServeEvent serveEvent, Parameters parameters);
367
    void afterMatch(ServeEvent serveEvent, Parameters parameters);
368
    void beforeResponseSent(ServeEvent serveEvent, Parameters parameters);
369
    void afterComplete(ServeEvent serveEvent, Parameters parameters);
370
}
371
```
372

373
[Extension System](./extension-system.md)
374

375
### Standalone Command-Line Interface
376

377
Command-line interface for running WireMock as a standalone service with comprehensive configuration options.
378

379
```java { .api }
380
class WireMockServerRunner {
381
    void run(String... args);
382
    void stop();
383
    boolean isRunning();
384
    int port();
385
}
386

387
class CommandLineOptions implements Options {
388
    CommandLineOptions(String... args);
389
    boolean help();
390
    boolean version();
391
    String helpText();
392
    boolean verboseLoggingEnabled();
393
    boolean recordMappingsEnabled();
394
}
395
```
396

397
[Command-Line Interface](./command-line-interface.md)
398

399
## Common Types
400

401
```java { .api }
402
// Core Interfaces
403
interface Options {
404
    int portNumber();
405
    String bindAddress();
406
    boolean getHttpDisabled();
407
    HttpsSettings httpsSettings();
408
    boolean browserProxyingEnabled();
409
    ProxySettings proxyVia();
410
    long timeout();
411
    int containerThreads();
412
    FileSource filesRoot();
413
    Notifier notifier();
414
}
415

416
interface Admin {
417
    void addStubMapping(StubMapping stubMapping);
418
    void removeStubMapping(StubMapping stubMapping);
419
    ListStubMappingsResult listAllStubMappings();
420
    void resetAll();
421
    void resetRequests();
422
    VerificationResult countRequestsMatching(RequestPattern pattern);
423
    FindRequestsResult findRequestsMatching(RequestPattern pattern);
424
}
425

426
interface Container {
427
    int port();
428
    void shutdown();
429
}
430

431
// Pattern Types
432
abstract class StringValuePattern {
433
    boolean isPresent();
434
    Boolean isAbsent();
435
    LogicalAnd and(StringValuePattern other);
436
    LogicalOr or(StringValuePattern other);
437
}
438

439
abstract class ContentPattern<T> implements NamedValueMatcher<T> {
440
    T getValue();
441
}
442

443
// Request/Response Types
444
class RequestPattern {
445
    static RequestPattern ANYTHING;
446
    static RequestPattern everything();
447
    MatchResult match(Request request, Map<String, RequestMatcherExtension> customMatchers);
448
}
449

450
class StubMapping {
451
    UUID getId();
452
    String getName();
453
    RequestPattern getRequest();
454
    ResponseDefinition getResponse();
455
    Integer getPriority();
456
    String getScenarioName();
457
    String getRequiredScenarioState();
458
    String getNewScenarioState();
459
}
460

461
// Fault Types
462
enum Fault {
463
    CONNECTION_RESET_BY_PEER,
464
    EMPTY_RESPONSE,
465
    MALFORMED_RESPONSE_CHUNK,
466
    RANDOM_DATA_THEN_CLOSE
467
}
468

469
// Result Types
470
class VerificationResult {
471
    int getCount();
472
}
473

474
class ListStubMappingsResult {
475
    List<StubMapping> getMappings();
476
}
477

478
class FindRequestsResult {
479
    List<LoggedRequest> getRequests();
480
}
481

482
class LoggedRequest {
483
    String getUrl();
484
    String getMethod();
485
    HttpHeaders getHeaders();
486
    String getBodyAsString();
487
    Date getLoggedDate();
488
}
489
```