com.jayway.restassured
Class RestAssured

java.lang.Object
  com.jayway.restassured.RestAssured

public class RestAssured
extends java.lang.Object

REST Assured is a Java DSL for simplifying testing of REST based services built on top of HTTP Builder. It supports POST, GET, PUT, DELETE and HEAD requests and to verify the response of these requests. Usage examples:

1. Assume that the GET request (to http://localhost:8080/lotto) returns JSON as:

    {
    "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]
      }]
     }
    }
    

   REST assured can then help you to easily make the GET request and verify the response. E.g. if you want to verify that lottoId is equal to 5 you can do like this:

    expect().body("lotto.lottoId", equalTo(5)).when().get("/lotto");
    

   or perhaps you want to check that the winnerId's are 23 and 54:

     expect().body("lotto.winners.winnerId", hasItems(23, 54)).when().get("/lotto");
    

2. XML can be verified in a similar way. Image that a POST request to http://localhost:8080/greetXML returns:

    <greeting>
        <firstName>{params("firstName")}</firstName>
        <lastName>{params("lastName")}</lastName>
      </greeting>
    

   i.e. it sends back a greeting based on the firstName and lastName parameter sent in the request. You can easily perform and verify e.g. the firstName with REST assured:

    with().parameters("firstName", "John", "lastName", "Doe").expect().body("greeting.firstName", equalTo("John")).when().post("/greetXML");
    

   If you want to verify both firstName and lastName you may do like this:

    with().parameters("firstName", "John", "lastName", "Doe").expect().body("greeting.firstName", equalTo("John")).and().body("greeting.lastName", equalTo("Doe")).when().post("/greetXML");
    

   or a little shorter:

    with().parameters("firstName", "John", "lastName", "Doe").expect().body("greeting.firstName", equalTo("John"), "greeting.lastName", equalTo("Doe")).when().post("/greetXML");
    

3. You can also verify XML responses using x-path. For example:

    expect().body(hasXPath("/greeting/firstName", containsString("Jo"))).given().parameters("firstName", "John", "lastName", "Doe").when().post("/greetXML");
    

   or

    expect().body(hasXPath("/greeting/firstName[text()='John']")).with().parameters("firstName", "John", "lastName", "Doe").post("/greetXML");
    

4. Besides specifying request parameters you can also specify headers, cookies, body and content type.
   
   • Cookie:

      given().cookie("username", "John").then().expect().body(equalTo("username")).when().get("/cookie");
      

   • Headers:

      given().header("MyHeader", "Something").and(). ..
      given().headers("MyHeader", "Something", "MyOtherHeader", "SomethingElse").and(). ..
      

   • Content Type:

      given().contentType(ContentType.TEXT). ..
      

   • Body:

      given().request().body("some body"). .. // Works for POST and PUT requests
      given().request().body(new byte[]{42}). .. // Works for POST
      

5. You can also verify status code, status line, cookies, headers, content type and body.
   • Cookie:

      expect().cookie("cookieName", "cookieValue"). ..
      expect().cookies("cookieName1", "cookieValue1", "cookieName2", "cookieValue2"). ..
      expect().cookies("cookieName1", "cookieValue1", "cookieName2", containsString("Value2")). ..
      

   • Status:

      expect().statusCode(200). ..
      expect().statusLine("something"). ..
      expect().statusLine(containsString("some")). ..
      

   • Headers:

      expect().header("headerName", "headerValue"). ..
      expect().headers("headerName1", "headerValue1", "headerName2", "headerValue2"). ..
      expect().headers("headerName1", "headerValue1", "headerName2", containsString("Value2")). ..
      

   • Content-Type:

      expect().contentType(ContentType.JSON). ..
      

   • Full body/content matching:

      expect().body(equalsTo("something")). ..
      expect().content(equalsTo("something")). .. // Same as above
      

6. REST assured also supports some authentication schemes, for example basic authentication:

    given().auth().basic("username", "password").expect().statusCode(200).when().get("/secured/hello");
    

   Other supported schemes are OAuth and certificate authentication.
7. By default REST assured assumes host localhost and port 8080 when doing a request. If you want a different port you can do:

    given().port(80). ..
    

   or simply:

    .. when().get("http://myhost.org:80/doSomething");
    

   You can also change the default base URI and port for all subsequent requests:

    RestAssured.baseURI = "http://myhost.org";
    RestAssured.port = 80;
    

   This means that a request like e.g. get("/hello") goes to: http://myhost.org:8080/hello
   You can reset to the standard baseURI (localhost) and standard port (8080) using:

    RestAssured.reset();
    

In order to use REST assured effectively it's recommended to statically import methods from the following classes:

• com.jayway.restassured.RestAssured.*
• org.hamcrest.Matchers.*

Field Summary

static java.lang.String	baseURI The base URI that's used by REST assured when making requests if a non-fully qualified URI is used in the request.
static int	DEFAULT_PORT
static java.lang.String	DEFAULT_URI
static int	port The port that's used by REST assured when is left out of the specified URI when making a request.

Constructor Summary

RestAssured()

Method Summary

static ResponseSpecification	expect() Start building the response part of the test specification.
static RequestSpecification	given() Start building the request part of the test specification.
static RequestSender	given(RequestSpecification requestSpecification, ResponseSpecification responseSpecification) When you have long specifications it can be better to split up the definition of response and request specifications in multiple lines.
static void	reset() Reset the baseURI and port to their default values of "http://localhost" and 8080.
static RequestSpecification	with() Start building the request part of the test specification.

Methods inherited from class java.lang.Object

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

Field Detail

DEFAULT_URI

public static final java.lang.String DEFAULT_URI

See Also:

Constant Field Values

DEFAULT_PORT

public static final int DEFAULT_PORT

See Also:

Constant Field Values

baseURI

public static java.lang.String baseURI

The base URI that's used by REST assured when making requests if a non-fully qualified URI is used in the request. Default value is "http://localhost".

port

public static int port

The port that's used by REST assured when is left out of the specified URI when making a request. Default value is 8080.

Constructor Detail

RestAssured

public RestAssured()

Method Detail

expect

public static ResponseSpecification expect()

Start building the response part of the test specification. E.g.

 expect().body("lotto.lottoId", equalTo(5)).when().get("/lotto");
 

will expect that the response body for the GET request to "/lotto" should contain JSON or XML which has a lottoId equal to 5.

Returns:

A response specification.

with

public static RequestSpecification with()

Start building the request part of the test specification. E.g.

 with().parameters("firstName", "John", "lastName", "Doe").expect().body("greeting.firstName", equalTo("John")).when().post("/greetXML");
 

will send a POST request to "/greetXML" with request parameters firstName=John and lastName=Doe and expect that the response body containing JSON or XML firstName equal to John. The only difference between with() and given() is syntactical.

Returns:

A request specification.

given

public static RequestSpecification given()

Start building the request part of the test specification. E.g.

 given().parameters("firstName", "John", "lastName", "Doe").expect().body("greeting.firstName", equalTo("John")).when().post("/greetXML");
 

will send a POST request to "/greetXML" with request parameters firstName=John and lastName=Doe and expect that the response body containing JSON or XML firstName equal to John. The only difference between with() and given() is syntactical.

Returns:

A request specification.

given

public static RequestSender given(RequestSpecification requestSpecification,
                                  ResponseSpecification responseSpecification)

When you have long specifications it can be better to split up the definition of response and request specifications in multiple lines. You can then pass the response and request specifications to this method. E.g.

 RequestSpecification requestSpecification = with().parameters("firstName", "John", "lastName", "Doe");
 ResponseSpecification responseSpecification = expect().body("greeting", equalTo("Greetings John Doe"));
 given(requestSpecification, responseSpecification).get("/greet");
 

This will perform a GET request to "/greet" and verify it according to the responseSpecification.

Returns:

A test specification.

reset

public static void reset()

Reset the baseURI and port to their default values of "http://localhost" and 8080.