0
# Response Validation
1

2
Comprehensive response validation capabilities including status codes, headers, cookies, body content validation, and data extraction using Hamcrest matchers and JSONPath/XPath expressions.
3

4
## Capabilities
5

6
### Response Specification Entry Points
7

8
Entry points for defining expected response characteristics.
9

10
```java { .api }
11
/**
12
 * Start building response expectations
13
 * @return Response specification for defining expected response characteristics
14
 */
15
static ResponseSpecification expect();
16
```
17

18
**Usage Examples:**
19

20
```java
21
// Using expect() for response validation
22
expect()
23
    .statusCode(200)
24
    .contentType(ContentType.JSON)
25
    .body("name", equalTo("John"))
26
.when()
27
    .get("/users/1");
28

29
// More common fluent pattern
30
given()
31
    .queryParam("id", 1)
32
.when()
33
    .get("/users")
34
.then()
35
    .statusCode(200)
36
    .body("users.size()", greaterThan(0));
37
```
38

39
### Status Code Validation
40

41
Methods for validating HTTP response status codes and status lines.
42

43
```java { .api }
44
interface ResponseSpecification {
45
    /**
46
     * Validate response status code
47
     * @param expectedStatusCode The expected HTTP status code
48
     * @return Updated response specification
49
     */
50
    ResponseSpecification statusCode(int expectedStatusCode);
51
    
52
    /**
53
     * Validate response status code with Hamcrest matcher
54
     * @param expectedStatusCode Hamcrest matcher for status code
55
     * @return Updated response specification
56
     */
57
    ResponseSpecification statusCode(Matcher<? super Integer> expectedStatusCode);
58
    
59
    /**
60
     * Validate response status line
61
     * @param expectedStatusLine The expected status line string
62
     * @return Updated response specification
63
     */
64
    ResponseSpecification statusLine(String expectedStatusLine);
65
    
66
    /**
67
     * Validate response status line with Hamcrest matcher
68
     * @param expectedStatusLine Hamcrest matcher for status line
69
     * @return Updated response specification
70
     */
71
    ResponseSpecification statusLine(Matcher<String> expectedStatusLine);
72
}
73

74
interface ValidatableResponse {
75
    /**
76
     * Assert response status code
77
     * @param expectedStatusCode The expected HTTP status code
78
     * @return Updated validatable response
79
     */
80
    ValidatableResponse statusCode(int expectedStatusCode);
81
    
82
    /**
83
     * Assert response status code with Hamcrest matcher
84
     * @param expectedStatusCode Hamcrest matcher for status code
85
     * @return Updated validatable response
86
     */
87
    ValidatableResponse statusCode(Matcher<? super Integer> expectedStatusCode);
88
    
89
    /**
90
     * Assert response status line
91
     * @param expectedStatusLine The expected status line
92
     * @return Updated validatable response
93
     */
94
    ValidatableResponse statusLine(String expectedStatusLine);
95
    
96
    /**
97
     * Assert response status line with Hamcrest matcher
98
     * @param expectedStatusLine Hamcrest matcher for status line
99
     * @return Updated validatable response
100
     */
101
    ValidatableResponse statusLine(Matcher<String> expectedStatusLine);
102
}
103
```
104

105
**Usage Examples:**
106

107
```java
108
// Exact status code
109
get("/users").then().statusCode(200);
110

111
// Status code with matcher
112
get("/users").then().statusCode(anyOf(is(200), is(201)));
113

114
// Status line validation
115
get("/users").then().statusLine("HTTP/1.1 200 OK");
116
get("/users").then().statusLine(containsString("200"));
117
```
118

119
### Body Content Validation
120

121
Methods for validating response body content using JSONPath, XPath, and Hamcrest matchers.
122

123
```java { .api }
124
interface ResponseSpecification {
125
    /**
126
     * Validate response body using path expression
127
     * @param path JSONPath or XPath expression
128
     * @param matcher Hamcrest matcher for the extracted value
129
     * @return Updated response specification
130
     */
131
    ResponseSpecification body(String path, Matcher<?> matcher);
132
    
133
    /**
134
     * Validate multiple body paths
135
     * @param path First path expression
136
     * @param matcher First matcher
137
     * @param additionalKeyMatcherPairs Additional path-matcher pairs
138
     * @return Updated response specification
139
     */
140
    ResponseSpecification body(String path, Matcher<?> matcher, Object... additionalKeyMatcherPairs);
141
    
142
    /**
143
     * Validate response body using path with arguments
144
     * @param path Path expression with placeholder arguments
145
     * @param arguments Arguments for path placeholders
146
     * @param matcher Hamcrest matcher for the extracted value
147
     * @param additionalKeyMatcherPairs Additional path-matcher pairs
148
     * @return Updated response specification
149
     */
150
    ResponseSpecification body(String path, List<Argument> arguments, Matcher<?> matcher, Object... additionalKeyMatcherPairs);
151
    
152
    /**
153
     * Validate entire response body content
154
     * @param matcher Hamcrest matcher for the complete body
155
     * @return Updated response specification
156
     */
157
    ResponseSpecification body(Matcher<?> matcher);
158
    
159
    /**
160
     * Validate response content (same as body)
161
     * @param path JSONPath or XPath expression
162
     * @param matcher Hamcrest matcher for the extracted value
163
     * @return Updated response specification
164
     */
165
    ResponseSpecification content(String path, Matcher<?> matcher);
166
    
167
    /**
168
     * Validate entire response content (same as body)
169
     * @param matcher Hamcrest matcher for the complete content
170
     * @return Updated response specification
171
     */
172
    ResponseSpecification content(Matcher<?> matcher);
173
}
174

175
interface ValidatableResponse {
176
    /**
177
     * Assert response body using path expression
178
     * @param path JSONPath or XPath expression
179
     * @param matcher Hamcrest matcher for the extracted value
180
     * @return Updated validatable response
181
     */
182
    ValidatableResponse body(String path, Matcher<?> matcher);
183
    
184
    /**
185
     * Assert multiple body paths
186
     * @param path First path expression
187
     * @param matcher First matcher
188
     * @param additionalKeyMatcherPairs Additional path-matcher pairs
189
     * @return Updated validatable response
190
     */
191
    ValidatableResponse body(String path, Matcher<?> matcher, Object... additionalKeyMatcherPairs);
192
    
193
    /**
194
     * Assert response body using path with arguments
195
     * @param path Path expression with placeholder arguments  
196
     * @param arguments Arguments for path placeholders
197
     * @param matcher Hamcrest matcher for the extracted value
198
     * @param additionalKeyMatcherPairs Additional path-matcher pairs
199
     * @return Updated validatable response
200
     */
201
    ValidatableResponse body(String path, List<Argument> arguments, Matcher<?> matcher, Object... additionalKeyMatcherPairs);
202
    
203
    /**
204
     * Assert entire response body content
205
     * @param matcher Hamcrest matcher for the complete body
206
     * @return Updated validatable response
207
     */
208
    ValidatableResponse body(Matcher<?> matcher);
209
}
210
```
211

212
**Usage Examples:**
213

214
```java
215
// JSONPath validation
216
get("/users/1").then()
217
    .body("name", equalTo("John"))
218
    .body("age", greaterThan(18))
219
    .body("emails.size()", is(2))
220
    .body("emails[0]", endsWith("@example.com"));
221

222
// Multiple path validation in one call
223
get("/users/1").then()
224
    .body("name", equalTo("John"),
225
          "age", greaterThan(18),
226
          "active", is(true));
227

228
// XPath validation for XML responses
229
get("/users/1.xml").then()
230
    .body("user.name", equalTo("John"))
231
    .body("user.@id", equalTo("123"))
232
    .body(hasXPath("/user/emails/email[1]", containsString("john")));
233

234
// Full body validation
235
get("/users/1").then()
236
    .body(containsString("John"))
237
    .body(not(containsString("password")));
238

239
// Path with arguments
240
get("/users").then()
241
    .body("users.find { it.name == '%s' }.age", withArgs("John"), greaterThan(18));
242
```
243

244
### Header Validation
245

246
Methods for validating HTTP response headers.
247

248
```java { .api }
249
interface ResponseSpecification {
250
    /**
251
     * Validate response header
252
     * @param headerName The header name to validate
253
     * @param expectedValueMatcher Hamcrest matcher for header value
254
     * @return Updated response specification
255
     */
256
    ResponseSpecification header(String headerName, Matcher<?> expectedValueMatcher);
257
    
258
    /**
259
     * Validate response header with string value
260
     * @param headerName The header name to validate
261
     * @param expectedValue Expected header value
262
     * @return Updated response specification
263
     */
264
    ResponseSpecification header(String headerName, String expectedValue);
265
    
266
    /**
267
     * Validate multiple response headers
268
     * @param firstHeaderName First header name
269
     * @param firstHeaderValueMatcher First header value matcher
270
     * @param headerNameValueMatchers Additional header name-matcher pairs
271
     * @return Updated response specification
272
     */
273
    ResponseSpecification headers(String firstHeaderName, Matcher<?> firstHeaderValueMatcher, Object... headerNameValueMatchers);
274
    
275
    /**
276
     * Validate response headers from map
277
     * @param expectedHeaders Map of header names to expected values or matchers
278
     * @return Updated response specification
279
     */
280
    ResponseSpecification headers(Map<String, ?> expectedHeaders);
281
}
282

283
interface ValidatableResponse {
284
    /**
285
     * Assert response header
286
     * @param headerName The header name to validate
287
     * @param expectedValueMatcher Hamcrest matcher for header value
288
     * @return Updated validatable response
289
     */
290
    ValidatableResponse header(String headerName, Matcher<?> expectedValueMatcher);
291
    
292
    /**
293
     * Assert response header with string value
294
     * @param headerName The header name to validate
295
     * @param expectedValue Expected header value
296
     * @return Updated validatable response
297
     */
298
    ValidatableResponse header(String headerName, String expectedValue);
299
    
300
    /**
301
     * Assert multiple response headers
302
     * @param firstHeaderName First header name
303
     * @param firstHeaderValueMatcher First header value matcher
304
     * @param headerNameValueMatchers Additional header name-matcher pairs
305
     * @return Updated validatable response
306
     */
307
    ValidatableResponse headers(String firstHeaderName, Matcher<?> firstHeaderValueMatcher, Object... headerNameValueMatchers);
308
    
309
    /**
310
     * Assert response headers from map
311
     * @param expectedHeaders Map of header names to expected values or matchers
312
     * @return Updated validatable response
313
     */
314
    ValidatableResponse headers(Map<String, ?> expectedHeaders);
315
}
316
```
317

318
**Usage Examples:**
319

320
```java
321
// Single header validation
322
get("/users").then()
323
    .header("Content-Type", "application/json")
324
    .header("Cache-Control", containsString("no-cache"))
325
    .header("X-Total-Count", notNullValue());
326

327
// Multiple headers
328
get("/users").then()
329
    .headers("Content-Type", "application/json",
330
             "Server", containsString("nginx"));
331

332
// Headers with map
333
Map<String, String> expectedHeaders = new HashMap<>();
334
expectedHeaders.put("Content-Type", "application/json");
335
expectedHeaders.put("Content-Encoding", "gzip");
336
get("/users").then().headers(expectedHeaders);
337
```
338

339
### Cookie Validation
340

341
Methods for validating HTTP response cookies.
342

343
```java { .api }
344
interface ResponseSpecification {
345
    /**
346
     * Validate response cookie
347
     * @param cookieName The cookie name to validate
348
     * @param expectedValueMatcher Hamcrest matcher for cookie value
349
     * @return Updated response specification
350
     */
351
    ResponseSpecification cookie(String cookieName, Matcher<?> expectedValueMatcher);
352
    
353
    /**
354
     * Validate response cookie with string value
355
     * @param cookieName The cookie name to validate
356
     * @param expectedValue Expected cookie value
357
     * @return Updated response specification
358
     */
359
    ResponseSpecification cookie(String cookieName, String expectedValue);
360
    
361
    /**
362
     * Validate multiple response cookies
363
     * @param firstCookieName First cookie name
364
     * @param firstCookieValueMatcher First cookie value matcher
365
     * @param cookieNameValueMatchers Additional cookie name-matcher pairs
366
     * @return Updated response specification
367
     */
368
    ResponseSpecification cookies(String firstCookieName, Matcher<?> firstCookieValueMatcher, Object... cookieNameValueMatchers);
369
    
370
    /**
371
     * Validate response cookies from map
372
     * @param expectedCookies Map of cookie names to expected values or matchers
373
     * @return Updated response specification
374
     */
375
    ResponseSpecification cookies(Map<String, ?> expectedCookies);
376
}
377

378
interface ValidatableResponse {
379
    /**
380
     * Assert response cookie
381
     * @param cookieName The cookie name to validate
382
     * @param expectedValueMatcher Hamcrest matcher for cookie value
383
     * @return Updated validatable response
384
     */
385
    ValidatableResponse cookie(String cookieName, Matcher<?> expectedValueMatcher);
386
    
387
    /**
388
     * Assert response cookie with string value
389
     * @param cookieName The cookie name to validate
390
     * @param expectedValue Expected cookie value
391
     * @return Updated validatable response
392
     */
393
    ValidatableResponse cookie(String cookieName, String expectedValue);
394
    
395
    /**
396
     * Assert multiple response cookies
397
     * @param firstCookieName First cookie name
398
     * @param firstCookieValueMatcher First cookie value matcher
399
     * @param cookieNameValueMatchers Additional cookie name-matcher pairs
400
     * @return Updated validatable response
401
     */
402
    ValidatableResponse cookies(String firstCookieName, Matcher<?> firstCookieValueMatcher, Object... cookieNameValueMatchers);
403
    
404
    /**
405
     * Assert response cookies from map
406
     * @param expectedCookies Map of cookie names to expected values or matchers
407
     * @return Updated validatable response
408
     */
409
    ValidatableResponse cookies(Map<String, ?> expectedCookies);
410
}
411
```
412

413
### Content Type Validation
414

415
Methods for validating response content type.
416

417
```java { .api }
418
interface ResponseSpecification {
419
    /**
420
     * Validate response content type
421
     * @param contentType Expected content type
422
     * @return Updated response specification
423
     */
424
    ResponseSpecification contentType(ContentType contentType);
425
    
426
    /**
427
     * Validate response content type with string
428
     * @param contentType Expected content type as string
429
     * @return Updated response specification
430
     */
431
    ResponseSpecification contentType(String contentType);
432
    
433
    /**
434
     * Validate response content type with matcher
435
     * @param contentType Hamcrest matcher for content type
436
     * @return Updated response specification
437
     */
438
    ResponseSpecification contentType(Matcher<String> contentType);
439
}
440

441
interface ValidatableResponse {
442
    /**
443
     * Assert response content type
444
     * @param contentType Expected content type
445
     * @return Updated validatable response
446
     */
447
    ValidatableResponse contentType(ContentType contentType);
448
    
449
    /**
450
     * Assert response content type with string
451
     * @param contentType Expected content type as string
452
     * @return Updated validatable response
453
     */
454
    ValidatableResponse contentType(String contentType);
455
    
456
    /**
457
     * Assert response content type with matcher
458
     * @param contentType Hamcrest matcher for content type
459
     * @return Updated validatable response
460
     */
461
    ValidatableResponse contentType(Matcher<String> contentType);
462
}
463
```
464

465
### Response Time Validation
466

467
Methods for validating response time.
468

469
```java { .api }
470
interface ValidatableResponse {
471
    /**
472
     * Assert response time
473
     * @param matcher Hamcrest matcher for response time in milliseconds
474
     * @return Updated validatable response
475
     */
476
    ValidatableResponse time(Matcher<Long> matcher);
477
    
478
    /**
479
     * Assert response time with time unit
480
     * @param matcher Hamcrest matcher for response time
481
     * @param timeUnit Time unit for the matcher
482
     * @return Updated validatable response
483
     */
484
    ValidatableResponse time(Matcher<Long> matcher, TimeUnit timeUnit);
485
}
486
```
487

488
**Usage Examples:**
489

490
```java
491
// Response time validation
492
get("/users").then()
493
    .time(lessThan(2000L)) // Less than 2 seconds
494
    .time(lessThan(5L), TimeUnit.SECONDS); // Less than 5 seconds
495
```
496

497
### Data Extraction
498

499
Methods for extracting data from responses for further processing.
500

501
```java { .api }
502
interface ValidatableResponse {
503
    /**
504
     * Extract data from the response for further processing
505
     * @return Extractable response interface
506
     */
507
    ExtractableResponse<Response> extract();
508
}
509

510
interface ExtractableResponse<T> {
511
    /**
512
     * Extract the complete response
513
     * @return The response object
514
     */
515
    T response();
516
    
517
    /**
518
     * Extract response body as string
519
     * @return Response body as string
520
     */
521
    String asString();
522
    
523
    /**
524
     * Extract response body as byte array
525
     * @return Response body as byte array
526
     */
527
    byte[] asByteArray();
528
    
529
    /**
530
     * Extract response body as input stream
531
     * @return Response body as input stream
532
     */
533
    InputStream asInputStream();
534
    
535
    /**
536
     * Extract and deserialize response body to object
537
     * @param cls Class to deserialize to
538
     * @return Deserialized object
539
     */
540
    <T> T as(Class<T> cls);
541
    
542
    /**
543
     * Extract value using path expression
544
     * @param path JSONPath or XPath expression
545
     * @return Extracted value
546
     */
547
    <T> T path(String path);
548
    
549
    /**
550
     * Extract value using path expression with arguments
551
     * @param path Path expression with placeholders
552
     * @param arguments Arguments for placeholders
553
     * @return Extracted value
554
     */
555
    <T> T path(String path, Object... arguments);
556
    
557
    /**
558
     * Extract JSON path value
559
     * @param path JSONPath expression
560
     * @return Extracted value
561
     */
562
    <T> T jsonPath(String path);
563
    
564
    /**
565
     * Extract XML path value
566
     * @param path XPath expression
567
     * @return Extracted value
568
     */
569
    <T> T xmlPath(String path);
570
    
571
    /**
572
     * Extract response header value
573
     * @param name Header name
574
     * @return Header value
575
     */
576
    String header(String name);
577
    
578
    /**
579
     * Extract response cookie value
580
     * @param name Cookie name
581
     * @return Cookie value
582
     */
583
    String cookie(String name);
584
    
585
    /**
586
     * Extract response status code
587
     * @return HTTP status code
588
     */
589
    int statusCode();
590
}
591
```
592

593
**Usage Examples:**
594

595
```java
596
// Extract complete response
597
Response response = get("/users/1").then().extract().response();
598

599
// Extract specific values
600
String name = get("/users/1").then().extract().path("name");
601
int age = get("/users/1").then().extract().path("age");
602
List<String> emails = get("/users/1").then().extract().path("emails");
603

604
// Extract and deserialize to object
605
User user = get("/users/1").then().extract().as(User.class);
606

607
// Extract headers and cookies
608
String contentType = get("/users").then().extract().header("Content-Type");
609
String sessionId = post("/login").then().extract().cookie("JSESSIONID");
610

611
// Extract status code
612
int statusCode = get("/users/1").then().extract().statusCode();
613
```
614

615
## Types
616

617
```java { .api }
618
// Main response validation interfaces
619
interface ResponseSpecification {
620
    // All validation methods listed above
621
}
622

623
interface ValidatableResponse extends Validatable<ValidatableResponse, Response> {
624
    // All assertion methods listed above
625
}
626

627
interface ExtractableResponse<T> {
628
    // All extraction methods listed above
629
}
630

631
// Argument for path expressions
632
class Argument {
633
    static Argument arg(Object argument);
634
    Object getArgument();
635
}
636

637
// Content type enumeration (same as in request building)
638
enum ContentType {
639
    JSON("application/json"),
640
    XML("application/xml"),
641
    HTML("text/html"),
642
    TEXT("text/plain"),
643
    URLENC("application/x-www-form-urlencoded"),
644
    MULTIPART("multipart/form-data"),
645
    BINARY("application/octet-stream"),
646
    ANY("*/*");
647
}
648
```