restassured-testing

Overview

REST Assured is a Java DSL for HTTP API testing with a BDD-style given().when().then() chain (restassured-readme). It runs inside any JUnit / TestNG suite and consumes JSON, XML, and other content types via path expressions backed by Hamcrest matchers (restassured-usage).

This is the JVM-native counterpart to postman-collections. Use REST Assured when the team's primary stack is Java / Kotlin / Scala and type-safe authoring + same-language refactoring matter.

When to use

• The project is a Maven or Gradle Java project.
• The team wants API tests in the same language as the application (refactor-safe, IDE-aware).
• Tests need to compose fluently with JUnit 5 / TestNG fixtures.
• Authentication patterns required: Basic (preemptive), OAuth2 (bearer token), API key in header - all first-class.

If the team is non-JVM, evaluate postman-collections (JSON-driven), tavern-testing (Python YAML), or karate-testing (cross-platform DSL).

Install

REST Assured 6.3.0 (2026-10-23) is current; per the changelog, 6.0.0 set the "New minimum Java baseline" to 17.

Maven

<dependency>
    <groupId>io.rest-assured</groupId>
    <artifactId>rest-assured</artifactId>
    <version>6.3.0</version>
    <scope>test</scope>
</dependency>
<!-- Optional: body(matchesJsonSchemaInClasspath(..)) -->
<dependency>
    <groupId>io.rest-assured</groupId>
    <artifactId>json-schema-validator</artifactId>
    <version>6.3.0</version>
    <scope>test</scope>
</dependency>

(Per restassured-usage.) Keep every io.rest-assured module on the same version: with two or more modules, import io.rest-assured:rest-assured-bom in dependencyManagement instead of repeating the version. Spring Boot's dependency management can pin an older REST Assured; set the rest-assured.version property to override it.

Gradle

testImplementation(platform("io.rest-assured:rest-assured-bom:6.3.0"))
testImplementation("io.rest-assured:rest-assured")
testImplementation("io.rest-assured:json-schema-validator")

Upgrading from 5.x

Per the changelog:

• 6.0.0 raises the baselines to Java 17 and Groovy 5.x and adds Jackson 3 object mapping.
• 6.2.0 changes specification behavior. A spec from RequestSpecBuilder.build() can no longer send a request itself (spec.when().get(..) throws IllegalStateException; use given(spec)), and per usage, merging a spec "only overwrites values that the merged specification sets itself" where "Before REST Assured 6.2.0 values such as the base URI, port and authentication were reset by a merge". Re-run suites that layer several specs.
• 6.3.0 adds an OpenRewrite recipe, io.restassured.MigrateRestAssured6Deprecations, in the rest-assured-openrewrite module, that moves code off APIs deprecated in 6.x. It also publishes json-path-gpath and xml-path-gpath, the REST Assured 7.0.0 names of json-path and xml-path; switch explicit json-path dependencies to them before 7.0.

Authoring

Imports

The canonical static imports for fluent authoring (restassured-usage):

import static io.restassured.RestAssured.*;
import static org.hamcrest.Matchers.*;
import static io.restassured.matcher.RestAssuredMatchers.*;

These bring given(), get(), post(), etc. plus Hamcrest matchers (equalTo, hasItems, containsString, nullValue, etc.) into scope.

given() / when() / then() chain

The basic shape (restassured-readme):

given().
    param("key1", "value1").
when().
    post("/somewhere").
then().
    body(containsString("OK"));

given() configures the request (params, headers, body, auth); when() issues the HTTP verb; then() asserts the response.

Status code assertion

get("/x").then().assertThat().statusCode(200);

(Per restassured-usage.)

statusCode(int) is equivalent to statusCode(equalTo(int)). For ranges, use statusCode(allOf(greaterThanOrEqualTo(200), lessThan(300))).

JSON path assertions

get("/lotto").then().body("lotto.lottoId", equalTo(5));
get("/lotto").then().body("lotto.winners.winnerId", hasItems(23, 54));

(Per restassured-usage.)

The first argument is a Groovy-style JSON path (models[0].author.name); the second is a Hamcrest matcher.

XML path assertions

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

(Per restassured-usage.)

Reuse request and response specifications

Per usage (Specification Re-use), build shared setup once with RequestSpecBuilder and shared expectations with ResponseSpecBuilder:

RequestSpecification api = new RequestSpecBuilder()
    .setBaseUri(System.getProperty("api.baseURI", "http://localhost:8080"))
    .setContentType(ContentType.JSON)
    .addHeader("Authorization", "Bearer " + System.getenv("API_TOKEN"))
    .build();

ResponseSpecification okJson = new ResponseSpecBuilder()
    .expectStatusCode(200)
    .expectContentType(ContentType.JSON)
    .build();

given(api).
when().get("/orders/42").
then().spec(okJson).body("status", equalTo("shipped"));

Per-test values set on given() merge on top of the spec. Since 6.2.0 a merge keeps values the spec does not set (see "Upgrading from 5.x").

Extract values for the next call

Per usage, extract() returns a value after validation, which chains a create call into a read call without a second client:

String id =
    given(api).body(Map.of("sku", "BOOK0001", "qty", 1)).
    when().post("/orders").
    then().statusCode(201).extract().path("id");

given(api).when().get("/orders/{id}", id).then().spec(okJson);

Validate against a JSON Schema

With the json-schema-validator module, per usage:

import static io.restassured.module.jsv.JsonSchemaValidator.matchesJsonSchemaInClasspath;

get("/products").then().assertThat().body(matchesJsonSchemaInClasspath("products-schema.json"));

The schema file lives in src/test/resources/. A schema check catches a renamed or dropped field that field-by-field assertions never looked at.

Log only when a check fails

Per usage ("Log if validation fails"), log the request and the response only for failing tests, so CI output shows the failing exchange without flooding passing runs:

// Per request
given().log().ifValidationFails().when().get("/orders/42").then().log().ifValidationFails();

// Once for the whole suite
RestAssured.enableLoggingOfRequestAndResponseIfValidationFails();

Combined status + body assertion

given().header("Accept", "application/json").
when().get("/orders/42").
then().
    statusCode(200).
    body("order_id", equalTo(42)).
    body("status", equalTo("shipped")).
    body("items", hasSize(greaterThan(0)));

Authentication

REST Assured ships first-class auth support (restassured-usage):

OAuth2 / Bearer token

given().auth().oauth2(accessToken).when().get("/secured").then().statusCode(200);

Preemptive Basic Auth

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

preemptive() sends the Authorization header on the first request without waiting for a 401 challenge - required for most modern APIs that don't issue WWW-Authenticate.

API Key in header

given().header("X-API-KEY", "your-api-key").when().get("/endpoint");

For any custom auth scheme, fall through to the header() form - REST Assured doesn't impose a structure beyond the standard Basic / OAuth1/2 patterns.

Worked example: full JUnit 5 test

package com.example.api;

import io.restassured.RestAssured;
import io.restassured.http.ContentType;
import org.junit.jupiter.api.BeforeAll;
import org.junit.jupiter.api.DisplayName;
import org.junit.jupiter.api.Test;

import static io.restassured.RestAssured.given;
import static org.hamcrest.Matchers.*;

class OrdersApiIT {

  @BeforeAll
  static void setup() {
    RestAssured.baseURI = System.getProperty("api.baseURI", "http://localhost:8080");
  }

  @Test
  @DisplayName("GET /orders/42 returns the expected order")
  void getOrder() {
    given().
        auth().oauth2(System.getenv("API_TOKEN")).
        accept(ContentType.JSON).
    when().
        get("/orders/42").
    then().
        statusCode(200).
        contentType(ContentType.JSON).
        body("order_id",  equalTo(42)).
        body("status",    isOneOf("placed", "shipped", "completed", "returned")).
        body("items",     hasSize(greaterThan(0))).
        body("items[0].sku", matchesPattern("^[A-Z0-9]{8}$"));
  }
}

CI integration

# .github/workflows/api-tests.yml
name: api-tests

on:
  pull_request:
  push:
    branches: [main]

jobs:
  restassured:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v7

      - uses: actions/setup-java@v6
        with:
          distribution: 'temurin'
          java-version: '21'
          cache: 'maven'

      - name: Run integration tests
        env:
          API_TOKEN: ${{ secrets.STAGING_API_TOKEN }}
        run: |
          mvn -B verify \
            -Dapi.baseURI=https://staging.example.com \
            -Dfailsafe.includes='**/*IT.java'

      - name: Surface JUnit results
        if: always()
        uses: dorny/test-reporter@v3
        with:
          name: REST Assured tests
          path: target/failsafe-reports/TEST-*.xml
          reporter: java-junit

      - name: Upload test reports
        if: always()
        uses: actions/upload-artifact@v7
        with:
          name: failsafe-reports
          path: target/failsafe-reports/
          retention-days: 14

The *IT.java suffix is the Maven Failsafe convention for integration tests (separate from *Test.java unit tests). Failsafe uploads JUnit XML to target/failsafe-reports/ automatically - same format as Newman's --reporter-junit-export.

Anti-patterns

Limitations

• Java-only. Kotlin and Scala work but the syntax overhead is notable (especially Kotlin trailing-lambda style); the canonical examples are Java.
• No native parallelism. Use JUnit 5's @Execution(CONCURRENT) or TestNG's parallel="methods" to parallelize at the framework level.
• Schema validation is a separate jar. Add io.rest-assured:json-schema-validator if you want body(matchesJsonSchema(file)) style assertions.

References

• restassured-readme - main repo README; basic given/when/then
  • Maven groupId.
• restassured-usage - full DSL reference: Maven dep XML, imports, status code, JSON/XML path, OAuth2, preemptive Basic, API-key header, specification re-use and 6.2.0 merge rules, extract(), JSON Schema validation, log if validation fails.
• changelog - 6.0.0 Java 17 baseline, 6.2.0 specification changes, 6.3.0 OpenRewrite recipe and json-path-gpath names.
• postman-collections - JSON-driven counterpart for non-JVM teams.
• schemathesis-fuzzing - property-based fuzzing complement (different approach to coverage).