GettingStarted

Contents

1. Maven / Gradle
   1. REST Assured
   2. JsonPath
   3. XmlPath
   4. JSON Schema Validation
   5. Spring Mock MVC
   6. Spring Web Test Client
   7. Scala Module
   8. Kotlin Extensions Module
   9. Java 9+
2. Non-maven users
3. Static Imports
4. Version 2.x
5. Documentation

Maven / Gradle Users

Add the following dependency to your pom.xml:

REST Assured

Includes JsonPath and XmlPath

Maven:

<dependency>
      <groupId>io.rest-assured</groupId>
      <artifactId>rest-assured</artifactId>
      <version>5.4.0</version>
      <scope>test</scope>
</dependency>

Gradle:

testImplementation 'io.rest-assured:rest-assured:5.4.0'

Notes

1. You should place rest-assured before the JUnit dependency declaration in your pom.xml / build.gradle in order to make sure that the correct version of Hamcrest is used.
2. REST Assured includes JsonPath and XmlPath as transitive dependencies

JsonPath

Standalone JsonPath (included if you depend on the rest-assured artifact). Makes it easy to parse JSON documents. Note that this JsonPath implementation uses Groovy's GPath syntax and is not to be confused with Kalle Stenflo's JsonPath implementation.

Maven:

<dependency>
      <groupId>io.rest-assured</groupId>
      <artifactId>json-path</artifactId>
      <version>5.4.0</version>
      <scope>test</scope>
</dependency>

Gradle:

testImplementation 'io.rest-assured:json-path:5.4.0'

XmlPath

Stand-alone XmlPath (included if you depend on the rest-assured artifact). Makes it easy to parse XML documents.

Maven:

<dependency>
      <groupId>io.rest-assured</groupId>
      <artifactId>xml-path</artifactId>
      <version>5.4.0</version>
      <scope>test</scope>
</dependency>

Gradle:

testImplementation 'io.rest-assured:xml-path:5.4.0'

JSON Schema Validation

If you want to validate that a JSON response conforms to a Json Schema you can use the json-schema-validator module:

Maven:

<dependency>
      <groupId>io.rest-assured</groupId>
      <artifactId>json-schema-validator</artifactId>
      <version>5.4.0</version>
      <scope>test</scope>
</dependency>

Gradle:

testImplementation 'io.rest-assured:json-schema-validator:5.4.0'

Refer to the documentation for more info.

Spring Mock Mvc

If you're using Spring Mvc you can now unit test your controllers using the RestAssuredMockMvc API in the spring-mock-mvc module. For this to work you need to depend on the spring-mock-mvc module:

Maven:

<dependency>
      <groupId>io.rest-assured</groupId>
      <artifactId>spring-mock-mvc</artifactId>
      <version>5.4.0</version>
      <scope>test</scope>
</dependency>

Gradle:

testImplementation 'io.rest-assured:spring-mock-mvc:5.4.0'

Using Kotlin? Refer to the documentation for Kotlin extension functions that makes it nicer to work with the Spring Mock Mvc module.

Spring Web Test Client

If you're using Spring Webflux you can now unit test your reactive controllers using the RestAssuredWebTestClient API in the spring-mock-mvc module. For this to work you need to depend on the spring-web-test-client module:

Maven:

<dependency>
      <groupId>io.rest-assured</groupId>
      <artifactId>spring-web-test-client</artifactId>
      <version>5.4.0</version>
      <scope>test</scope>
</dependency>

Gradle:

testImplementation 'io.rest-assured:spring-web-test-client:5.4.0'

Scala Support

If you're using Scala you may leverage the scala-support module. For this to work you need to depend on the scala-support module:

SBT:

libraryDependencies += "io.rest-assured" % "scala-support" % "5.4.0"

Maven:

<dependency>
    <groupId>io.rest-assured</groupId>
    <artifactId>scala-support</artifactId>
    <version>5.4.0</version>
    <scope>test</scope>
</dependency>

Gradle:

testImplementation 'io.rest-assured:scala-support:5.4.0'

Kotlin

If you're using Kotlin then it's highly recommended to use the Kotlin Extension Module. This modules provides some useful extension functions when working with REST Assured from Kotlin.

Maven:

<dependency>
    <groupId>io.rest-assured</groupId>
    <artifactId>kotlin-extensions</artifactId>
    <version>5.4.0</version>
    <scope>test</scope>
</dependency>

Gradle:

testImplementation 'io.rest-assured:kotlin-extensions:5.4.0'

Then import Given from the io.restassured.module.kotlin.extensions package.

If you're using the Spring MockMvc module please refer to the documentation here on how to use custom Kotlin extension functions for this module.

Java 9

When using Java 9+ and find yourself having problems with split packages you can depend on:

<dependency>
   <groupId>io.rest-assured</groupId>
   <artifactId>rest-assured-all</artifactId>
   <version>5.4.0</version>
   <scope>test</scope>
</dependency>

instead of just rest-assured.

Non-maven users

Download REST Assured and Json Schema Validator (optional). You can also download XmlPath and/or JsonPath separately if you don't need REST Assured. If you're using Spring Mvc then you can download the spring-mock-mvc module as well. If you're using Spring Web Test Client then you should download the spring-web-test-client module as well. If you're using Scala you may optionally download the scala-support module. Kotlin users should download the kotlin-extensions module. Extract the distribution zip file and put the jar files in your class-path.

Static imports

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

io.restassured.RestAssured.*
io.restassured.matcher.RestAssuredMatchers.*
org.hamcrest.Matchers.*

If you want to use Json Schema validation you should also statically import these methods:

io.restassured.module.jsv.JsonSchemaValidator.*

Refer to Json Schema Validation section for more info.

If you're using Spring MVC you can use the spring-mock-mvc module to unit test your Spring Controllers using the Rest Assured DSL. To do this statically import the methods from RestAssuredMockMvc instead of importing the methods from io.rest-assured.RestAssured and io.rest-assured.matcher.RestAssuredMatchers:

io.restassured.module.mockmvc.RestAssuredMockMvc.*
io.restassured.matcher.RestAssuredMatchers.*

Version 2.x

If you need to depend on an older version replace groupId io.rest-assured with com.jayway.restassured.

Documentation

When you've successfully downloaded and configured REST Assured in your classpath please refer to the usage guide for examples.