io.restassured.builder

Class ResponseSpecBuilder

java.lang.Object

io.restassured.builder.ResponseSpecBuilder

public class ResponseSpecBuilder
extends Object

You can use the builder to construct a response specification. The specification can be used as e.g.

 ResponseSpecification responseSpec = new ResponseSpecBuilder().expectStatusCode(200).build();
 RequestSpecification requestSpec = new RequestSpecBuilder().addParam("parameter1", "value1").build();

 given(responseSpec, requestSpec).post("/something");
 

or

 ResponseSpecification responseSpec = new ResponseSpecBuilder().expectStatusCode(200).build();

 expect().
         spec(responseSpec).
         body("x.y.z", equalTo("something")).
 when().
        get("/something");
 

Constructor Summary

Constructors

Constructor and Description
ResponseSpecBuilder()

Method Summary

Modifier and Type	Method and Description
ResponseSpecBuilder	addResponseSpecification(ResponseSpecification specification) Merge this builder with settings from another specification.
ResponseSpecBuilder	appendRootPath(String pathToAppend) Append the given path to the root path of the response body so that you don't need to write the entire path for each expectation.
ResponseSpecBuilder	appendRootPath(String pathToAppend, List<Argument> arguments) Append the given path to the root path with arguments supplied of the response body so that you don't need to write the entire path for each expectation.
ResponseSpecification	build() Build the response specification.
ResponseSpecBuilder	detachRootPath(String pathToDetach) Detach the given path from the root path.
ResponseSpecBuilder	expectBody(org.hamcrest.Matcher<?> matcher) Expect that the response body conforms to one or more Hamcrest matchers.
ResponseSpecBuilder	expectBody(String path, List<Argument> arguments, org.hamcrest.Matcher<?> matcher) Same as expectBody(String, org.hamcrest.Matcher) expect that you can pass arguments to the path.
ResponseSpecBuilder	expectBody(String path, org.hamcrest.Matcher<?> matcher) Expect that the JSON or XML response content conforms to one or more Hamcrest matchers.
ResponseSpecBuilder	expectContent(org.hamcrest.Matcher<?> matcher) Deprecated. Use expectBody(Matcher) instead
ResponseSpecBuilder	expectContent(String path, List<Argument> arguments, org.hamcrest.Matcher<?> matcher) Deprecated. Use expectBody(String, List, Matcher) instead
ResponseSpecBuilder	expectContent(String path, org.hamcrest.Matcher<?> matcher) Deprecated. Use expectBody(String, Matcher) instead
ResponseSpecBuilder	expectContentType(ContentType contentType) Set the response content type to be contentType.
ResponseSpecBuilder	expectContentType(String contentType) Set the response content type to be contentType.
ResponseSpecBuilder	expectCookie(String cookieName) Expect that a cookie exist in the response, regardless of value (it may have no value at all).
ResponseSpecBuilder	expectCookie(String cookieName, org.hamcrest.Matcher<String> expectedValueMatcher) Expect that a response cookie matches the supplied cookie name and hamcrest matcher.
ResponseSpecBuilder	expectCookie(String cookieName, String expectedValue) Expect that a response cookie matches the supplied name and value.
ResponseSpecBuilder	expectCookies(Map<String,Object> expectedCookies) Expect that response cookies matches those specified in a Map.
ResponseSpecBuilder	expectHeader(String headerName, org.hamcrest.Matcher<String> expectedValueMatcher) Expect that a response header matches the supplied header name and hamcrest matcher.
ResponseSpecBuilder	expectHeader(String headerName, String expectedValue) Expect that a response header matches the supplied name and value.
ResponseSpecBuilder	expectHeaders(Map<String,Object> expectedHeaders) Expect that response headers matches those specified in a Map.
ResponseSpecBuilder	expectResponseTime(org.hamcrest.Matcher<Long> matcher) Validate that the response time (in milliseconds) matches the supplied matcher.
ResponseSpecBuilder	expectResponseTime(org.hamcrest.Matcher<Long> matcher, TimeUnit timeUnit) Validate that the response time matches the supplied matcher and time unit.
ResponseSpecBuilder	expectStatusCode(int expectedStatusCode) Expect that the response status code matches an integer.
ResponseSpecBuilder	expectStatusCode(org.hamcrest.Matcher<Integer> expectedStatusCode) Expect that the response status code matches the given Hamcrest matcher.
ResponseSpecBuilder	expectStatusLine(org.hamcrest.Matcher<String> expectedStatusLine) Expect that the response status line matches the given Hamcrest matcher.
ResponseSpecBuilder	expectStatusLine(String expectedStatusLine) Expect that the response status line matches the given String.
ResponseSpecBuilder	noRootPath() Reset the root path of the response body so that you don't need to write the entire path for each expectation.
ResponseSpecBuilder	registerParser(String contentType, Parser parser) Register a content-type to be parsed using a predefined parser.
ResponseSpecBuilder	rootPath(String rootPath) Set the root path of the response body so that you don't need to write the entire path for each expectation.
ResponseSpecBuilder	rootPath(String rootPath, List<Argument> arguments) Set the root path of the response body so that you don't need to write the entire path for each expectation.
ResponseSpecBuilder	setDefaultParser(Parser parser) Register a default predefined parser that will be used if no other parser (registered or pre-defined) matches the response content-type.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

ResponseSpecBuilder

public ResponseSpecBuilder()

Method Detail

expectContent

@Deprecated
public ResponseSpecBuilder expectContent(org.hamcrest.Matcher<?> matcher)

Deprecated. Use expectBody(Matcher) instead

Expect that the response content conforms to one or more Hamcrest matchers.

Parameters:

matcher - The hamcrest matcher that must response content must match.

Returns:

The builder

expectContent

@Deprecated
public ResponseSpecBuilder expectContent(String path,
                                                     org.hamcrest.Matcher<?> matcher)

Deprecated. Use expectBody(String, Matcher) instead

Expect that the JSON or XML response content conforms to one or more Hamcrest matchers.

JSON example

Assume that a GET request to "/lotto" returns a JSON response containing:

 { "lotto":{
   "lottoId":5,
   "winning-numbers":[2,45,34,23,7,5,3],
   "winners":[{
     "winnerId":23,
     "numbers":[2,45,34,23,3,5]
   },{
     "winnerId":54,
     "numbers":[52,3,12,11,18,22]
   }]
  }}
 

You can verify that the lottoId is equal to 5 like this:

 ResponseSpecBuilder builder = new ResponseSpecBuilder();
 builder.expectContent("lotto.lottoId", equalTo(5));
 

Parameters:

matcher - The hamcrest matcher that the response content must match.

Returns:

The builder

expectContent

@Deprecated
public ResponseSpecBuilder expectContent(String path,
                                                     List<Argument> arguments,
                                                     org.hamcrest.Matcher<?> matcher)

Deprecated. Use expectBody(String, List, Matcher) instead

Same as expectContent(String, org.hamcrest.Matcher) expect that you can pass arguments to the path. This is useful in situations where you have e.g. pre-defined variables that constitutes the path:

 String someSubPath = "else";
 int index = 1;
 expect().body("something.%s[%d]", withArgs(someSubPath, index), equalTo("some value")). ..
 

or if you have complex root paths and don't wish to duplicate the path for small variations:

 expect().
          root("filters.filterConfig[%d].filterConfigGroups.find { it.name == 'Gold' }.includes").
          body(withArgs(0), hasItem("first")).
          body(withArgs(1), hasItem("second")).
          ..
 

The path and arguments follows the standard formatting syntax of Java.

Note that withArgs can be statically imported from the io.restassured.RestAssured class.

Parameters:

path - The body path

matcher - The hamcrest matcher that must response body must match.

Returns:

the response specification

See Also:

expectBody(String, Matcher)

expectStatusCode

public ResponseSpecBuilder expectStatusCode(org.hamcrest.Matcher<Integer> expectedStatusCode)

Expect that the response status code matches the given Hamcrest matcher.

Parameters:

expectedStatusCode - The expected status code matcher.

Returns:

The builder

expectStatusCode

public ResponseSpecBuilder expectStatusCode(int expectedStatusCode)

Expect that the response status code matches an integer.

Parameters:

expectedStatusCode - The expected status code.

Returns:

The builder

expectStatusLine

public ResponseSpecBuilder expectStatusLine(org.hamcrest.Matcher<String> expectedStatusLine)

Expect that the response status line matches the given Hamcrest matcher.

Parameters:

expectedStatusLine - The expected status line matcher.

Returns:

The builder

expectStatusLine

public ResponseSpecBuilder expectStatusLine(String expectedStatusLine)

Expect that the response status line matches the given String.

Parameters:

expectedStatusLine - The expected status line.

Returns:

The builder

expectHeaders

public ResponseSpecBuilder expectHeaders(Map<String,Object> expectedHeaders)

Expect that response headers matches those specified in a Map.

E.g. expect that the response of the GET request to "/something" contains header headerName1=headerValue1 and headerName2=headerValue2:

 Map expectedHeaders = new HashMap();
 expectedHeaders.put("headerName1", "headerValue1"));
 expectedHeaders.put("headerName2", "headerValue2");
 

You can also use Hamcrest matchers:

 Map expectedHeaders = new HashMap();
 expectedHeaders.put("Content-Type", containsString("charset=UTF-8"));
 expectedHeaders.put("Content-Length", "160");
 

Parameters:

expectedHeaders - The Map of expected response headers

Returns:

The builder

expectHeader

public ResponseSpecBuilder expectHeader(String headerName,
                                        org.hamcrest.Matcher<String> expectedValueMatcher)

Expect that a response header matches the supplied header name and hamcrest matcher.

Parameters:

headerName - The name of the expected header

expectedValueMatcher - The Hamcrest matcher that must conform to the value

Returns:

The builder

expectHeader

public ResponseSpecBuilder expectHeader(String headerName,
                                        String expectedValue)

Expect that a response header matches the supplied name and value.

Parameters:

headerName - The name of the expected header

expectedValue - The value of the expected header

Returns:

The builder

expectCookies

public ResponseSpecBuilder expectCookies(Map<String,Object> expectedCookies)

Expect that response cookies matches those specified in a Map.

E.g. expect that the response of the GET request to "/something" contains cookies cookieName1=cookieValue1 and cookieName2=cookieValue2:

 Map expectedCookies = new HashMap();
 expectedCookies.put("cookieName1", "cookieValue1"));
 expectedCookies.put("cookieName2", "cookieValue2");
 

You can also use Hamcrest matchers:

 Map expectedCookies = new HashMap();
 expectedCookies.put("cookieName1", containsString("Value1"));
 expectedCookies.put("cookieName2", "cookieValue2");
 

Parameters:

expectedCookies - A Map of expected response cookies

Returns:

The builder

expectCookie

public ResponseSpecBuilder expectCookie(String cookieName,
                                        org.hamcrest.Matcher<String> expectedValueMatcher)

Expect that a response cookie matches the supplied cookie name and hamcrest matcher.

E.g. cookieName1=cookieValue1

Parameters:

cookieName - The name of the expected cookie

expectedValueMatcher - The Hamcrest matcher that must conform to the value

Returns:

The builder

expectCookie

public ResponseSpecBuilder expectCookie(String cookieName,
                                        String expectedValue)

Expect that a response cookie matches the supplied name and value.

Parameters:

cookieName - The name of the expected cookie

expectedValue - The value of the expected cookie

Returns:

The builder

expectCookie

public ResponseSpecBuilder expectCookie(String cookieName)

Expect that a cookie exist in the response, regardless of value (it may have no value at all).

Parameters:

cookieName - the cookie to validate that it exists

Returns:

the builder

expectResponseTime

public ResponseSpecBuilder expectResponseTime(org.hamcrest.Matcher<Long> matcher)

Validate that the response time (in milliseconds) matches the supplied matcher.

Parameters:

matcher - The matcher

Returns:

the builder

expectResponseTime

public ResponseSpecBuilder expectResponseTime(org.hamcrest.Matcher<Long> matcher,
                                              TimeUnit timeUnit)

Validate that the response time matches the supplied matcher and time unit.

Parameters:

matcher - The matcher

timeUnit - The timeout

Returns:

the builder

rootPath

public ResponseSpecBuilder rootPath(String rootPath)

Set the root path of the response body so that you don't need to write the entire path for each expectation. E.g. instead of writing:

 expect().
          body("x.y.firstName", is(..)).
          body("x.y.lastName", is(..)).
          body("x.y.age", is(..)).
          body("x.y.gender", is(..)).
 when().
          get(..);
 

you can use a root path and do:

 expect().
          rootPath("x.y").
          body("firstName", is(..)).
          body("lastName", is(..)).
          body("age", is(..)).
          body("gender", is(..)).
 when().
          get(..);
 

Parameters:

rootPath - The root path to use.

rootPath

public ResponseSpecBuilder rootPath(String rootPath,
                                    List<Argument> arguments)

Set the root path of the response body so that you don't need to write the entire path for each expectation. The same as rootPath(String) but also provides a way to defined arguments.

Parameters:

rootPath - The root path to use.

arguments - The arguments.

See Also:

ResponseSpecification.rootPath(String, java.util.List)

appendRootPath

public ResponseSpecBuilder appendRootPath(String pathToAppend)

Append the given path to the root path of the response body so that you don't need to write the entire path for each expectation. E.g. instead of writing:

 expect().
          root("x.y").
          body("age", is(..)).
          body("gender", is(..)).
          body("name.firstName", is(..)).
          body("name.lastName", is(..)).
 when().
          get(..);
 

you can use a append root and do:

 expect().
          root("x.y").
          body("age", is(..)).
          body("gender", is(..)).
          appendRoot("name").
          body("firstName", is(..)).
          body("lastName", is(..)).
 when().
          get(..);
 

Parameters:

pathToAppend - The root path to append.

appendRootPath

public ResponseSpecBuilder appendRootPath(String pathToAppend,
                                          List<Argument> arguments)

Append the given path to the root path with arguments supplied of the response body so that you don't need to write the entire path for each expectation. This is mainly useful when you have parts of the path defined in variables. E.g. instead of writing:

 String namePath = "name";
 expect().
          root("x.y").
          body("age", is(..)).
          body("gender", is(..)).
          body(namePath + "first", is(..)).
          body(namePath + "last", is(..)).
 when().
          get(..);
 

you can use a append root and do:

 String namePath = "name";
 expect().
          root("x.y").
          body("age", is(..)).
          body("gender", is(..)).
          appendRoot("%s", withArgs(namePath)).
          body("first", is(..)).
          body("last", is(..)).
 when().
          get(..);
 

Parameters:

pathToAppend - The root path to use. The path and arguments follows the standard formatting syntax of Java.

noRootPath

public ResponseSpecBuilder noRootPath()

Reset the root path of the response body so that you don't need to write the entire path for each expectation. For example:

 expect().
          root("x.y").
          body("firstName", is(..)).
          body("lastName", is(..)).
          noRoot()
          body("z.something1", is(..)).
          body("w.something2", is(..)).
 when().
          get(..);
 

This is the same as calling rootPath("") but more expressive.

See Also:

rootPath(String)

detachRootPath

public ResponseSpecBuilder detachRootPath(String pathToDetach)

Detach the given path from the root path. E.g. instead of writing:

 when().
          get(..);
 then().
          root("x.y").
          body("age", is(..)).
          body("gender", is(..)).
          root("x").
          body("firstName", is(..)).
          body("lastName", is(..)).
 

you can use a append root and do:

 when().
          get(..);
 then().
          root("x.y").
          body("age", is(..)).
          body("gender", is(..)).
          detachRoot("y").
          body("firstName", is(..)).
          body("lastName", is(..)).
 

Parameters:

pathToDetach - The root path to detach.

expectContentType

public ResponseSpecBuilder expectContentType(ContentType contentType)

Set the response content type to be contentType.

Note that this will affect the way the response is decoded. E,g. if you can't use JSON/XML matching (see e.g. expectBody(String, org.hamcrest.Matcher)) if you specify a content-type of "text/plain". If you don't specify the response content type REST Assured will automatically try to figure out which content type to use.

Parameters:

contentType - The content type of the response.

Returns:

The builder

expectContentType

public ResponseSpecBuilder expectContentType(String contentType)

Set the response content type to be contentType.

Note that this will affect the way the response is decoded. E,g. if you can't use JSON/XML matching (see e.g. expectBody(String, org.hamcrest.Matcher)) if you specify a content-type of "text/plain". If you don't specify the response content type REST Assured will automatically try to figure out which content type to use.

Parameters:

contentType - The content type of the response.

Returns:

The builder

expectBody

public ResponseSpecBuilder expectBody(org.hamcrest.Matcher<?> matcher)

Expect that the response body conforms to one or more Hamcrest matchers.

Parameters:

matcher - The hamcrest matcher that must response content must match.

Returns:

The builder

expectBody

public ResponseSpecBuilder expectBody(String path,
                                      org.hamcrest.Matcher<?> matcher)

Expect that the JSON or XML response content conforms to one or more Hamcrest matchers.

JSON example

Assume that a GET request to "/lotto" returns a JSON response containing:

 { "lotto":{
   "lottoId":5,
   "winning-numbers":[2,45,34,23,7,5,3],
   "winners":[{
     "winnerId":23,
     "numbers":[2,45,34,23,3,5]
   },{
     "winnerId":54,
     "numbers":[52,3,12,11,18,22]
   }]
  }}
 

You can verify that the lottoId is equal to 5 like this:

 ResponseSpecBuilder builder = new ResponseSpecBuilder();
 builder.expectBody("lotto.lottoId", equalTo(5));
 

Parameters:

matcher - The hamcrest matcher that the response content must match.

Returns:

The builder

expectBody

public ResponseSpecBuilder expectBody(String path,
                                      List<Argument> arguments,
                                      org.hamcrest.Matcher<?> matcher)

Same as expectBody(String, org.hamcrest.Matcher) expect that you can pass arguments to the path. This is useful in situations where you have e.g. pre-defined variables that constitutes the path:

 String someSubPath = "else";
 int index = 1;
 expect().body("something.%s[%d]", withArgs(someSubPath, index), equalTo("some value")). ..
 

or if you have complex root paths and don't wish to duplicate the path for small variations:

 expect().
          root("filters.filterConfig[%d].filterConfigGroups.find { it.name == 'Gold' }.includes").
          body(withArgs(0), hasItem("first")).
          body(withArgs(1), hasItem("second")).
          ..
 

The path and arguments follows the standard formatting syntax of Java.

Note that withArgs can be statically imported from the io.restassured.RestAssured class.

Parameters:

path - The body path

matcher - The hamcrest matcher that must response body must match.

Returns:

the response specification

See Also:

expectBody(String, org.hamcrest.Matcher)

addResponseSpecification

public ResponseSpecBuilder addResponseSpecification(ResponseSpecification specification)

Merge this builder with settings from another specification. Note that the supplied specification can overwrite data in the current specification. The following settings are overwritten:

• Content type
• Root pathStatus code
• Status line

The following settings are merged:

• Response body expectations
• Cookies
• Headers

Parameters:

specification - The specification the add.

Returns:

The builder

registerParser

public ResponseSpecBuilder registerParser(String contentType,
                                          Parser parser)

Register a content-type to be parsed using a predefined parser. E.g. let's say you want parse content-type application/vnd.uoml+xml with the XML parser to be able to verify the response using the XML dot notations:

 expect().body("document.child", equalsTo("something"))..
 

Since application/vnd.uoml+xml is not registered to be processed by the XML parser by default you need to explicitly tell REST Assured to use this parser before making the request:

 expect().parser("application/vnd.uoml+xml", Parser.XML").when(). ..;
 

You can also specify by default by using:

 RestAssured.registerParser("application/vnd.uoml+xml, Parser.XML");
 

Parameters:

contentType - The content-type to register

parser - The parser to use when verifying the response.

Returns:

The builder

setDefaultParser

public ResponseSpecBuilder setDefaultParser(Parser parser)

Register a default predefined parser that will be used if no other parser (registered or pre-defined) matches the response content-type. E.g. let's say that for some reason no content-type is defined in the response but the content is nevertheless JSON encoded. To be able to expect the content in REST Assured you need to set the default parser:

 expect().defaultParser(Parser.JSON).when(). ..;
 

You can also specify it for every response by using:

 RestAssured.defaultParser(Parser.JSON);
 

Parameters:

parser - The parser to use when verifying the response if no other parser is found for the response content-type.

build

public ResponseSpecification build()

Build the response specification.

Returns:

The assembled response specification