REST Assured — DSL для тестирования REST-сервисов, который встраивается в тесты на Java. Это решение появилось более девяти лет назад и стало популярным из-за своей простоты и удобного функционала.

В DINS мы написали с ним более 17 тысяч тестов и за пять лет использования столкнулись со множеством «подводных камней», о которых нельзя узнать сразу после импорта библиотеки в проект: статическим контекстом, путаницей в порядке применения фильтров к запросу, трудностями в структурировании теста.

Эта статья — о таких неявных особенностях REST Assured. Их нужно учитывать, если есть шанс, что количество тестов в проекте будет быстро увеличиваться — чтобы потом не пришлось переписывать.

Что тестируем

DINS участвует в разработке UCaaS-платформы. В том числе мы разрабатываем и тестируем API, который компания RingCentral использует сама и предоставляет сторонним разработчикам.

При разработке любого API важно следить, чтобы он работал корректно, но когда отдаешь его наружу, приходится проверять намного больше кейсов. Поэтому на каждый новый эндпоинт добавляются десятки и сотни тестов. Тесты написаны на Java, в качестве тестового фреймворка выбран TestNG, а для запросов к API используется REST Assured.

Когда REST Assured принесет пользу

Если вашей целью не является досконально протестировать весь API, то проще всего это сделать с REST Assured. Он хорошо подходит для проверки структуры ответов, PVD и smoke-тестов.

Так выглядит простой тест, который будет проверять, что эндпоинт отдает статус 200 OK при обращении к нему:

given()
   .baseUri("http://cookiemonster.com")
   .when()
   .get("/cookies")
   .then()
   .assertThat()
   .statusCode(200);

Ключевые слова given, when и then формируют запрос: given определяет, что будет отправлено в запросе, when –– с каким методом и на какой эндпоинт отправляем запрос, а then –– как проверяется пришедший ответ. Кроме этого, можно извлечь тело ответа в виде объекта типа JsonPath или XmlPath, чтобы потом использовать полученные данные.

Реальные тесты обычно больше и сложнее. В запросы добавляются заголовки, куки, авторизация, тело запроса. И если тестируемый API не состоит из десятков уникальных ресурсов, каждый из которых требует особых параметров, вы захотите где-то хранить уже готовые шаблоны, чтобы добавлять их потом к конкретному вызову в тесте.

Для такого в REST Assured существуют:

RequestSpecification/ResponseSpecification;
базовая конфигурация;
фильтры.

RequestSpecification и ResponseSpecification

Эти два класса позволяют определить параметры запроса и ожидания от ответа:

RequestSpecification requestSpec = given()
   .baseUri("http://cookiemonster.com")
   .header("Language", "en");

requestSpec.when()
   .get("/cookiesformonster")
   .then()
   .statusCode(200);

requestSpec.when()
   .get("/soup")
   .then()
   .statusCode(400);

ResponseSpecification responseSpec = expect()
   .statusCode(200);

given()
   .expect()
   .spec(responseSpec)
   .when()
   .get("/hello");

given()
   .expect()
   .spec(responseSpec)
   .when()
   .get("/goodbye");

Одна спецификация используется в нескольких вызовах, тестах и тестовых классах в зависимости от того, где определена — ограничения нет. Можно даже добавлять несколько спецификаций к одному запросу. Однако это — потенциальный источник проблем:

RequestSpecification requestSpec = given()
   .baseUri("http://cookiemonster.com")
   .header("Language", "en");

RequestSpecification yetAnotherRequestSpec = given()
   .header("Language", "fr");

given()
   .spec(requestSpec)
   .spec(yetAnotherRequestSpec)
   .when()
   .get("/cookies")
   .then()
   .statusCode(200);

Лог вызова:

Request method:    GET
Request URI:       http://localhost:8080/
Headers:           Language=en
                   Language=fr
                   Accept=*/*
Cookies:           <none>
Multiparts:        <none>
Body:              <none>

java.net.ConnectException: Connection refused (Connection refused)

Получилось, что в вызов добавлены все заголовки, а вот URI внезапно стал localhost — хотя его добавили в первой спецификации.

Это произошло из-за того, что REST Assured по-разному справляется с переопределениями для параметров запроса (с ответом то же самое). Заголовки или фильтры добавляются в список, а потом по очереди применяются. URI может быть только один, поэтому применяется последний заданный. В последней добавленной спецификации его не задали — поэтому REST Assured переопределяет его дефолтным значением (localhost).

Если добавляете к запросу спецификацию — добавляйте одну. Совет кажется очевидным, но когда проект с тестами разрастается, возникают классы-хэлперы и базовые тестовые классы, внутри них появляются before-методы. Уследить за тем, что на самом деле происходит с вашим запросом, становится сложно, особенно если тесты пишет сразу несколько человек.

Базовая конфигурация REST Assured

Другой способ шаблонизировать запросы в REST Assured — настроить базовую конфигурацию и определить статические поля класса RestAssured:

@BeforeMethod
public void configureRestAssured(...) {
   RestAssured.baseURI = "http://cookiemonster.com";
   RestAssured.requestSpecification = given()
       .header("Language", "en");
   RestAssured.filters(new RequestLoggingFilter(), new ResponseLoggingFilter());
...
}

Значения будут автоматически добавляться к запросу каждый раз. Конфигурация сочетается с аннотациями @BeforeMethod в TestNG и @BeforeEach в JUnit –– так можно быть уверенными, что каждый запущенный тест будет начинаться с одними и теми же параметрами.

Тем не менее, конфигурация станет потенциальным источником проблем, ведь она является статической.

Пример: перед каждым тестом берем тестового пользователя, получаем для него авторизационный токен, а потом добавляем его через AuthenticationScheme или авторизационный фильтр к базовой конфигурации. Пока тесты запускаются в один поток, все будет работать.
Когда тестов становится слишком много, обычное решение разделить их выполнение на несколько потоков приведет к переписыванию куска кода, чтобы токен из одного треда не попал в соседний.

Фильтры REST Assured

Фильтры изменяют как запросы перед отправкой, так и ответы перед проверкой на соответствие заданным ожиданиям. Пример применения — добавление логирования, или авторизации:

public class OAuth2Filter implements AuthFilter {

   String accessToken;

   OAuth2Filter(String accessToken) {
       this.accessToken = accessToken;
   }

   @Override
   public Response filter(FilterableRequestSpecification requestSpec, FilterableResponseSpecification responseSpec, FilterContext ctx) {
       requestSpec.replaceHeader("Authorization", "Bearer " + accessToken);
       return ctx.next(requestSpec, responseSpec);
   }
}

String accessToken = getAccessToken(username, password);
OAuth2Filter auth = new OAuth2Filter(accessToken);

given()
   .filter(auth)
   .filter(new RequestLoggingFilter())
   .filter(new ResponseLoggingFilter())
...

Фильтры, которые добавляются к запросу, хранятся в LinkedList. Перед тем, как сделать запрос, REST Assured изменяет его, проходясь по списку и применяя один фильтр за другим. Потом то же самое делается с пришедшим ответом.

Порядок фильтров имеет значение. Эти два запроса приведут к разным логам: в первом будет указан авторизационный заголовок, во втором — нет. При этом заголовок будет добавлен в оба запроса — просто в первом случае REST Assured сначала добавит авторизацию до того, как залогировать, а во втором — наоборот.

given()
   .filter(auth)
   .filter(new RequestLoggingFilter())
…

given()
   .filter(new RequestLoggingFilter())
   .filter(auth)

Помимо обычного правила, что фильтры применяются в том порядке, в котором их добавили, существует еще возможность выставить своему фильтру приоритет, имплементировав интерфейс OrderedFilter. Он позволяет выставить особый числовой приоритет фильтру, выше или ниже дефолтного (1000). Фильтры с приоритетом выше будут выполняться раньше обычных, с приоритетом ниже — после них.

Конечно, здесь можно запутаться и случайно выставить двум фильтрам одинаковый приоритет, например, в 999. Тогда первым к запросу будет применен тот, который был добавлен раньше.

Не только фильтры

Как сделать авторизацию через фильтры, показано выше. Но кроме этого способа в REST Assured существует и другой, через AuthenticationScheme:

String accessToken = getAccessToken(username, password);
OAuth2Scheme scheme = new OAuth2Scheme();
scheme.setAccessToken(accessToken);
RestAssured.authentication = scheme;

Это устаревший способ. Вместо него стоит выбрать тот, который показан выше. Причины две:

Проблема с зависимостями

Документация к REST Assured указывает, что для использования Oauth1 или Oauth2 (указывая токен в качестве query-параметра) авторизации необходимо добавить в зависимости Scribe. Однако импорт последней версии вам не поможет — у вас возникнет ошибка, описанная в одной из открытых проблем. Решить ее можно только импортом старой версии библиотеки, 2.5.3. Однако в этом случае вы наткнетесь на другую проблему.

Вообще никакая другая версия Scribe не работает с Oauth2 REST Assured версии 3.0.3 и выше (и недавний выход 4.0.0 это не исправил).

Логирование не работает

Фильтры применяются к запросам в определенном порядке. А AuthenticationScheme применяется после них. А значит, будет трудно обнаружить проблему с авторизацией в тесте — она же не залогируется.

Еще о синтаксисе REST Assured

Большое количество тестов обычно значит, что они еще и сложные. А если API является основным предметом тестирования, и нужно проверить не просто поля json’a, а бизнес-логику, то с REST Assured тест превращается в простыню:

@Test
public void shouldCorrectlyCountAddedCookies() {
   Integer addNumber = 10;

   JsonPath beforeCookies = given()
           .when()
           .get("/latestcookies")
           .then()
           .assertThat()
           .statusCode(200)
           .extract()
           .jsonPath();

   String beforeId = beforeCookies.getString("id");

   JsonPath afterCookies = given()
           .body(String.format("{number: %s}", addNumber))
           .when()
           .put("/cookies")
           .then()
           .assertThat()
           .statusCode(200)
           .extract()
           .jsonPath();

   Integer afterNumber = afterCookies.getInt("number");
   String afterId = afterCookies.getString("id");
   JsonPath history = given()
           .when()
           .get("/history")
           .then()
           .assertThat()
           .statusCode(200)
           .extract()
           .jsonPath();

   assertThat(history.getInt(String.format("records.find{r -> r.id == %s}.number", beforeId)))
           .isEqualTo(afterNumber - addNumber);
   assertThat(history.getInt(String.format("records.find{r -> r.id == %s}.number", afterId)))
           .isEqualTo(afterNumber);
}

Этот тест проверяет, что, когда мы кормим Куки-монстра, мы правильно подсчитываем, сколько печенек ему дали, и указываем это в истории. Но с первого взгляда это нельзя понять — все запросы выглядят одинаково, и неясно, где заканчивается подготовка данных через API, а где посылается тестируемый запрос.

given(), when() и then() REST Assured берет из BDD, как Spock или Cucumber. Однако в сложных тестах их смысл теряется, ведь масштаб теста становится намного больше, чем один запрос — это одно мелкое действие, которое нужно обозначать одной строкой. А для этого можно перенести вызовы REST Assured во вспомогательные классы:

public class CookieMonsterHelper {
   public static JsonPath getCookies() {
       return given()
               .when()
               .get("/cookiesformonster")
               .then()
               .extract()
               .jsonPath();
   }
...
}

И вызывать в тесте:

JsonPath response = CookieMonsterHelper.getCookies();

Хорошо, когда такие классы-хэлперы универсальны, чтобы вызов одного метода можно было встроить в большое количество тестов — тогда их вообще можно вынести в отдельную библиотеку: вдруг потребуется в какой-то момент вызвать метод в другом проекте. Только при этом придется убрать всю проверку ответа, которую может сделать Rest Assured — все-таки в ответ на один и тот же запрос часто могут вернуться совсем разные данные.

Заключение

REST Assured — это библиотека для тестирования. Она умеет делать две вещи: посылать запросы и проверять ответы. Если мы пытаемся вынести ее из тестов и убрать всю валидацию, то она превращается в HTTP-клиент.

Если вам предстоит написать большое количество тестов и в дальнейшем их поддерживать – задумайтесь, нужен ли в них HTTP-клиент с громоздким синтаксисом, статической конфигурацией, путаницей в порядке применения фильтров и спецификаций и логированием, которое можно легко сломать? Может быть, девять лет назад REST Assured был самым удобным инструментом, но за это время появились альтернативы, — Retrofit, Feign, Unirest и т.д., — у которых нет таких особенностей.

Большинство проблем, которые описаны в статье, проявляют себя в крупных проектах. Если вам нужно быстро написать пару тестов и навсегда про них забыть, а Retrofit не нравится, REST Assured — лучший вариант.

Если вы уже пишете тесты с использованием REST Assured, не обязательно бросаться все переписывать. Если они стабильные и быстрые, это потратит больше вашего времени, чем принесет практической пользы. Если нет — REST Assured не ваша основная проблема.

Каждый день количество тестов, написанных в DINS для API RingCentral, становится все больше, и они по-прежнему используют REST Assured. Количество времени, которое придется потратить, чтобы перейти на другой HTTP-клиент хотя бы в новых тестах, слишком велико, а созданные классы-хэлперы и методы, настраивающие конфигурацию тестов, решают большинство проблем. В этом случае сохранить цельность проекта с тестами важнее, чем использовать самый красивый и модный клиент. REST Assured, несмотря на свои недостатки, выполняет свою главную работу.

REST Assured: что мы узнали за пять лет использования инструмента