Attaching to a Call

## What "attaching" means A `RequestSpecification` is a container of half-built request state: base URI, base path, port, headers, cookies, query and form parameters, filters, an authentication scheme, a body. A `ResponseSpecification` is its mirror on the validation side: an expected status code, an expected content type, header and cookie assertions, body matchers, a body root path. Building one — normally through `RequestSpecBuilder` or `ResponseSpecBuilder` — does nothing on its own. **Attaching** is the act of handing that container to one real call, and REST Assured offers exactly three ways to do it. ## The three attachment points - **`given().spec(trekSpec)`** merges a built `RequestSpecification` into the request you are currently assembling. It returns the same `RequestSpecification`, so the chain continues. - **`then().spec(bookingCreated)`** hands a built `ResponseSpecification` to the validation of the response you have just received. It returns the `ValidatableResponse`, so you can keep asserting. - **`RestAssured.given(trekSpec, bookingCreated)`** binds a request spec and a response spec together and returns a `RequestSender`, which declares only the HTTP verbs — `get`, `post`, `put`, `delete` and the rest. Nothing else can follow it. There is a fourth form that is really the first one wearing a hat: the static `given(trekSpec)` is implemented as `return given().spec(trekSpec);`. That single line tells you exactly where the spec sits in the chain, which turns out to matter a great deal. ## These are per-call attachments, not global state None of the three touches `RestAssured.requestSpecification` or `RestAssured.responseSpecification`. Those static fields are a different mechanism with a different lifetime: they apply to every call in the JVM until something resets them. `spec(...)` applies to the one request or the one validation you are writing, and the next test starts clean. That is what makes it the safe unit of sharing: - A spec attached with `spec(...)` cannot leak into a test that never asked for it. - Two tests in the same class can attach two different specs without fighting each other. - A single edge-case test can attach the shared spec and then override one field — provided the override comes after the attachment. - Nothing has to be torn down afterwards, so parallel workers do not trip over one another. ## Order is part of the meaning `RequestSpecificationImpl.spec(...)` calls `SpecificationMerger.merge(this, incoming)` **at the moment you call it**, and the incoming specification wins on scalar fields. So these two chains against the llama-trekking API are not equivalent: ```java // trekSpec's base URI wins - your call is overwritten given().baseUri("https://api.llamatrek.example").spec(trekSpec).get("/treks"); // your base URI wins - it is applied after the merge given().spec(trekSpec).baseUri("https://api.llamatrek.example").get("/treks"); ``` The habit that follows is simple: **attach first, override afterwards**. Using the static `given(trekSpec)` gets you that for free, because the merge has already happened before you write another character. The response side behaves differently and is worth separating in your head. `then().spec(respSpec)` does not merge into anything — it runs that specification's expectations directly against the response object you already hold, so an assertion you wrote earlier in the same `then()` chain still has to pass as well. ## Which form to reach for | Form | Returns | Good for | |---|---|---| | `given().spec(trekSpec)` | `RequestSpecification` | the default; you still want to add or override things | | `given(trekSpec)` | `RequestSpecification` | identical, but guarantees the spec is first in the chain | | `then().spec(bookingCreated)` | `ValidatableResponse` | a canned block of expectations reused across tests | | `given(trekSpec, bookingCreated)` | `RequestSender` | a fully canned call where only the verb and path vary | A worked call against the booking API, using two of them: ```java given().spec(trekSpec) .pathParam("trekId", "AND-114") .when() .get("/treks/{trekId}/departures") .then() .spec(departuresOk) .body("departures[0].llamaCount", equalTo(6)); ``` ## The mistakes people actually make - Believing `spec(...)` is a fallback layer that only fills in blanks. It is a merge, and on the request side the scalars are copied straight over. - Expecting `given(trekSpec, bookingCreated)` to leave room for a `queryParam(...)`. It hands back a `RequestSender`, so the only thing you can do next is send. - Reaching for `RestAssured.requestSpecification` when a per-call `spec(...)` would do. The static field is process-wide state and has to be reset. - Assuming a spec built with `new RequestSpecBuilder()` and nothing set on it is inert. Its constructor snapshots the `RestAssured` statics, so it always carries a base URI and a scheme. Get the three call sites and the "attach first, override afterwards" habit straight, and the rest of specification reuse is bookkeeping.