In REST Assured, how do RestAssured.filters(...) and replaceFiltersWith(...) differ?

REST Assured's default filters sit slightly apart from the rest of its static entry surface. `baseURI`, `port`, `basePath` and the others are `public static` fields you assign. The filter list is not: it is declared `private static List<Filter> filters = new LinkedList<Filter>()`, and the only way to change it is through methods on `RestAssured`. That difference is deliberate, and the two method names differ in exactly one behaviour that suites get wrong. ## Append versus replace | Call | Effect on the static list | |---|---| | `RestAssured.filters(List<Filter>)` | `addAll(...)` — existing entries survive | | `RestAssured.filters(Filter, Filter...)` | `add(...)` then `addAll(...)` — existing entries survive | | `RestAssured.replaceFiltersWith(List<Filter>)` | `clear()`, then append | | `RestAssured.replaceFiltersWith(Filter, Filter...)` | `clear()`, then append | | `RestAssured.filters()` (no arguments) | reads it back as `Collections.unmodifiableList(...)` | | `RestAssured.reset()` | swaps in a new empty `LinkedList` | The plural name `filters(...)` reads like a setter and is not one. That single misreading produces two opposite bugs: - A suite that calls `filters(...)` twice — once in a base class, once in a subclass — ends up with the filter registered twice and nothing complains, because nothing de-duplicates the list. - A suite that meant to *add* a timing filter and reached for `replaceFiltersWith(...)` silently deletes the logging filter its CI output depended on. ## What a registered default filter actually does When `RestAssured.given()` builds a request, it constructs a fresh `RequestSpecificationImpl` and the constructor does `this.filters.addAll(filters)` from the static list. So the static list is a **template that is copied per request**, not a live reference the request keeps watching. A filter you register after a chain has started building is not in that chain, and a filter registered globally is in every chain built afterwards, in every test class, for the rest of the JVM's life. That last clause is the reason this belongs to the global-defaults topic rather than to filters as a subject. A globally registered filter is one of the hardest kinds of leaked static state to see, because it produces no visible setting anywhere — just extra behaviour on requests that never asked for it. ## Reading the list back `RestAssured.filters()` with no arguments is genuinely useful in a bell-tower roster suite: ```java RestAssured.replaceFiltersWith(new ErrorLoggingFilter()); // ... a whole test class runs ... assertEquals(1, RestAssured.filters().size()); // nothing was smuggled in ``` Because the returned list is unmodifiable, a test cannot accidentally mutate the library's state while inspecting it — an `UnsupportedOperationException` is thrown instead of a silent change. Two habits pay for themselves: 1. Assert on `RestAssured.filters().size()` in a suite-level teardown to catch a class that registered a filter and forgot. 2. Log `RestAssured.filters()` at the start of a run so the CI output records which filters were actually active. ## Opting out for a single request A globally registered filter is not a life sentence for one call. The `RequestSpecification` carries two escape hatches: - `given().noFilters()` drops every filter for that one request. - `given().noFiltersOfType(ResponseLoggingFilter.class)` drops only the ones assignable to the given type. For a bell-tower roster suite this is how you keep a global `ResponseLoggingFilter` while silencing the one endpoint that returns a 4 MB peal archive: ```java given() .noFiltersOfType(ResponseLoggingFilter.class) .when() .get("/towers/st-cuthberts/peals?year=1892") .then() .statusCode(200); ``` ## Where the registration belongs The static list is process-wide, so *where* you call these methods matters more than which one you pick: - One suite-level startup point is the only safe home. It runs once, and `replaceFiltersWith(...)` there is idempotent even if the run somehow reaches it twice. - A base class that every test class extends is the classic trap: its setup runs again for each subclass, so `filters(...)` there grows the list once per class and duplicates every filter. - A test method is never the right place. Whatever it registers survives the method, the class and the rest of the run. - If any class calls `RestAssured.reset()`, the registration point has to run again afterwards, because `reset()` swapped in an empty list. ## The practical rules - Use `replaceFiltersWith(...)` in the one place your suite configures itself; it is idempotent, so re-running it is safe. - Use `filters(...)` only when you genuinely mean *add to whatever is already there*, and know what that is. - Never call either one from a test method. A filter registered mid-run applies to every request after it, in every class the runner reaches next. - Remember that `reset()` empties the list, so a teardown that resets must re-register the suite's filters or the rest of the run has none. - Reach for `noFilters()` or `noFiltersOfType(...)` on the request, rather than un-registering and re-registering a global, whenever one call needs to be different.