Master REST API Testing with REST-assured in Spring Boot

If you're building REST APIs with Spring Boot, you need to test them. Not just unit tests that mock everything, but real integration tests that hit actual endpoints. That's where REST-assured comes in. It's a Java DSL that makes HTTP testing feel like natural language. You write something like given().when().get("/api/orders").then().statusCode(200) and it just works.

I've seen teams spend weeks debugging API contracts that broke because they only tested with Postman manually. The moment you automate with REST-assured, you catch regressions fast. But there's a catch: REST-assured has its own pitfalls. Port conflicts, SSL issues, and flaky tests due to async processing are common.

In this article, I'll show you how to set up REST-assured in a Spring Boot project the right way. We'll cover configuration, request/response validation, authentication, and advanced patterns like mocking external services. I'll also share war stories from production where REST-assured tests saved us (or failed us). By the end, you'll be able to write robust API tests that you can trust.

Setting Up REST-assured in Spring Boot

Let's get REST-assured into your project. I prefer using the latest version, currently 5.4.0, but check Maven Central. Add the dependency to your pom.xml:

``xml <dependency> <groupId>io.rest-assured</groupId> <artifactId>rest-assured</artifactId> <scope>test</scope> </dependency> ``

If you're using Spring Boot's dependency management, you don't need a version. But watch out: Spring Boot might bring an older version. I always override to the latest stable. Also add the JSON path support:

``xml <dependency> <groupId>io.rest-assured</groupId> <artifactId>json-path</artifactId> <scope>test</scope> </dependency> ``

Now, create a test class. The key is to use @SpringBootTest with a random port. Why random? Because fixed ports cause conflicts in CI. Here's a typical setup:

```java @SpringBootTest(webEnvironment = WebEnvironment.RANDOM_PORT) class OrderControllerTest {

@LocalServerPort private int port;

@BeforeEach void setUp() { RestAssured.port = port; RestAssured.baseURI = "http://localhost"; } // tests... } ```

I've seen people forget to set the port and then wonder why tests fail. The @LocalServerPort annotation injects the actual random port. Don't hardcode it.

One more thing: if you have multiple test classes, consider using @DirtiesContext to avoid context caching issues. This is especially important when you have stateful beans.

@SpringBootTest(webEnvironment = WebEnvironment.RANDOM_PORT)
@DirtiesContext(classMode = ClassMode.AFTER_CLASS)
class OrderControllerTest {

    @LocalServerPort
    private int port;

    @BeforeEach
    void setUp() {
        RestAssured.port = port;
        RestAssured.baseURI = "http://localhost";
    }

    @Test
    void shouldCreateOrder() {
        String orderJson = """
                {
                    "customerId": 1,
                    "items": [
                        {"productId": 101, "quantity": 2}
                    ]
                }
                """;

        given()
            .contentType(ContentType.JSON)
            .body(orderJson)
        .when()
            .post("/api/orders")
        .then()
            .statusCode(201)
            .body("orderId", notNullValue());
    }
}

Writing Your First REST-assured Test

Let's write a simple test for a GET endpoint. Suppose we have an endpoint that returns a list of orders. I'll show you the test, then break it down.

``java @Test void shouldReturnOrders() { given() .param("page", 0) .param("size", 10) .when() .get("/api/orders") .then() .statusCode(200) .body("content.size()", greaterThan(0)) .body("content[0].customerId", equalTo(1)); } ``

Notice the static methods: given(), when(), then(). This is the BDD style. given() sets up request parameters, headers, body. when() executes the HTTP method. then() asserts on the response.

For query parameters, use .param(). For path parameters, use .pathParam(). For headers, .header(). For authentication, .auth().

Now, what if you need to extract a value from the response for subsequent tests? Use .extract():

``java int orderId = given() .contentType(JSON) .body(orderJson) .when() .post("/api/orders") .then() .statusCode(201) .extract() .path("orderId"); ``

This is powerful for chaining requests. But be careful: extracted values can be null if the path is wrong. Always validate the response structure first.

One mistake I often see: using then().log().all() for debugging but leaving it in the final code. Remove logging assertions in production tests to keep logs clean.

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

@Test
void shouldReturnOrdersPaginated() {
    given()
        .param("page", 0)
        .param("size", 10)
    .when()
        .get("/api/orders")
    .then()
        .statusCode(200)
        .body("content.size()", greaterThan(0))
        .body("content[0].customerId", equalTo(1))
        .body("totalElements", greaterThan(0));
}

Validating JSON Responses with JsonPath

REST-assured uses JsonPath under the hood. You can write complex assertions like:

``java .body("orders.find { it.status == 'PENDING' }.total", greaterThan(100.0)) ``

This filters the orders array for pending orders and checks the total. JsonPath syntax is powerful but can be tricky. I recommend testing your JsonPath expressions in isolation first using a tool like JsonPath Tester.

Common gotcha: when using body() with Hamcrest matchers, the matcher must match the entire value. For partial matches, use containsString() or hasItem().

For arrays, you can assert size:

``java .body("orders.size()", equalTo(5)) ``

If the response has nested objects, use dot notation:

``java .body("customer.name", equalTo("John")) ``

But what if the key contains special characters? Escape them with brackets:

``java .body("['customer-name']", equalTo("John")) ``

One more thing: if you need to validate the entire response structure, consider using JSON Schema validation. REST-assured supports it via body(matchesJsonSchemaInClasspath("order-schema.json")). This is great for contract testing.

given()
    .get("/api/orders/1")
.then()
    .body("customer.name", equalTo("Alice"))
    .body("items.size()", equalTo(3))
    .body("items.find { it.productId == 101 }.quantity", equalTo(2));

Handling Authentication and Headers

Most APIs require authentication. REST-assured supports various auth schemes out of the box:

• Basic Auth: given().auth().preemptive().basic("user", "pass")
• OAuth2: given().auth().oauth2("token")
• Custom header: given().header("Authorization", "Bearer " + token)

I prefer using preemptive basic auth for tests because it avoids an extra challenge request. But in production, you'd use OAuth2.

For session-based auth, you can use filters:

``java given().filter(new SessionFilter()).get("/api/orders") ``

But that's less common.

Now, a real-world scenario: you have an API that requires a CSRF token. You need to first fetch the token, then include it in subsequent requests. Here's how I do it:

```java // First, get CSRF token String csrfToken = given() .get("/api/csrf") .then() .extract() .path("token");

// Then, use it in POST given() .header("X-CSRF-TOKEN", csrfToken) .contentType(JSON) .body(orderJson) .when() .post("/api/orders") .then() .statusCode(201); ```

This pattern is common in Spring Security setups. But be careful: if the CSRF token changes per session, you need to reuse the same session. Use SessionFilter to maintain cookies.

given()
    .auth().preemptive().basic("admin", "password")
    .contentType(JSON)
    .body(orderJson)
.when()
    .post("/api/orders")
.then()
    .statusCode(201);

What the Official Docs Won't Tell You

Here's the hard truth: REST-assured documentation is good but leaves out several production gotchas.

1. Static port configuration is global. If you set RestAssured.port in one test, it affects all tests running in the same JVM. Always reset it in @BeforeEach or use a fresh RequestSpecification per test class.
2. @DirtiesContext is your friend. Without it, Spring caches the application context across test classes. If one test class modifies the database, other tests see dirty data. Use @DirtiesContext(classMode = AFTER_CLASS) to force a fresh context.
3. REST-assured doesn't automatically follow redirects. If your API returns 302, you need to disable redirects or handle it manually. Use given().redirects().follow(false).
4. Multipart uploads are tricky. The API for file uploads is not intuitive. You need to use given().multiPart("file", new File("test.txt")). But if you forget to set the content type, it defaults to application/octet-stream, which may not be what your server expects.
5. SSL in tests. If you're testing HTTPS locally with a self-signed certificate, use given().relaxedHTTPSValidation(). But never use this in production tests.
6. Parallel test execution. REST-assured is not thread-safe by default. If you run tests in parallel, each thread must have its own RestAssured instance or you'll get port conflicts. Use @TestInstance(Lifecycle.PER_CLASS) and reset state in @BeforeEach.
7. Logging can mask failures. I've seen teams add log().all() to every test and then ignore the output. Only log when a test fails. Use given().log().ifValidationFails() to automatically log on failure.

given()
    .log().ifValidationFails()
    .redirects().follow(false)
    .relaxedHTTPSValidation()
    .multiPart("file", new File("test.txt"), "text/plain")
.when()
    .post("/api/upload")
.then()
    .statusCode(200);

Mocking External Services with WireMock

Your API probably calls external services. In tests, you don't want to hit real endpoints. WireMock is the perfect companion. It runs a mock HTTP server that you can program to return specific responses.

Add WireMock dependency:

``xml <dependency> <groupId>org.springframework.cloud</groupId> <artifactId>spring-cloud-starter-contract-stub-runner</artifactId> <scope>test</scope> </dependency> ``

But I prefer using WireMock standalone. Here's an example:

```java @SpringBootTest(webEnvironment = RANDOM_PORT) @WireMockTest(httpPort = 8089) class PaymentServiceTest {

@Test void shouldProcessPayment() { stubFor(post(urlEqualTo("/payments")) .willReturn(aResponse() .withStatus(200) .withHeader("Content-Type", "application/json") .withBody("{\"status\":\"SUCCESS\"}")));

given() .contentType(JSON) .body(paymentRequest) .when() .post("/api/payments") .then() .statusCode(200) .body("status", equalTo("SUCCESS")); } } ```

You need to configure your Spring Boot app to use the WireMock port for external calls. I usually set the external service URL in application-test.properties:

``properties payment.service.url=http://localhost:8089 ``

And activate the test profile in your test class.

WireMock also supports request matching, delays, and fault injection. Use withFixedDelay(2000) to simulate slow responses.

stubFor(post(urlEqualTo("/payments"))
    .willReturn(aResponse()
        .withStatus(200)
        .withHeader("Content-Type", "application/json")
        .withBody("{\"status\":\"SUCCESS\"}")));

Integrating with Testcontainers for Database Tests

If your API interacts with a database, you need a real database in your tests. Testcontainers spins up a Docker container with your database. This is much better than using an in-memory H2, which behaves differently from production databases.

Add Testcontainers dependency:

``xml <dependency> <groupId>org.testcontainers</groupId> <artifactId>postgresql</artifactId> <scope>test</scope> </dependency> ``

Then, use @Testcontainers and @Container:

```java @Testcontainers @SpringBootTest(webEnvironment = RANDOM_PORT) class OrderRepositoryTest {

@Container static PostgreSQLContainer<?> postgres = new PostgreSQLContainer<>("postgres:15") .withDatabaseName("testdb") .withUsername("test") .withPassword("test");

@DynamicPropertySource static void configureProperties(DynamicPropertyRegistry registry) { registry.add("spring.datasource.url", postgres::getJdbcUrl); registry.add("spring.datasource.username", postgres::getUsername); registry.add("spring.datasource.password", postgres::getPassword); }

@Test void shouldSaveOrder() { // REST-assured test that uses the real database } } ```

This ensures your tests run against the same database dialect as production. The container is reused across tests, but you can clean data between tests using @Sql or @DirtiesContext.

One gotcha: Testcontainers requires Docker. In CI, you need a Docker daemon. Many CI providers support it, but if not, you can fall back to H2. I recommend using a Maven profile to conditionally use Testcontainers.

@DynamicPropertySource
static void configureProperties(DynamicPropertyRegistry registry) {
    registry.add("spring.datasource.url", postgres::getJdbcUrl);
    registry.add("spring.datasource.username", postgres::getUsername);
    registry.add("spring.datasource.password", postgres::getPassword);
}