io.restassured.response.ValidatableResponseOptions Maven / Gradle / Ivy
Go to download
Show more of this group Show more artifacts with this name
Show all versions of rest-assured Show documentation
Show all versions of rest-assured Show documentation
Java DSL for easy testing of REST services
/*
* Copyright 2016 the original author or authors.
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
package io.restassured.response;
import io.restassured.function.RestAssuredFunction;
import io.restassured.http.ContentType;
import io.restassured.http.Cookie;
import io.restassured.matcher.DetailedCookieMatcher;
import io.restassured.matcher.ResponseAwareMatcher;
import io.restassured.matcher.RestAssuredMatchers;
import io.restassured.parsing.Parser;
import io.restassured.specification.Argument;
import io.restassured.specification.ResponseSpecification;
import org.hamcrest.Matcher;
import java.util.List;
import java.util.Map;
import java.util.concurrent.TimeUnit;
/**
* A validatable response of a request made by REST Assured.
*
* Usage example:
*
* get("/lotto").then().body("lotto.lottoId", is(5));
*
*
*/
public interface ValidatableResponseOptions, R extends ResponseBody & ResponseOptions> {
/**
* Validate that the response content conforms to one or more Hamcrest matchers. E.g.
*
* // Validate that the response content (body) contains the string "winning-numbers"
* get("/lotto").then().content(containsString("winning-numbers"));
*
* // Validate that the response content (body) contains the string "winning-numbers" and "winners"
* get("/lotto").then().assertThat().content(containsString("winning-numbers"), containsString("winners"));
*
*
* @param matcher The hamcrest matcher that must response content must match.
* @param additionalMatchers Optionally additional hamcrest matchers that must return true.
* @return the response specification
*/
T content(Matcher matcher, Matcher... additionalMatchers);
/**
* This as special kind of validation that is mainly useful when you've specified a root path with an argument placeholder.
* For example:
*
* get(..).then().assertThat().
* root("x.%s"). // Root path with a placeholder
* content(withArgs("firstName"), equalTo(..)).
* content(withArgs("lastName"), equalTo(..)).
*
*
* Note that this is the same as doing:
*
* get(..).then().assertThat().
* root("x.%s"). // Root path with a placeholder
* body(withArgs("firstName"), equalTo(..)).
* body(withArgs("lastName"), equalTo(..)).
*
*
*
* Note that this method is the same as {@link #body(java.util.List, org.hamcrest.Matcher, Object...)} but with a method name.
*
*
* @param arguments The arguments to apply to the root path.
* @param matcher The hamcrest matcher that must response body must match.
* @param additionalKeyMatcherPairs Optionally additional hamcrest matchers that must return true.
* @return the response specification
* @see #body(String, org.hamcrest.Matcher, Object...)
*/
T content(List arguments, Matcher matcher, Object... additionalKeyMatcherPairs);
/**
* Compare a path in the response body to something available in the response using arguments when root path is used.
* For example imagine that a resource "/x" returns the following JSON document:
*
* {
* "data" : {
* "user1" : {
* "userId" : "my-id1",
* "href" : "http://localhost:8080/my-id1"
* },
* "user2" : {
* "userId" : "my-id2",
* "href" : "http://localhost:8080/my-id2"
* },
* }
* }
*
* you can then verify the href using:
*
* when().
* get("/x").
* then().
* root("data.%s").
* content(withArgs("user1"), new ResponseAwareMatcher() {
* public Matcher matcher(Response response) {
* return equalTo("http://localhost:8080/" + response.path("userId"));
* }
* });
*
* Note that you can also use some of the predefined methods in {@link RestAssuredMatchers}.
*
* Note that this method is the same as {@link #body(java.util.List, ResponseAwareMatcher)} expect for syntactic differences.
*
*
* @param responseAwareMatcher The {@link ResponseAwareMatcher} that creates the Hamcrest matcher.
* @return the response specification
* @see #content(String, ResponseAwareMatcher)
* @see RestAssuredMatchers#endsWithPath(String)
* @see RestAssuredMatchers#startsWithPath(String)
* @see RestAssuredMatchers#containsPath(String)
* @see RestAssuredMatchers#equalToPath(String)
*/
T content(List arguments, ResponseAwareMatcher responseAwareMatcher);
/**
* Validate 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:
*
* get("/lotto").then().assertThat().content("lotto.lottoId", equalTo(5));
*
*
* You can also verify that e.g. one of the the winning numbers is 45.
*
* get("/lotto").then().content("lotto.winning-numbers", hasItem(45));
*
*
* Or both at the same time:
*
* get("/lotto").then().content("lotto.lottoId", equalTo(5)).and().content("lotto.winning-numbers", hasItem(45));
*
*
* or a slightly short version:
*
* get("/lotto").then().content("lotto.lottoId", equalTo(5), "lotto.winning-numbers", hasItem(45));
*
*
* XML example
*
* Assume that a GET request to "/xml" returns a XML response containing:
*
* <greeting>
* <firstName>John</firstName>
* <lastName>Doe</lastName>
* </greeting>
*
*
*
* You can now verify that the firstName is equal to "John" like this:
*
* get("/xml").then().content("greeting.firstName", equalTo("John"));
*
*
* To verify both the first name and last name you can do like this:
*
* get("/xml").then().content("greeting.firstName", equalTo("John")).and().content("greeting.lastName", equalTo("Doe"));
*
*
* Or the slightly shorter version of:
*
* get("/xml").then().content("greeting.firstName", equalTo("John"), "greeting.lastName", equalTo("Doe"));
*
* Notes
*
* Note that if the response content type is not of type application/xml or application/json you
* cannot use this verification.
*
*
*
* The only difference between the content and body methods are of syntactic nature.
*
*
* @param matcher The hamcrest matcher that must response content must match.
* @param additionalKeyMatcherPairs Optionally additional hamcrest matchers that must return true.
* @return the response specification
*/
T content(String key, Matcher matcher, Object... additionalKeyMatcherPairs);
/**
* Same as {@link #body(String, org.hamcrest.Matcher, Object...)} expect that you can pass arguments to the key. This
* is useful in situations where you have e.g. pre-defined variables that constitutes the key:
*
* String someSubPath = "else";
* int index = 1;
* get("/x").then().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:
*
* get("/x").then().
* root("filters.filterConfig[%d].filterConfigGroups.find { it.name == 'Gold' }.includes").
* body(withArgs(0), hasItem("first")).
* body(withArgs(1), hasItem("second")).
* ..
*
*
* The key and arguments follows the standard formatting syntax of Java.
*
* Note that withArgs can be statically imported from the io.restassured.RestAssured class.
*
*
* @param path The body path
* @param arguments The arguments to apply to the key
* @param matcher The hamcrest matcher that must response body must match.
* @param additionalKeyMatcherPairs Optionally additional hamcrest matchers that must return true.
* @return the response specification
* @see #body(String, org.hamcrest.Matcher, Object...)
*/
T body(String path, List arguments, Matcher matcher, Object... additionalKeyMatcherPairs);
/**
* This as special kind of expectation that is mainly useful when you've specified a root path with an argument placeholder.
* For example:
*
* get(..).then().
* root("x.%s"). // Root path with a placeholder
* body(withArgs("firstName"), equalTo(..)).
* body(withArgs("lastName"), equalTo(..)).
*
*
* Note that this is the same as doing:
*
* get(..).then().
* root("x.%s"). // Root path with a placeholder
* content(withArgs("firstName"), equalTo(..)).
* content(withArgs("lastName"), equalTo(..)).
*
*
*
* Note that this method is the same as {@link #content(java.util.List, org.hamcrest.Matcher, Object...)} but with a method name.
*
*
* @param arguments The arguments to apply to the root path.
* @param matcher The hamcrest matcher that must response body must match.
* @param additionalKeyMatcherPairs Optionally additional hamcrest matchers that must return true.
* @return the response specification
* @see #body(String, org.hamcrest.Matcher, Object...)
*/
T body(List arguments, Matcher matcher, Object... additionalKeyMatcherPairs);
/**
* Compare a path in the response body to something available in the response using arguments when root path is used.
* For example imagine that a resource "/x" returns the following JSON document:
*
* {
* "data" : {
* "user1" : {
* "userId" : "my-id1",
* "href" : "http://localhost:8080/my-id1"
* },
* "user2" : {
* "userId" : "my-id2",
* "href" : "http://localhost:8080/my-id2"
* },
* }
* }
*
* you can then verify the href using:
*
* when().
* get("/x").
* then().
* root("data.%s").
* body(withArgs("user1"), new ResponseAwareMatcher() {
* public Matcher matcher(Response response) {
* return equalTo("http://localhost:8080/" + response.path("userId"));
* }
* });
*
* Note that you can also use some of the predefined methods in {@link RestAssuredMatchers}.
*
* Note that this method is the same as {@link #content(java.util.List, ResponseAwareMatcher)} expect for syntactic differences.
*
*
* @param responseAwareMatcher The {@link ResponseAwareMatcher} that creates the Hamcrest matcher.
* @return the response specification
* @see #body(String, ResponseAwareMatcher)
* @see RestAssuredMatchers#endsWithPath(String)
* @see RestAssuredMatchers#startsWithPath(String)
* @see RestAssuredMatchers#containsPath(String)
* @see RestAssuredMatchers#equalToPath(String)
*/
T body(List arguments, ResponseAwareMatcher responseAwareMatcher);
/**
* Validate that the response status code matches the given Hamcrest matcher. E.g.
*
* get("/something").then().assertThat().statusCode(equalTo(200));
*
*
* @param expectedStatusCode The expected status code matcher.
* @return the response specification
*/
T statusCode(Matcher expectedStatusCode);
/**
* Validate that the response status code matches an integer. E.g.
*
* get("/something").then().assertThat().statusCode(200);
*
*
* This is the same as:
*
* get("/something").then().assertThat().statusCode(equalTo(200));
*
*
* @param expectedStatusCode The expected status code.
* @return the response specification
*/
T statusCode(int expectedStatusCode);
/**
* Validate that the response status line matches the given Hamcrest matcher. E.g.
*
* expect().statusLine(equalTo("No Content")).when().get("/something");
*
*
* @param expectedStatusLine The expected status line matcher.
* @return the response specification
*/
T statusLine(Matcher expectedStatusLine);
/**
* Validate that the response status line matches the given String. E.g.
*
* expect().statusLine("No Content").when().get("/something");
*
*
* This is the same as:
*
* expect().statusLine(equalTo("No Content")).when().get("/something");
*
*
* @param expectedStatusLine The expected status line.
* @return the response specification
*/
T statusLine(String expectedStatusLine);
/**
* Validate 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");
*
* get("/something").then().assertThat().headers(expectedHeaders);
*
*
*
*
* You can also use Hamcrest matchers:
*
* Map expectedHeaders = new HashMap();
* expectedHeaders.put("Content-Type", containsString("charset=UTF-8"));
* expectedHeaders.put("Content-Length", "160");
*
* get("/something").then().assertThat().headers(expectedHeaders);
*
*
*
* @param expectedHeaders The Map of expected response headers
* @return the response specification
*/
T headers(Map expectedHeaders);
/**
* Validate that response headers matches the supplied headers and values.
*
* E.g. expect that the response of the GET request to "/something" contains header Pragma=no-cache
* and Content-Encoding=gzip:
*
* get("/something").then().assertThat().headers("Pragma", "no-cache", "Content-Encoding", "gzip");
*
*
*
*
* You can also use Hamcrest matchers:
*
* get("/something").then().assertThat().headers("Content-Type", containsString("application/json"), "Pragma", equalsTo("no-cache"));
*
*
* and you can even mix string matching and hamcrest matching:
*
* get("/something").then().assertThat().headers("Content-Type", containsString("application/json"), "Pragma", "no-cache");
*
*
*
* @param firstExpectedHeaderName The name of the first header
* @param firstExpectedHeaderValue The value of the first header
* @param expectedHeaders A list of expected "header name" - "header value" pairs.
* @return the response specification
*/
T headers(String firstExpectedHeaderName, Object firstExpectedHeaderValue, Object... expectedHeaders);
/**
* Validate that a response header matches the supplied header name and hamcrest matcher.
*
* E.g. expect that the response of the GET request to "/something" contains header Pragma=no-cache:
*
* get("/something").then().assertThat().header("Pragma", containsString("no"));
*
*
*
*
* You can also expect several headers:
*
* get("/something").then().assertThat().header("Pragma", equalsTo("no-cache")).and().header("Content-Encoding", containsString("zip"));
*
* Also take a look at {@link #headers(String, Object, Object...)} )} for a short version of passing multiple headers.
*
*
* @param headerName The name of the expected header
* @param expectedValueMatcher The Hamcrest matcher that must conform to the value
* @return the response specification
*/
T header(String headerName, Matcher expectedValueMatcher);
/**
* Compare a header in the response to something else available in the response.
*
* For example imagine that a POST to resource "/x" returns "201 Created" and sets a Location header
* that should end with "/x/{id}" where {id} is present in the response body:
*
* { "id" : 5 }
*
* To verify that the Location header ends with "/x/{id}" you can do like this:
*
*
* given().param("id", 1).body(..).post("/x").then().assertThat().header("Location", response -> response.endsWith("/x/") + response.path("id"));
*
*
*
*
*
*
* @param headerName The name of the expected header
* @param expectedValueMatcher The Hamcrest matcher that must conform to the value
* @return the response specification
*/
T header(String headerName, ResponseAwareMatcher expectedValueMatcher);
/**
* Expect that a response header matches the supplied header name and hamcrest matcher using a mapping function.
*
* E.g. expect that the response of the GET request to "/something" contains header Content-Length: 500 and you want to
* validate that the length must always be less than 600:
*
* when().
* get("/something").
* then().
* header("Content-Length", Integer::parseInt, lessThan(600));
*
*
*
* @param headerName The name of the expected header
* @param mappingFunction Map the header to another value type before exposing it to the Hamcrest matcher
* @param expectedValueMatcher The Hamcrest matcher that must conform to the value
* @return the response specification
*/
T header(String headerName, RestAssuredFunction mappingFunction, Matcher expectedValueMatcher);
/**
* Validate that a response header matches the supplied name and value.
*
* E.g. expect that the response of the GET request to "/something" contains header Pragma=no-cache:
*
* get("/something").then().assertThat().header("Pragma", "no-cache");
*
*
*
*
* You can also expect several headers:
*
* get("/something").then().assertThat().header("Pragma", "no-cache").and().header("Content-Encoding", "gzip");
*
* Also take a look at {@link #headers(String, Object, Object...)} for a short version of passing multiple headers.
*
*
* @param headerName The name of the expected header
* @param expectedValue The value of the expected header
* @return the response specification
*/
T header(String headerName, String expectedValue);
/**
* Validate 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");
*
* get("/something").then().assertThat().cookies(expectedCookies);
*
*
*
*
* You can also use Hamcrest matchers:
*
* Map expectedCookies = new HashMap();
* expectedCookies.put("cookieName1", containsString("Value1"));
* expectedCookies.put("cookieName2", "cookieValue2");
*
* get("/something").then().assertThat().cookies(expectedCookies);
*
*
*
* @param expectedCookies A Map of expected response cookies
* @return the response specification
*/
T cookies(Map expectedCookies);
/**
* Validate that a cookie exist in the response, regardless of value (it may have no value at all).
*
* @param cookieName the cookie to validate that it exists
* @return the response specification
*/
T cookie(String cookieName);
/**
* Validate that response cookies matches the supplied cookie names and values.
*
* E.g. expect that the response of the GET request to "/something" contains cookies cookieName1=cookieValue1
* and cookieName2=cookieValue2:
*
* get("/something").then().assertThat().cookies("cookieName1", "cookieValue1", "cookieName2", "cookieValue2");
*
*
*
*
* You can also use Hamcrest matchers:
*
* get("/something").then().assertThat().cookies("cookieName1", containsString("Value1"), "cookieName2", equalsTo("cookieValue2"));
*
*
* and you can even mix string matching and hamcrest matching:
*
* get("/something").then().assertThat().cookies("cookieName1", containsString("Value1"), "cookieName2", "cookieValue2");
*
*
*
* @param firstExpectedCookieName The name of the first cookie
* @param firstExpectedCookieValue The value of the first cookie
* @param expectedCookieNameValuePairs A list of expected "cookie name" - "cookie value" pairs.
* @return the response specification
*/
T cookies(String firstExpectedCookieName, Object firstExpectedCookieValue, Object... expectedCookieNameValuePairs);
/**
* Validate that a response cookie matches the supplied cookie name and hamcrest matcher.
*
* E.g. expect that the response of the GET request to "/something" contain cookie cookieName1=cookieValue1
*
* get("/something").then().assertThat().cookie("cookieName1", containsString("Value1"));
*
*
*
*
* You can also expect several cookies:
*
* get("/something").then().assertThat().cookie("cookieName1", equalsTo("cookieValue1")).and().cookie("cookieName2", containsString("Value2"));
*
* Also take a look at {@link #cookies(String, Object, Object...)} for a short version of passing multiple cookies.
*
*
* @param cookieName The name of the expected cookie
* @param expectedValueMatcher The Hamcrest matcher that must conform to the value
* @return the response specification
*/
T cookie(String cookieName, Matcher expectedValueMatcher);
/**
* Validate that a detailed response cookie matches the supplied cookie name and hamcrest matcher (see {@link DetailedCookieMatcher}).
*
* E.g. expect that the response of the GET request to "/something" contain cookie cookieName1=cookieValue1
*
* get("/something").then().assertThat()
* .detailedCookie("cookieName1", detailedCookie().value("cookieValue1").secured(true));
*
*
*
*
* You can also expect several cookies:
*
* get("/something").then().assertThat().detailedCookie("cookieName1", detailedCookie().value("cookieValue1").secured(true))
* .and().detailedCookie("cookieName2", detailedCookie().value("cookieValue2").secured(false));
*
*
*
* @param cookieName The name of the expected cookie
* @param detailedCookieMatcher The Hamcrest matcher that must conform to the cookie
* @return the response specification
*/
T cookie(String cookieName, DetailedCookieMatcher detailedCookieMatcher);
/**
* Validate that a response cookie matches the supplied name and value.
*
* E.g. expect that the response of the GET request to "/something" contain cookie cookieName1=cookieValue1:
*
* get("/something").then().assertThat().cookie("cookieName1", "cookieValue1");
*
*
*
*
* You can also expect several cookies:
*
* get("/something").then().assertThat().cookie("cookieName1", "cookieValue1").and().cookie("cookieName2", "cookieValue2");
*
* Also take a look at {@link #cookies(String, Object, Object...)} for a short version of passing multiple cookies.
*
*
* @param cookieName The name of the expected cookie
* @param expectedValue The value of the expected cookie
* @return the response specification
*/
T cookie(String cookieName, Object expectedValue);
/**
* 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:
*
*
* get(..).then().
* body("x.y.firstName", is(..)).
* body("x.y.lastName", is(..)).
* body("x.y.age", is(..)).
* body("x.y.gender", is(..)).
*
*
* you can use a root path and do:
*
* get(..).then().
* rootPath("x.y").
* body("firstName", is(..)).
* body("lastName", is(..)).
* body("age", is(..)).
* body("gender", is(..));
*
*
* Note that this method is exactly the same as {@link #root(String)}.
*
* @param rootPath The root path to use.
*/
T rootPath(String rootPath);
/**
* Set the root path with arguments of the response body so that you don't need to write the entire path for each expectation.
*
* Note that this method is exactly the same as {@link #root(String, java.util.List)}.
*
* @param rootPath The root path to use.
* @param arguments A list of arguments. The path and arguments follows the standard formatting syntax of Java.
* @see #rootPath(String)
*/
T rootPath(String rootPath, List arguments);
/**
* Set the root path with arguments of the response body so that you don't need to write the entire path for each expectation.
*
* Note that this method is exactly the same as {@link #rootPath(String, java.util.List)}.
*
* @param rootPath The root path to use.
* @param arguments The list of substitution arguments. The path and arguments follows the standard formatting syntax of Java..
* @see #rootPath(String)
*/
T root(String rootPath, List arguments);
/**
* 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:
*
*
* get(..).then().
* body("x.y.firstName", is(..)).
* body("x.y.lastName", is(..)).
* body("x.y.age", is(..)).
* body("x.y.gender", is(..));
*
*
* you can use a root and do:
*
* get(..).then().
* root("x.y").
* body("firstName", is(..)).
* body("lastName", is(..)).
* body("age", is(..)).
* body("gender", is(..)).
*
*
* Note that this method is exactly the same as {@link #rootPath(String)} but slightly shorter.
*
* @param rootPath The root path to use.
*/
T root(String rootPath);
/**
* Reset the root path of the response body so that you don't need to write the entire path for each expectation.
* For example:
*
*
* get(..).then().
* root("x.y").
* body("firstName", is(..)).
* body("lastName", is(..)).
* noRoot()
* body("z.something1", is(..)).
* body("w.something2", is(..));
*
*
* This is the same as calling rootPath("") but more expressive.
* Note that this method is exactly the same as {@link #noRootPath()} but slightly shorter.
*
* @see #root(String)
*/
T noRoot();
/**
* Reset the root path of the response body so that you don't need to write the entire path for each expectation.
* For example:
*
*
* get(..).then().
* rootPath("x.y").
* body("firstName", is(..)).
* body("lastName", is(..)).
* noRootPath()
* body("z.something1", is(..)).
* body("w.something2", is(..)).
*
*
* This is the same as calling rootPath("") but more expressive.
* Note that this method is exactly the same as {@link #noRoot()} but slightly more expressive.
*
* @see #root(String)
*/
T noRootPath();
/**
* 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:
*
*
* get(..).then().
* root("x.y").
* body("age", is(..)).
* body("gender", is(..)).
* body("name.firstName", is(..)).
* body("name.lastName", is(..));
*
*
* you can use a append root and do:
*
* get(..).then().
* root("x.y").
* body("age", is(..)).
* body("gender", is(..)).
* appendRoot("name").
* body("firstName", is(..)).
* body("lastName", is(..));
*
*
* @param pathToAppend The root path to use.
*/
T appendRoot(String pathToAppend);
/**
* 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";
* get(..).then().
* root("x.y").
* body("age", is(..)).
* body("gender", is(..)).
* body(namePath + "first", is(..)).
* body(namePath + "last", is(..)).
*
*
* you can use a append root and do:
*
* String namePath = "name";
* get(..).then().
* root("x.y").
* body("age", is(..)).
* body("gender", is(..)).
* appendRoot("%s", withArgs(namePath)).
* body("first", is(..)).
* body("last", is(..)).
*
*
* @param pathToAppend The root path to use. The path and arguments follows the standard formatting syntax of Java.
*/
T appendRoot(String pathToAppend, List arguments);
/**
* 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(..)).
*
*
* @param pathToDetach The root path to detach.
*/
T detachRoot(String pathToDetach);
/**
* 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. {@link #body(String, org.hamcrest.Matcher, Object...)}) 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.
*
* @param contentType The content type of the response.
* @return the response specification
*/
T contentType(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. {@link #body(String, org.hamcrest.Matcher, Object...)}) 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.
*
* @param contentType The content type of the response.
* @return the response specification
*/
T contentType(String contentType);
/**
* Validate the response content type to be contentType.
*
* @param contentType The expected content type of the response.
* @return the response specification
*/
T contentType(Matcher contentType);
/**
* Validate that the response body conforms to one or more Hamcrest matchers. E.g.
*
* // Validate that the response body (content) contains the string "winning-numbers"
* get("/lotto").then().assertThat().body(containsString("winning-numbers"));
*
* // Validate that the response body (content) contains the string "winning-numbers" and "winners"
* get("/lotto").then().assertThat().body(containsString("winning-numbers"), containsString("winners"));
*
*
* @param matcher The hamcrest matcher that must response body must match.
* @param additionalMatchers Optionally additional hamcrest matchers that must return true.
* @return the response specification
*/
T body(Matcher matcher, Matcher... additionalMatchers);
/**
* Compare a path in the response body to something available in the response using arguments.
* For example imagine that a resource "/x" returns the following JSON document:
*
* {
* "userId" : "my-id",
* "my.href" : "http://localhost:8080/my-id"
* }
*
* you can then verify the href using:
*
* get("/x").then().body("%s.href", withArgs("my"), new ResponseAwareMatcher() {
* public Matcher matcher(Response response) {
* return equalTo("http://localhost:8080/" + response.path("userId"));
* }
* });
*
* Note that you can also use some of the predefined methods in {@link RestAssuredMatchers}.
*
* @param path The body path
* @param responseAwareMatcher The {@link ResponseAwareMatcher} that creates the Hamcrest matcher.
* @return the response specification
* @see #body(String, ResponseAwareMatcher)
* @see RestAssuredMatchers#endsWithPath(String)
* @see RestAssuredMatchers#startsWithPath(String)
* @see RestAssuredMatchers#containsPath(String)
* @see RestAssuredMatchers#equalToPath(String)
*/
T body(String path, List arguments, ResponseAwareMatcher responseAwareMatcher);
/**
* Compare a path in the response body to something available in the response, for example another path.
* For example imagine that a resource "/x" returns the following JSON document:
*
* {
* "userId" : "my-id",
* "href" : "http://localhost:8080/my-id"
* }
*
* you can then verify the href using:
*
* get("/x").then().body("href", new ResponseAwareMatcher() {
* public Matcher matcher(Response response) {
* return equalTo("http://localhost:8080/" + response.path("userId"));
* }
* });
*
* Note that you can also use some of the predefined methods in {@link RestAssuredMatchers}.
*
* Note that this method is the same as {@link #content(String, ResponseAwareMatcher)} expect for syntactic differences.
*
*
* @param path The body path
* @param responseAwareMatcher The {@link ResponseAwareMatcher} that creates the Hamcrest matcher.
* @return the response specification
* @see #body(String, java.util.List, ResponseAwareMatcher)
* @see RestAssuredMatchers#endsWithPath(String)
* @see RestAssuredMatchers#startsWithPath(String)
* @see RestAssuredMatchers#containsPath(String)
* @see RestAssuredMatchers#equalToPath(String)
*/
T body(String path, ResponseAwareMatcher responseAwareMatcher);
/**
* Validate that the JSON or XML response body 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:
*
* get("/lotto").then().assertThat().body("lotto.lottoId", equalTo(5));
*
*
* You can also verify that e.g. one of the the winning numbers is 45.
*
* get("/lotto").then().assertThat().body("lotto.winning-numbers", hasItem(45));
*
*
* Or both at the same time:
*
* get("/lotto").then().assertThat().body("lotto.lottoId", equalTo(5)).and().body("lotto.winning-numbers", hasItem(45));
*
*
* or a slightly short version:
*
* get("/lotto").then().assertThat().body("lotto.lottoId", equalTo(5), "lotto.winning-numbers", hasItem(45));
*
*
* XML example
*
* Assume that a GET request to "/xml" returns a XML response containing:
*
* <greeting>
* <firstName>John</firstName>
* <lastName>Doe</lastName>
* </greeting>
*
*
*
* You can now verify that the firstName is equal to "John" like this:
*
* get("/xml").then().assertThat().body("greeting.firstName", equalTo("John"));
*
*
* To verify both the first name and last name you can do like this:
*
* get("/xml").then().assertThat().body("greeting.firstName", equalTo("John")).and().body("greeting.lastName", equalTo("Doe"));
*
*
* Or the slightly shorter version of:
*
* get("/xml").then().assertThat().body("greeting.firstName", equalTo("John"), "greeting.lastName", equalTo("Doe"));
*
* Notes
*
* Note that if the response body type is not of type application/xml or application/json you
* cannot use this verification.
*
*
*
* The only difference between the content and body methods are of syntactic nature.
*
*
* @param path The body path
* @param matcher The hamcrest matcher that must response body must match.
* @param additionalKeyMatcherPairs Optionally additional hamcrest matchers that must return true.
* @return the response specification
*/
T body(String path, Matcher matcher, Object... additionalKeyMatcherPairs);
/**
* Same as {@link #body(String, java.util.List, org.hamcrest.Matcher, Object...)} 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;
* get("/x").then().assertThat().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:
*
* get("/x").then()
* 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.
*
*
* @param path The body path
* @param matcher The hamcrest matcher that must response body must match.
* @param additionalKeyMatcherPairs Optionally additional hamcrest matchers that must return true.
* @return the response specification
* @see #content(String, org.hamcrest.Matcher, Object...)
*/
T content(String path, List arguments, Matcher matcher, Object... additionalKeyMatcherPairs);
/**
* Compare a path in the response body to something available in the response using arguments.
* For example imagine that a resource "/x" returns the following JSON document:
*
* {
* "userId" : "my-id",
* "my.href" : "http://localhost:8080/my-id"
* }
*
* you can then verify the href using:
*
* get("/x").then().content("%s.href", withArgs("my"), new ResponseAwareMatcher() {
* public Matcher matcher(Response response) {
* return equalTo("http://localhost:8080/" + response.path("userId"));
* }
* });
*
* Note that you can also use some of the predefined methods in {@link RestAssuredMatchers}.
* *
* Note that this method is the same as {@link #body(String, java.util.List, ResponseAwareMatcher)} expect for syntactic differences.
*
*
* @param path The body path
* @param responseAwareMatcher The {@link ResponseAwareMatcher} that creates the Hamcrest matcher.
* @return the response specification
* @see #content(String, ResponseAwareMatcher)
* @see RestAssuredMatchers#endsWithPath(String)
* @see RestAssuredMatchers#startsWithPath(String)
* @see RestAssuredMatchers#containsPath(String)
* @see RestAssuredMatchers#equalToPath(String)
*/
T content(String path, List arguments, ResponseAwareMatcher responseAwareMatcher);
/**
* Compare a path in the response body to something available in the response, for example another path.
* For example imagine that a resource "/x" returns the following JSON document:
*
* {
* "userId" : "my-id",
* "href" : "http://localhost:8080/my-id"
* }
*
* you can then verify the href using:
*
* get("/x").then().content("href", new ResponseAwareMatcher() {
* public Matcher matcher(Response response) {
* return equalTo("http://localhost:8080/" + response.path("userId"));
* }
* });
*
* Note that you can also use some of the predefined methods in {@link RestAssuredMatchers}.
*
* Note that this method is the same as {@link #body(String, ResponseAwareMatcher)} expect for syntactic differences.
*
*
* @param path The body path
* @param responseAwareMatcher The {@link ResponseAwareMatcher} that creates the Hamcrest matcher.
* @return the response specification
* @see #content(String, java.util.List, ResponseAwareMatcher)
* @see RestAssuredMatchers#endsWithPath(String)
* @see RestAssuredMatchers#startsWithPath(String)
* @see RestAssuredMatchers#containsPath(String)
* @see RestAssuredMatchers#equalToPath(String)
*/
T content(String path, ResponseAwareMatcher responseAwareMatcher);
/**
* Syntactic sugar, e.g.
*
* get("/something").then().assertThat().body(containsString("OK")).and().body(containsString("something else"));
*
*
* is that same as:
*
* get("/something").then().assertThat().body(containsString("OK")).body(containsString("something else"));
*
*
* @return the response specification
*/
T and();
/**
* Syntactic sugar, e.g.
*
* get("/something").then().using().defaultParser(JSON).assertThat().body(containsString("OK")).and().body(containsString("something else"));
*
*
* is that same as:
*
* get("/something").then().defaultParser(JSON).body(containsString("OK")).body(containsString("something else"));
*
*
* @return the response specification
*/
T using();
/**
* Syntactic sugar, e.g.
*
* get("/something").then().assertThat().body(containsString("OK")).and().body(containsString("something else"));
*
*
* is that same as:
*
* get("/something").then().body(containsString("OK")).body(containsString("something else"));
*
*
* @return the response specification
*/
T assertThat();
/**
* Validate that the response matches an entire specification.
*
* ResponseSpecification responseSpec = new ResponseSpecBuilder().expectStatusCode(200).build();
* get("/something").then()
* spec(responseSpec).
* body("x.y.z", equalTo("something"));
*
*
* This is useful when you want to reuse multiple different expectations in several tests.
*
* The specification passed to this method is merged with the current 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
*
*
* This method is the same as {@link #specification(ResponseSpecification)} but the name is a bit shorter.
*
* @param responseSpecificationToMerge The specification to merge with.
* @return the response specification
*/
T spec(ResponseSpecification responseSpecificationToMerge);
/**
* Validate that the response matches an entire specification.
*
* ResponseSpecification responseSpec = new ResponseSpecBuilder().expectStatusCode(200).build();
*
* get("/something").then().
* specification(responseSpec).
* body("x.y.z", equalTo("something"));
*
*
* This is useful when you want to reuse multiple different expectations in several tests.
*
* The specification passed to this method is merged with the current 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
*
*
*
* This method is the same as {@link #spec(ResponseSpecification)} but the name is a bit longer.
*
* @param responseSpecificationToMerge The specification to merge with.
* @return the response specification
*/
T specification(ResponseSpecification responseSpecificationToMerge);
/**
* Register a content-type to be parsed using a predefined parser. E.g. let's say you want parse
* content-type application/custom with the XML parser to be able to verify the response using the XML dot notations:
*
* get("/x").then().assertThat().body("document.child", equalsTo("something")
*
* Since application/custom 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:
*
* get("/x").then().parser("application/custom", Parser.XML).assertThat(). ..;
*
*
* You can also specify by it for every response by using:
*
* RestAssured.registerParser("application/custom", Parser.XML);
*
*
* @param contentType The content-type to register
* @param parser The parser to use when verifying the response.
*/
T parser(String contentType, 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:
*
* get("/x").then().using().defaultParser(Parser.JSON).assertThat(). ..;
*
*
* You can also specify it for every response by using:
*
* RestAssured.defaultParser(Parser.JSON);
*
*
* @param parser The parser to use when verifying the response if no other parser is found for the response content-type.
*/
T defaultParser(Parser parser);
/**
* Extract values from the response or return the response instance itself. This is useful for example if you want to use values from the
* response in sequent requests. For example given that the resource title returns the following JSON
*
* {
* "title" : "My Title",
* "_links": {
* "self": { "href": "/title" },
* "next": { "href": "/title?page=2" }
* }
* }
*
* and you want to validate that content type is equal to JSON and the title is equal to My Title
* but you also want to extract the link to the "next" title to use that in a subsequent request. This is how:
*
* String nextTitleLink =
* given().
* param("param_name", "param_value").
* when().
* get("/title").
* then().
* contentType(JSON).
* body("title", equalTo("My Title")).
* extract().
* path("_links.next.href");
*
* get(nextTitleLink). ..
*
*
* @return An instance of {@link ExtractableResponse}.
*/
ExtractableResponse extract();
/**
* Returns the {@link ValidatableResponseLogSpec} that allows you to log different parts of the {@link Response}.
* This is mainly useful for debug purposes when writing your tests. I
*
* @return the validatable response log specification
*/
ValidatableResponseLogSpec log();
/**
* Validate that the response time (in milliseconds) matches the supplied matcher. For example:
*
*
* when().
* get("/something").
* then().
* time(lessThan(2000));
*
*
* where lessThan is a Hamcrest matcher
*
* @return The {@link ValidatableResponse} instance.
*/
T time(Matcher matcher);
/**
* Validate that the response time matches the supplied matcher and time unit. For example:
*
*
* when().
* get("/something").
* then().
* time(lessThan(2), TimeUnit.SECONDS);
*
*
* where lessThan is a Hamcrest matcher
*
* @return The {@link ValidatableResponse} instance.
*/
T time(Matcher matcher, TimeUnit timeUnit);
}