io.restassured.specification.ResponseSpecification 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.specification;
import io.restassured.function.RestAssuredFunction;
import io.restassured.http.ContentType;
import io.restassured.http.Cookie;
import io.restassured.matcher.DetailedCookieMatcher;
import io.restassured.parsing.Parser;
import io.restassured.response.Response;
import io.restassured.response.ValidatableResponse;
import org.hamcrest.Matcher;
import java.util.List;
import java.util.Map;
import java.util.concurrent.TimeUnit;
/**
* Allows you to specify how the expected response must look like in order for a test to pass.
*/
public interface ResponseSpecification {
/**
* Expect that the response content conforms to one or more Hamcrest matchers. E.g.
*
* // Expect that the response content (body) contains the string "winning-numbers"
* expect().content(containsString("winning-numbers")).when().get("/lotto");
*
* // Expect that the response content (body) contains the string "winning-numbers" and "winners"
* expect().content(containsString("winning-numbers"), containsString("winners")).when().get("/lotto");
*
*
* @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
* @deprecated Use {@link #body(Matcher, Matcher[])} instead
*/
@Deprecated
ResponseSpecification content(Matcher matcher, Matcher... additionalMatchers);
/**
* This as special kind of expectation that is mainly useful when you've specified a root path with an argument placeholder.
* For example:
*
* expect().
* root("x.%s"). // Root path with a placeholder
* content(withArgs("firstName"), equalTo(..)).
* content(withArgs("lastName"), equalTo(..)).
* when().
* get(..);
*
*
* Note that this is the same as doing:
*
* expect().
* root("x.%s"). // Root path with a placeholder
* content(withArgs("firstName"), equalTo(..)).
* content(withArgs("lastName"), equalTo(..)).
* when().
* get(..);
*
*
*
* 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...)
* @deprecated use {@link #body(List, Matcher, Object...)} instead
*/
@Deprecated
ResponseSpecification content(List arguments, Matcher matcher, Object... additionalKeyMatcherPairs);
/**
* Validates the specified response against this ResponseSpecification
*
* @param response The response to validate
* @return The same response
*/
Response validate(Response response);
/**
* 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:
*
* expect().content("lotto.lottoId", equalTo(5)).when().get("/lotto");
*
*
* You can also verify that e.g. one of the the winning numbers is 45.
*
* expect().content("lotto.winning-numbers", hasItem(45)).when().get("/lotto");
*
*
* Or both at the same time:
*
* expect().content("lotto.lottoId", equalTo(5)).and().content("lotto.winning-numbers", hasItem(45)).when().get("/lotto");
*
*
* or a slightly short version:
*
* expect().content("lotto.lottoId", equalTo(5), "lotto.winning-numbers", hasItem(45)).when().get("/lotto");
*
*
* 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:
*
* expect().content("greeting.firstName", equalTo("John")).when().get("/xml");
*
*
* To verify both the first name and last name you can do like this:
*
* expect().content("greeting.firstName", equalTo("John")).and().content("greeting.lastName", equalTo("Doe")).when().get("/xml");
*
*
* Or the slightly shorter version of:
*
* expect().content("greeting.firstName", equalTo("John"), "greeting.lastName", equalTo("Doe")).when().get("/xml");
*
* 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
* @deprecated Use {@link #body(String, Matcher, Object...)} instead
*/
@Deprecated
ResponseSpecification content(String key, Matcher matcher, Object... additionalKeyMatcherPairs);
/**
* Validate that the response time (in milliseconds) matches the supplied matcher. For example:
*
*
* when().
* get("/something").
* then().
* time(lessThan(2000L));
*
*
* where lessThan is a Hamcrest matcher
*
* @return The {@link ValidatableResponse} instance.
*/
ResponseSpecification time(Matcher matcher);
/**
* Validate that the response time matches the supplied matcher and time unit. For example:
*
*
* when().
* get("/something").
* then().
* time(lessThan(2L), TimeUnit.SECONDS);
*
*
* where lessThan is a Hamcrest matcher
*
* @return The {@link ValidatableResponse} instance.
*/
ResponseSpecification time(Matcher matcher, TimeUnit timeUnit);
/**
* 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;
* when().get().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:
*
* when().
* get()
* 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 key The body key
* @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...)
*/
ResponseSpecification body(String key, 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:
*
* when().
* 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:
*
* when().
* get(..);
* then().
* root("x.%s"). // Root path with a placeholder
* body(withArgs("firstName"), equalTo(..)).
* body(withArgs("lastName"), equalTo(..)).
*
*
*
* @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...)
*/
ResponseSpecification body(List arguments, Matcher matcher, Object... additionalKeyMatcherPairs);
/**
* Expect that the response status code matches the given Hamcrest matcher. E.g.
*
* expect().statusCode(equalTo(200)).when().get("/something");
*
*
* @param expectedStatusCode The expected status code matcher.
* @return the response specification
*/
ResponseSpecification statusCode(Matcher expectedStatusCode);
/**
* Expect that the response status code matches an integer. E.g.
*
* expect().statusCode(200).when().get("/something");
*
*
* This is the same as:
*
* expect().statusCode(equalTo(200)).when().get("/something");
*
*
* @param expectedStatusCode The expected status code.
* @return the response specification
*/
ResponseSpecification statusCode(int expectedStatusCode);
/**
* Expect 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
*/
ResponseSpecification statusLine(Matcher expectedStatusLine);
/**
* Expect 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
*/
ResponseSpecification statusLine(String expectedStatusLine);
/**
* 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");
*
* expect().response().headers(expectedHeaders).when().get("/something");
*
*
*
*
* You can also use Hamcrest matchers:
*
* Map expectedHeaders = new HashMap();
* expectedHeaders.put("Content-Type", containsString("charset=UTF-8"));
* expectedHeaders.put("Content-Length", "160");
*
* expect().headers(expectedHeaders).when().get("/something");
*
*
*
* @param expectedHeaders The Map of expected response headers
* @return the response specification
*/
ResponseSpecification headers(Map expectedHeaders);
/**
* Expect 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:
*
* expect().headers("Pragma", "no-cache", "Content-Encoding", "gzip").when().get("/something");
*
*
*
*
* You can also use Hamcrest matchers:
*
* expect().response().headers("Content-Type", containsString("application/json"), "Pragma", equalsTo("no-cache")).when().get("/something");
*
*
* and you can even mix string matching and hamcrest matching:
*
* expect().headers("Content-Type", containsString("application/json"), "Pragma", "no-cache").when().get("/something");
*
*
*
* @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
*/
ResponseSpecification headers(String firstExpectedHeaderName, Object firstExpectedHeaderValue, Object... expectedHeaders);
/**
* Expect 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:
*
* expect().header("Pragma", containsString("no")).when().get("/something");
*
*
*
*
* You can also expect several headers:
*
* expect().header("Pragma", equalsTo("no-cache")),and().header("Content-Encoding", containsString("zip")).when().get("/something");
*
* 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
*/
ResponseSpecification header(String headerName, Matcher 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
*/
ResponseSpecification header(String headerName, RestAssuredFunction mappingFunction, Matcher expectedValueMatcher);
/**
* Expect 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:
*
* expect().header("Pragma", "no-cache").when().get("/something");
*
*
*
*
* You can also expect several headers:
*
* expect().header("Pragma", "no-cache"),and().header("Content-Encoding", "gzip").when().get("/something");
*
* 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
*/
ResponseSpecification header(String headerName, String expectedValue);
/**
* 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");
*
* expect().response().cookies(expectedCookies).when().get("/something");
*
*
*
*
* You can also use Hamcrest matchers:
*
* Map expectedCookies = new HashMap();
* expectedCookies.put("cookieName1", containsString("Value1"));
* expectedCookies.put("cookieName2", "cookieValue2");
*
* expect().cookies(expectedCookies).when().get("/something");
*
*
*
* @param expectedCookies A Map of expected response cookies
* @return the response specification
*/
ResponseSpecification cookies(Map expectedCookies);
/**
* Expect 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
*/
ResponseSpecification cookie(String cookieName);
/**
* Expect 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:
*
* expect().cookies("cookieName1", "cookieValue1", "cookieName2", "cookieValue2").when().get("/something");
*
*
*
*
* You can also use Hamcrest matchers:
*
* expect().response().cookies("cookieName1", containsString("Value1"), "cookieName2", equalsTo("cookieValue2")).when().get("/something");
*
*
* and you can even mix string matching and hamcrest matching:
*
* expect().cookies("cookieName1", containsString("Value1"), "cookieName2", "cookieValue2").when().get("/something");
*
*
*
* @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
*/
ResponseSpecification cookies(String firstExpectedCookieName, Object firstExpectedCookieValue, Object... expectedCookieNameValuePairs);
/**
* Expect 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
*
* expect().cookie("cookieName1", containsString("Value1")).when().get("/something");
*
*
*
*
* You can also expect several cookies:
*
* expect().cookie("cookieName1", equalsTo("cookieValue1")).and().cookie("cookieName2", containsString("Value2")).when().get("/something");
*
* 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
*/
ResponseSpecification 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
*
* expect.detailedCookie("cookieName1", detailedCookie().value("cookieValue1").secured(true));
*
*
*
*
* You can also expect several cookies:
*
* expect().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
*/
ResponseSpecification cookie(String cookieName, DetailedCookieMatcher detailedCookieMatcher);
/**
* Expect 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:
*
* expect().cookie("cookieName1", "cookieValue1").when().get("/something");
*
*
*
*
* You can also expect several cookies:
*
* expect().cookie("cookieName1", "cookieValue1"),and().cookie("cookieName2", "cookieValue2").when().get("/something");
*
* 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
*/
ResponseSpecification cookie(String cookieName, Object expectedValue);
/**
* Returns the {@link ResponseLogSpecification} that allows you to log different parts of the {@link ResponseSpecification}.
* This is mainly useful for debug purposes when writing your tests. It's a shortcut for:
*
* given().filter(ResponseLoggingFilter.responseLogger()). ..
*
*
* @return the response log specification
*/
ResponseLogSpecification log();
/**
* 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(..);
*
*
* Note that this method is exactly the same as {@link #root(String)}.
*
* @param rootPath The root path to use.
* @deprecated Use {@link #root(String)} instead
*/
@Deprecated
ResponseSpecification 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 #root(String)
* @deprecated Use {@link #root(String, List)} instead
*/
@Deprecated
ResponseSpecification 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.
*
* @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..
*/
ResponseSpecification 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:
*
*
* when().
* 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:
*
* when().
* get(..).
* then().
* root("x.y").
* body("firstName", is(..)).
* body("lastName", is(..)).
* body("age", is(..)).
* body("gender", is(..)).
*
*
*
* @param rootPath The root path to use.
*/
ResponseSpecification 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:
*
*
* when().
* 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 root("") but less verbose and the it communicates intent better.
*
* @see #root(String)
*/
ResponseSpecification 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:
*
*
* when().
* 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 #noRoot()} but slightly more expressive.
*
* @see #root(String)
* @deprecated Use {@link #noRoot()} instead
*/
@Deprecated
ResponseSpecification 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:
*
*
* 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(..);
*
*
* @param pathToAppend The root path to append.
*/
ResponseSpecification 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";
* 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(..);
*
*
* @param pathToAppend The root path to use. The path and arguments follows the standard formatting syntax of Java.
*/
ResponseSpecification 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.
*/
ResponseSpecification detachRoot(String pathToDetach);
/**
* Set the response content type to be contentType.
*
* @param contentType The content type of the response.
* @return the response specification
*/
ResponseSpecification contentType(ContentType contentType);
/**
* Set the response content type to be contentType.
*
* @param contentType The content type of the response.
* @return the response specification
*/
ResponseSpecification contentType(String contentType);
/**
* Expect the response content type to be contentType.
*
* @param contentType The expected content type of the response.
* @return the response specification
*/
ResponseSpecification contentType(Matcher contentType);
/**
* Expect that the response body conforms to one or more Hamcrest matchers. E.g.
*
* // Expect that the response body (content) contains the string "winning-numbers"
* when().get("/lotto").then().body(containsString("winning-numbers"));
*
* // Expect that the response body (content) contains the string "winning-numbers" and "winners"
* when().get("/lotto").then().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
*/
ResponseSpecification body(Matcher matcher, Matcher... additionalMatchers);
/**
* Expect 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:
*
* when().get("/lotto").then().body("lotto.lottoId", equalTo(5));
*
*
* You can also verify that e.g. one of the the winning numbers is 45.
*
* when().get("/lotto").then().body("lotto.winning-numbers", hasItem(45));
*
*
* Or both at the same time:
*
* when().get("/lotto").then().body("lotto.lottoId", equalTo(5)).and().body("lotto.winning-numbers", hasItem(45));
*
*
* or a slightly short version:
*
* when().get("/lotto").then().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:
*
* when().get("/xml").then().body("greeting.firstName", equalTo("John"));
*
*
* To verify both the first name and last name you can do like this:
*
* when().get("/xml").then().body("greeting.firstName", equalTo("John")).and().body("greeting.lastName", equalTo("Doe"));
*
*
* Or the slightly shorter version of:
*
* when().get("/xml").then().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
*/
ResponseSpecification 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;
* 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.
*
*
* @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...)
* @deprecated Use {@link #body(String, List, Matcher, Object...)} instead
*/
@Deprecated
ResponseSpecification content(String path, List arguments, Matcher matcher, Object... additionalKeyMatcherPairs);
/**
* Syntactic sugar, e.g.
*
* expect().body(containsString("OK")).when().get("/something");
*
*
* is that same as:
*
* expect().body(containsString("OK")).get("/something");
*
*
* @return the response specification
*/
RequestSender when();
/**
* Returns the request io.restassured.specification so that you can define the properties of the request.
*
* expect().body(containsString("OK")).given().parameters("param1", "value1").when().get("/something");
*
*
* @return the request io.restassured.specification
*/
RequestSpecification given();
/**
* Syntactic sugar, e.g.
*
* expect().that().body(containsString("OK")).when().get("/something");
*
*
* is that same as:
*
* expect().body(containsString("OK")).get("/something");
*
*
* @return the response specification
*/
ResponseSpecification that();
/**
* Returns the request io.restassured.specification so that you can define the properties of the request.
*
* expect().body(containsString("OK")).and().request().parameters("param1", "value1").when().get("/something");
*
*
* @return the request io.restassured.specification
*/
RequestSpecification request();
/**
* Syntactic sugar, e.g.
*
* expect().response().body(containsString("OK")).when().get("/something");
*
*
* is that same as:
*
* expect().body(containsString("OK")).get("/something");
*
*
* @return the response specification
*/
ResponseSpecification response();
/**
* Syntactic sugar, e.g.
*
* expect().body(containsString("OK")).and().body(containsString("something else")).when().get("/something");
*
*
* is that same as:
*
* expect().body(containsString("OK")).body(containsString("something else")).when().get("/something");
*
*
* @return the response specification
*/
ResponseSpecification and();
/**
* Returns the request io.restassured.specification so that you can define the properties of the request.
*
* expect().body(containsString("OK")).and().with().request().parameters("param1", "value1").get("/something");
*
*
* @return the request io.restassured.specification
*/
RequestSpecification with();
/**
* Syntactic sugar, e.g.
*
* expect().body(containsString("OK")).then().get("/something");
*
*
* is that same as:
*
* expect().body(containsString("OK")).get("/something");
*
*
* @return the response specification
*/
ResponseSpecification then();
/**
* Syntactic sugar, e.g.
*
* expect().body(containsString("OK")).and().expect().body(containsString("something else")).when().get("/something");
*
*
* is that same as:
*
* * expect().body(containsString("OK")).and().body(containsString("something else")).when().get("/something");
*
*
* @return the response specification
*/
ResponseSpecification expect();
/**
* Expect that the response matches an entire specification.
*
* ResponseSpecification responseSpec = new ResponseSpecBuilder().expectStatusCode(200).build();
*
* when().
* 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
*
*
*
* @param responseSpecificationToMerge The specification to merge with.
* @return the response specification
*/
ResponseSpecification spec(ResponseSpecification responseSpecificationToMerge);
/**
* Expect that the response matches an entire specification.
*
* ResponseSpecification responseSpec = new ResponseSpecBuilder().expectStatusCode(200).build();
*
* expect().
* specification(responseSpec).
* body("x.y.z", equalTo("something")).
* when().
* get("/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
* @deprecated Use {@link #spec(ResponseSpecification)} instead
*/
@Deprecated
ResponseSpecification 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/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 it for every response by using:
*
* RestAssured.registerParser("application/vnd.uoml+xml", Parser.XML);
*
*
* @param contentType The content-type to register
* @param parser The parser to use when verifying the response.
*/
ResponseSpecification 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:
*
* expect().defaultParser(Parser.JSON).when(). ..;
*
*
* 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.
*/
ResponseSpecification defaultParser(Parser parser);
}