0
# Request Verification
1

2
Request verification system with count matching, pattern matching, and detailed error reporting for test assertions. Provides comprehensive tools for validating that expected HTTP requests were made during testing.
3

4
## Capabilities
5

6
### Basic Request Verification
7

8
Core verification methods for asserting that requests were made with specific patterns.
9

10
```java { .api }
11
/**
12
 * Basic request verification methods in WireMock class
13
 */
14
// Simple Verification
15
/** Verify request was made exactly once */
16
static void verify(RequestPatternBuilder requestPatternBuilder);
17

18
/** Verify request was made specific number of times */
19
static void verify(int count, RequestPatternBuilder requestPatternBuilder);
20

21
/** Verify request with count matching strategy */
22
static void verify(CountMatchingStrategy strategy, RequestPatternBuilder pattern);
23

24
// Request Pattern Builders
25
/** Create request pattern for GET method */
26
static RequestPatternBuilder getRequestedFor(UrlPattern urlPattern);
27

28
/** Create request pattern for POST method */
29
static RequestPatternBuilder postRequestedFor(UrlPattern urlPattern);
30

31
/** Create request pattern for PUT method */
32
static RequestPatternBuilder putRequestedFor(UrlPattern urlPattern);
33

34
/** Create request pattern for DELETE method */
35
static RequestPatternBuilder deleteRequestedFor(UrlPattern urlPattern);
36

37
/** Create request pattern for PATCH method */
38
static RequestPatternBuilder patchRequestedFor(UrlPattern urlPattern);
39

40
/** Create request pattern for HEAD method */
41
static RequestPatternBuilder headRequestedFor(UrlPattern urlPattern);
42

43
/** Create request pattern for OPTIONS method */
44
static RequestPatternBuilder optionsRequestedFor(UrlPattern urlPattern);
45

46
/** Create request pattern for any method */
47
static RequestPatternBuilder anyRequestedFor(UrlPattern urlPattern);
48
```
49

50
**Usage Examples:**
51

52
```java
53
// Basic verification
54
verify(getRequestedFor(urlEqualTo("/api/users")));
55

56
// Verify specific count
57
verify(3, postRequestedFor(urlEqualTo("/api/orders")));
58

59
// Verify with matching strategy
60
verify(moreThan(5), getRequestedFor(urlMatching("/api/products/.*")));
61

62
// Complex request verification
63
verify(postRequestedFor(urlEqualTo("/api/users"))
64
    .withHeader("Content-Type", equalTo("application/json"))
65
    .withRequestBody(matchingJsonPath("$.name")));
66
```
67

68
### Count Matching Strategies
69

70
Flexible count matching with relational operators for sophisticated verification scenarios.
71

72
```java { .api }
73
/**
74
 * Count matching strategy factory methods
75
 */
76
// Relational Count Matching
77
/** Less than expected count */
78
static CountMatchingStrategy lessThan(int expected);
79

80
/** Less than or equal to expected count */
81
static CountMatchingStrategy lessThanOrExactly(int expected);
82

83
/** Exactly expected count */
84
static CountMatchingStrategy exactly(int expected);
85

86
/** Greater than or equal to expected count */
87
static CountMatchingStrategy moreThanOrExactly(int expected);
88

89
/** Greater than expected count */
90
static CountMatchingStrategy moreThan(int expected);
91

92
class CountMatchingStrategy {
93
    /** Create strategy with mode and expected count */
94
    CountMatchingStrategy(CountMatchingMode mode, int expected);
95
    
96
    /** Test if actual count matches expectation */
97
    boolean match(int actual);
98
    
99
    int getExpected();
100
    CountMatchingMode getMode();
101
}
102

103
enum CountMatchingMode implements BiPredicate<Integer, Integer> {
104
    LESS_THAN,
105
    LESS_THAN_OR_EQUAL,
106
    EQUAL_TO,
107
    GREATER_THAN_OR_EQUAL,
108
    GREATER_THAN;
109
    
110
    /** Get human-readable name */
111
    String getFriendlyName();
112
    
113
    /** Test condition against actual and expected values */
114
    boolean test(Integer actual, Integer expected);
115
}
116
```
117

118
**Usage Examples:**
119

120
```java
121
// Count-based verification
122
verify(exactly(1), getRequestedFor(urlEqualTo("/api/login")));
123
verify(lessThan(3), getRequestedFor(urlEqualTo("/api/retry")));
124
verify(moreThanOrExactly(5), getRequestedFor(urlMatching("/api/metrics/.*")));
125

126
// Custom count matching
127
CountMatchingStrategy customStrategy = new CountMatchingStrategy(
128
    CountMatchingMode.GREATER_THAN, 10);
129
verify(customStrategy, getRequestedFor(urlEqualTo("/api/popular")));
130
```
131

132
### Request Inspection and Discovery
133

134
Methods for inspecting actual requests made and finding unmatched requests.
135

136
```java { .api }
137
/**
138
 * Request inspection methods
139
 */
140
// Request Discovery
141
/** Find all requests matching pattern */
142
static List<LoggedRequest> findAll(RequestPatternBuilder requestPatternBuilder);
143

144
/** Get all serve events (requests and responses) */
145
static List<ServeEvent> getAllServeEvents();
146

147
/** Find all unmatched requests */
148
static List<LoggedRequest> findUnmatchedRequests();
149

150
// Near Miss Analysis  
151
/** Find near misses for all unmatched requests */
152
static List<NearMiss> findNearMissesForAllUnmatched();
153

154
/** Find near misses for specific request */
155
static List<NearMiss> findNearMissesFor(LoggedRequest loggedRequest);
156

157
/** Find near misses for request pattern */
158
static List<NearMiss> findNearMissesFor(RequestPattern requestPattern);
159

160
// Administrative Access
161
/** Get verification result for pattern */
162
static VerificationResult findRequestsMatching(RequestPattern requestPattern);
163

164
/** Count requests matching pattern */
165
static VerificationResult countRequestsMatching(RequestPattern requestPattern);
166
```
167

168
**Usage Examples:**
169

170
```java
171
// Inspect actual requests
172
List<LoggedRequest> userRequests = findAll(
173
    getRequestedFor(urlMatching("/api/users/.*")));
174

175
for (LoggedRequest request : userRequests) {
176
    System.out.println("Request: " + request.getMethod() + " " + request.getUrl());
177
    System.out.println("Headers: " + request.getHeaders());
178
    System.out.println("Body: " + request.getBodyAsString());
179
}
180

181
// Find problematic requests
182
List<LoggedRequest> unmatched = findUnmatchedRequests();
183
if (!unmatched.isEmpty()) {
184
    List<NearMiss> nearMisses = findNearMissesForAllUnmatched();
185
    for (NearMiss nearMiss : nearMisses) {
186
        System.out.println("Near miss: " + nearMiss.getRequest().getUrl());
187
        System.out.println("Diff: " + nearMiss.getDiff());
188
    }
189
}
190
```
191

192
### RequestPatternBuilder Class
193

194
Builder for creating detailed request patterns for verification.
195

196
```java { .api }
197
/**
198
 * Builder for request patterns used in verification
199
 */
200
class RequestPatternBuilder {
201
    // Static Factory Methods
202
    /** Create new request pattern builder */
203
    static RequestPatternBuilder newRequestPattern();
204
    
205
    /** Create pattern matching all requests */
206
    static RequestPatternBuilder allRequests();
207
    
208
    /** Create pattern based on existing request pattern */
209
    static RequestPatternBuilder like(RequestPattern requestPattern);
210
    
211
    // HTTP Method and URL
212
    /** Set HTTP method */
213
    RequestPatternBuilder withMethod(RequestMethod method);
214
    
215
    /** Set URL pattern */
216
    RequestPatternBuilder withUrl(UrlPattern urlPattern);
217
    
218
    // Request Matching (same as MappingBuilder)
219
    RequestPatternBuilder withScheme(String scheme);
220
    RequestPatternBuilder withHost(StringValuePattern hostPattern);
221
    RequestPatternBuilder withPort(int port);
222
    RequestPatternBuilder withHeader(String key, StringValuePattern pattern);
223
    RequestPatternBuilder withQueryParam(String key, StringValuePattern pattern);
224
    RequestPatternBuilder withFormParam(String key, StringValuePattern pattern);
225
    RequestPatternBuilder withRequestBody(ContentPattern<?> bodyPattern);
226
    RequestPatternBuilder withBasicAuth(String username, String password);
227
    RequestPatternBuilder withCookie(String name, StringValuePattern pattern);
228
    
229
    // Custom Matching
230
    RequestPatternBuilder andMatching(ValueMatcher<Request> requestMatcher);
231
    RequestPatternBuilder andMatching(String customMatcherName);
232
    
233
    /** Build final request pattern */
234
    RequestPattern build();
235
}
236
```
237

238
**Usage Examples:**
239

240
```java
241
// Custom request pattern building
242
RequestPattern complexPattern = newRequestPattern()
243
    .withMethod(RequestMethod.POST)
244
    .withUrl(urlMatching("/api/orders/[0-9]+/items"))
245
    .withHeader("Authorization", matching("Bearer .*"))
246
    .withHeader("Content-Type", equalTo("application/json"))
247
    .withRequestBody(matchingJsonPath("$.quantity", matching("[1-9][0-9]*")))
248
    .withQueryParam("expand", containing("details"))
249
    .build();
250

251
verify(exactly(1), complexPattern);
252
```
253

254
### Request and Response Models
255

256
Data models representing captured HTTP requests and responses.
257

258
```java { .api }
259
/**
260
 * Request and response data models
261
 */
262
class LoggedRequest {
263
    /** Get request URL */
264
    String getUrl();
265
    
266
    /** Get absolute request URL */
267
    String getAbsoluteUrl();
268
    
269
    /** Get HTTP method */
270
    RequestMethod getMethod();
271
    
272
    /** Get client IP address */
273
    String getClientIp();
274
    
275
    /** Get request headers */
276
    HttpHeaders getHeaders();
277
    
278
    /** Get query parameters */
279
    Map<String, QueryParameter> getQueryParams();
280
    
281
    /** Get form parameters */
282
    Map<String, FormParameter> getFormParams();
283
    
284
    /** Get request body as string */
285
    String getBodyAsString();
286
    
287
    /** Get request body as byte array */
288
    byte[] getBody();
289
    
290
    /** Get multipart parts */
291
    Collection<Request.Part> getParts();
292
    
293
    /** Get cookies */
294
    Map<String, Cookie> getCookies();
295
    
296
    /** Get timestamp when request was logged */
297
    Date getLoggedDate();
298
    
299
    /** Check if request was matched by any stub */
300
    boolean wasMatched();
301
    
302
    /** Get matching stub mapping */
303
    StubMapping getStubMapping();
304
}
305

306
class ServeEvent {
307
    /** Get event ID */
308
    UUID getId();
309
    
310
    /** Get logged request */
311
    LoggedRequest getRequest();
312
    
313
    /** Get response definition */
314
    ResponseDefinition getResponseDefinition();
315
    
316
    /** Get actual response sent */
317
    Response getResponse();
318
    
319
    /** Check if request was matched */
320
    boolean getWasMatched();
321
    
322
    /** Get timing information */
323
    Timing getTiming();
324
    
325
    /** Get post-serve actions */
326
    List<PostServeActionDefinition> getPostServeActions();
327
}
328

329
class NearMiss {
330
    /** Get the request that nearly matched */
331
    LoggedRequest getRequest();
332
    
333
    /** Get the stub mapping that nearly matched */
334
    StubMapping getStubMapping();
335
    
336
    /** Get detailed difference information */
337
    Diff getDiff();
338
    
339
    /** Get match distance (0.0 = perfect match, 1.0 = no match) */
340
    double getDistance();
341
}
342
```
343

344
### Verification Exception Handling
345

346
Exception types for verification failures with detailed diagnostic information.
347

348
```java { .api }
349
/**
350
 * Verification exception with detailed error information
351
 */
352
class VerificationException extends RuntimeException {
353
    /** Basic constructor with message */
354
    VerificationException(String message);
355
    
356
    // Static Factory Methods
357
    /** Create exception for unmatched request pattern */
358
    static VerificationException forUnmatchedRequestPattern(Diff diff);
359
    
360
    /** Create exception for single unmatched request */
361
    static VerificationException forSingleUnmatchedRequest(Diff diff);
362
    
363
    /** Create exception with near miss information */
364
    static VerificationException forUnmatchedNearMisses(List<NearMiss> nearMisses);
365
    
366
    /** Create exception for multiple unmatched requests */
367
    static VerificationException forUnmatchedRequests(List<LoggedRequest> requests);
368
}
369

370
class Diff {
371
    /** Get difference description */
372
    String toString();
373
    
374
    /** Get actual request information */
375
    LoggedRequest getActualRequest();
376
    
377
    /** Get expected pattern information */
378
    RequestPattern getExpectedPattern();
379
}
380
```
381

382
**Usage Examples:**
383

384
```java
385
try {
386
    verify(exactly(1), getRequestedFor(urlEqualTo("/api/critical")));
387
} catch (VerificationException e) {
388
    System.err.println("Verification failed: " + e.getMessage());
389
    
390
    // Get diagnostic information
391
    List<LoggedRequest> unmatched = findUnmatchedRequests();
392
    List<NearMiss> nearMisses = findNearMissesForAllUnmatched();
393
    
394
    // Log details for debugging
395
    System.err.println("Unmatched requests: " + unmatched.size());
396
    for (NearMiss nearMiss : nearMisses) {
397
        System.err.println("Near miss: " + nearMiss.getDiff());
398
    }
399
}
400
```