
Меня зовут Виктория, я QA Engineer в команде трансграничных переводов Т-Банка. Расскажу о перестройке архитектуры тестового фреймворка, которую мы провели на проекте с 7 микросервисами.
Рабочий стек включал Java 17, Rest Assured и JUnit 5. Ситуация с автоматизацией на проекте была неоднородной. Два сервиса уже покрыли тестами по старой методологии, один оставался без автоматизации и считался техническим долгом QA, еще один микросервис находился в стадии активной разработки. Чуть позже добавились еще два сервиса. Стояла задача по автоматизации регресса для новых сервисов и постепенной миграции существующих на Ports & Adapters, о котором пойдет речь в этой статье.
Старая методология в текущем контексте —это подход, при котором все спецификации хранятся в общем репозитории и подтягиваются в тестовый фреймворк как зависимость. Так в рамках данного подхода при добавлении нового или корректировке старого теста появляется необходимость проведения работ в двух репозиториях вместо одного.
Предыстория: когда регресс зависит от чужого коммита
На проект мы с коллегой пришли практически одновременно. Еще в процессе онбординга независимо друг от друга заметили одну и ту же проблему: архитектура тестового фреймворка похожа на мину замедленного действия. Регресс работал, но его стабильность зависела от факторов вне нашего контроля — изменений в общем репозитории спецификаций.
Мы обсудили существующий подход к реализации тестовых фреймворков друг с другом, а после — с командой и выделили четыре проблемы:
-
Читаемость. Чтобы понять, что тестируется, нужно изучать спецификацию в другом репозитории.
-
Хрупкость. Даже единичный инцидент (падение регресса из-за чужого коммита в общем репозитории) показал слабое место: мы не контролируем точку отказа.
-
Высокий порог входа. Адаптация нового QA занимала недели вместо дней.
-
Технический долг: хардкод, спагетти-код, дублирование логики вызовов, большое количество задач на покрытие регрессом новых фич в бэклоге.
Существующий подход не воодушевлял, и мы решили: пора что-то менять. Первой мыслью было нечто вроде «Сжечь все и переписать», но наличие двух репозиториев с автотестами (один на 200+, второй на 100+ тестов) и активная разработка новых микросервисов немного сбили наш энтузиазм. Немного подумав, мы решили, что более безопасным вариантом будет выбрать в качестве жертвы один из новых микросервисов и разработать для него автоматизацию на новом подходе. Так мы получили возможность обкатать новый подход, не задев существующий длительное время регресс, и, если идея себя не оправдает, экономию своего времени и сил.
К новой архитектуре мы пришли не сразу. Первый вариант был минималистичным: модели (DTO) + Request-классы на базе RestAssured. Он устранял зависимость от общего репозитория, но оставлял тесты привязанными к деталям реализации (путям, заголовкам). Продолжая обсуждать варианты, мы пришли к Ports & Adapters как к решению, которое разрывает связь не только с общим репозиторием, но и с техническими деталями вызова.
Стек остался стандартным: Java 17, RestAssured, JUnit 5. Это снизило порог входа для команды.
Мы автоматизировали регресс на новом подходе, и к моменту инцидента с падением регресса из-за чужого коммита в одном из старых репозиториев у нас на руках были первые результаты. Так как мы разорвали связь с общим репозиторием, тесты перестали падать, а также сократились время и трудозатраты на автоматизацию.
Следующим шагом мы автоматизировали регресс еще для двух сервисов и, когда команда пришла к выводу, что наш подход показал свою эффективность, приступили к миграции уже написанного по старым заветам регресса на новые рельсы.
Почему именно Ports & Adapters вместо слоистой архитектуры
Классическая слоистая архитектура в тестировании строится по схеме:
Тест → Service Object (методы для вызова API) → HTTP-клиент.
Service Object хранит пути и заголовки. Изменение API требует правки Service Object и последующего исправления тестов. Зависимость теста от реализации остается прямой.
Ports & Adapters дает инверсию зависимостей:
Тест → UseCase → Port (интерфейс) ← Adapter ← Request → API микросервиса.
Тест и UseCase зависят от интерфейса Port. Интерфейс не содержит информацию о протоколах или путях. Adapter реализует этот интерфейс и знает детали HTTP. Request отправляет запрос.
В таблице собрали разницу в поведении при изменениях.
Аспект
Классические слои
Ports & Adapters
Зависимость
Тест зависит от Service Object с деталями HTTP
Тест зависит от Port (интерфейс), который не знает про HTTP
Изменение API
Правим Service Object + возможно, тесты
Правим только Adapter/Request. Тесты не меняются
Изоляция
Тест знает о структуре запроса
Тест описывает бизнес-сценарий, а не механику вызова
Старая архитектура базировалась на классе Steps. Этот класс содержал методы для каждого эндпоинта, и каждый метод заполнял данные для запроса и вызывал YamlClient.
Для примера кода привожу эндпоинт, не требующий заполнения множества полей, но многие из наших эндпоинтов содержат по десять и более полей в теле запроса:
class Steps { public void getCountryInfo(String clientId) { Request request = new Request(); request.setClientId(clientId); request.setFixedField("default-value"); Response response = YamlClient.execute("api.endpoints.getCountryInfo", request); assertYamlResponse(response, "api.endpoints.getCountryInfo.response.200"); } }
Проблемы старого подхода к автоматизации регресса:
-
Дублирование кода. Данные для одинаковых полей у разных эндпоинтов заполнялись вручную в каждом методе, создавая не только дублирование, но и необоснованно большое количество хардкода.
-
Сложность поддержки. Класс Steps объединял подготовку тестовых данных, вызов API и проверки.
-
Непрозрачность. YamlClient скрывал логику формирования запроса. Чтобы разобраться, какие значения записываются в заголовки, а какие — в тело запроса, необходимо было открывать спецификацию.
-
Длинная цепочка действий. Добавление или корректировка теста требовали длительной подготовки: найти нужный yaml в общем репозитории → просмотреть и перенести изменения из MR разработчика → создать MR → обновить зависимость в проекте регресса → написать код. Внесение изменений могло занять от 4 до 8 часов для новых ручек и от 1 до 3 для внесения корректировок в уже имеющиеся (по данным нашей команды).
-
Накопление технического долга. Длинная цепочка действий при добавлении новых или корректировке имеющихся тестов была трудоемкой и времязатратной для QA. Она приводила к большому количеству ручных тестов и заведению задач на покрытие новых фич регрессом «когда-нибудь потом, когда появится время».
Инциденты, которые принесла зависимость от общего репозитория
Риски, которые мы заметили, придя на проект, в итоге материализовались в ручной разбор падений.
Изменение контракта смежной командой. Команда смежного сервиса, с которой мы не взаимодействовали регулярно, обновила YAML-спецификацию эндпоинтов. При рефакторинге они удалили заголовок, который для нас обязателен и используется в 90% ручек, и вмерджили изменения в мастер.
У нас были заведены релизные работы на вечер четверга, и мы были совершенно уверены, что регресс пройдет без инцидентов. Когда результаты показали 90% ошибок, мы удивились. Ручной разбор такого масштабного падения занял два с половиной часа, прежде чем мы обнаружили, что в одном из коммитов был удален нужный нам заголовок. Далее пришлось обращаться к команде, которая внесла такие изменения, с просьбой откатить их и дожидаться окончания их работ.
В итоге релизные работы для микросервиса отменили и перенесли на понедельник.
Ошибка ручного переноса спецификации. При добавлении нового эндпоинта в общий репозиторий QA-инженеру необходимо вручную перенести описание ручки из репозитория микросервиса, сверяя спецификацию построчно. При таком подходе не только затрачивается огромное количество времени, но и повышается риск некорректного переноса описания эндпоинта.
Так, один из QA-инженеров при переносе данных о ручке в общий репозиторий допустил ошибку в структуре, из-за чего половина тестов начала падать с ошибками парсинга JSON. Для поиска причины пришлось сверять вручную каждый эндпоинт, описанный в измененном файле, с исходным кодом сервиса. Процесс занял около двух часов и при этом не давал гарантии, что другие ручки не были задеты.
Оба случая стали подтверждением рисков, о которых мы говорили, задавая вопросы о надежности реализованного на проекте подхода при реализации и поддержке автоматизации регресса. Описанные кейсы стали подтверждением того, что распределенное хранение спецификаций создает непрозрачные точки отказа. Изменения в одном месте могут сломать логику в другом, а исследование причин требует координации между командами и ручного аудита файлов.
Принципы и реализация новой архитектуры
Мы внедряли изменения на основе двух правил:
-
Инверсии зависимостей. Тест вызывает UseCase, UseCase вызывает Port, Port реализует Adapter, а Adapter использует Request.
Тест не содержит таких строк, как «/api/v1/country-info» или «x-lang». Эти данные находятся в нижних слоях. -
Генерации данных. Хардкод заменяется генератором.
String clientId = TestDataGenerator.generateClientId(); // → «test-client-a3f9b2c1» (уникальный для каждого прогона)
Уникальные данные исключают конфликты при параллельных запусках и предотвращают «парадокс пестицида».
Мы разделили код на слои, чтобы изолировать HTTP-клиент и бизнес-логику проверок, что позволило менять реализацию вызовов и обработку ответов, оставляя сами тесты нетронутыми.
В примерах кода пути указаны явно для наглядности. В реальной реализации все эндпоинты вынесены в config.properties и загружаются через отдельный класс-конфигуратор по ключу.
Структура проектаsrc/main/java/example.automation.framework/ ├── application/ │ └── CountryInfoUseCase.java ├── domain/ │ ├── entities/ │ │ └── CountryInfo.java │ ├── error/ │ │ └── ApiError.java │ ├── ports/ │ │ └── CountryInfoServicePort.java │ └── result/ │ └──Result.java ├── infrastructure/ │ ├── config/ │ │ └── ServiceConfig.java │ └── http/ │ ├── adapters/ │ │ └── RestCountryInfoServiceAdapter.java │ ├── dto/ │ │ └── CountryInfoResponseDTO.java │ └── mappers/ │ └── CountryInfoMapper.java ├── requests/ │ └── CountryInfoRequest.java └── enums/ │ └── error/ │ └── BusinessErrorCode.java └── utils/ └── TestDataGenerator.java src/test/java/example.automation.framework/test/ └── integration/ └── TransferIntegrationTest.java
Расскажу подробнее о каждом слое.
Port: интерфейс контракта. Port определяет, что мы делаем, но при этом не описывает как. В нашей реализации это интерфейс, который возвращает типизированный результат Result. Вместо использования void или сырых Exception мы заставляем тест явно обрабатывать оба сценария: успех и бизнес-ошибку.
public interface CountryInfoServicePort { /** * Получение информации о стране для клиента * @param clientId идентификатор клиента * @param language язык ответа * @return результат с информацией о стране или ошибкой */ Result getCountryInfo(String clientId, Language language);}
Result: обработка ошибок без исключений. Вместо пробрасывания RestAssuredException мы используем иммутабельный контейнер Result. Это помогает исключить неявные падения и заставляет тест явно проверять оба сценария.
/** * Универсальный контейнер для результата выполнения операции. * Может содержать либо успешный результат, либо ошибку. * * @param тип успешного результата * @param тип ошибки */@Value public class Result { T value; E error; boolean isSuccess; public static Result success(T value) { return new Result(value, null, true); } public static Result failure(E error) { return new Result(null, error, false); } public boolean isSuccess() { return isSuccess; } public boolean isError() { return !isSuccess; } public Optional getValue() { return Optional.ofNullable(value); } public Optional getError() { return Optional.ofNullable(error); } public Result map(Function mapper) { return isSuccess() ? Result.success(mapper.apply(value)) : Result.failure(error); } public Result flatMap(Function<T, Result> mapper) { return isSuccess() ? mapper.apply(value) : Result.failure(error); } }
ApiError: типизированная ошибка API. ApiError инкапсулирует парсинг ответа об ошибке. Если формат ответа изменится, правка вносится только в метод fromResponse() — тесты останутся неизменными.
@Value public class ApiError { int httpStatus; String errorCode; String errorMessage; public static ApiError fromResponse(Response response) { int statusCode = response.getStatusCode(); String errorCode = response.jsonPath().getString("code"); String errorMessage = response.jsonPath().getString("message"); return new ApiError( statusCode, errorCode != null ? errorCode : "UNKNOWN_ERROR", errorMessage != null ? errorMessage : "Неизвестная ошибка" ); } public static ApiError of(int httpStatus, String errorCode, String errorMessage) { return new ApiError(httpStatus, errorCode, errorMessage); } public static ApiError fromErrorCode(BusinessErrorCode errorCode, Object... args) { return new ApiError( errorCode.getHttpStatus(), errorCode.getErrorCode(), errorCode.formatErrorMessage(args) ); } }
Adapter: реализация вызова. Адаптер связывает Port с HTTP-слоем. Он обрабатывает статус-коды, парсит ошибки через ApiError.fromResponse() и маппит успешные ответы в доменные модели. Так позитивные и негативные кейсы возвращают один тип Result.
@Slf4j @RequiredArgsConstructor public class RestCountryInfoServiceAdapter implements CountryInfoServicePort { private final CountryInfoRequest clientCountryInfoRequest; @Override public Result getCountryInfo(String clientId, Lang lang) { Response response = clientCountryInfoRequest.getCountryInfoResponse(clientId, lang); int statusCode = response.getStatusCode(); if (sresponse.getStatusCode() == 200) { CountryInfoResponseDTO dto = response.as(CountryInfoResponseDTO.class);return Result.success(CountryInfoMapper.toDomain(dto)); } // Негативный кейс: делегируем парсинг ошибки в ApiError ApiError apiError = ApiError.fromResponse(response); log.warn("API error: status={}, code={}, message={}", apiError.getHttpStatus(), apiError.getErrorCode(), apiError.getErrorMessage()); return Result.failure(apiError); } }
Domain Model и маппер. Классы моделируют бизнес-сущности. Мы постарались уйти от использования Map и сырого JSON. Маппер отвечает за преобразование вложенных DTO в плоские или агрегированные доменные модели.
@Value @Builder public class CountryInfo { String infoText; List countries; } @Value public class Country { String codeAlpha2; String codeAlpha3; String codeNumeric; String name; } public class CountryInfoMapper { public static CountryInfo toDomain(CountryInfoResponseDTO dto) { return CountryInfo.builder() .infoText(dto.getInfo().getText()) .countries(dto.getResultList().stream() .map(countryDTO -> new Country( countryDTO.getCountryCodeAlpha2(), countryDTO.getCountryCodeAlpha3(), countryDTO.getCountryCodeNumeric(), countryDTO.getCountryName() )) .collect(Collectors.toList())) .build(); } }
Request: HTTP-слой. Класс отвечает за формирование и отправку запроса через RestAssured. Пути и заголовки вынесены в конфигурацию. Путь эндпоинта и базовый URL хранятся в application-test.properties. Коды указаны явно для наглядности.
@RequiredArgsConstructor public class CountryInfoRequest { private final RequestSpecification requestSpecification; @Step("Выполнение запроса получения информации о стране для клиента {clientId}") public Response execute(String clientId, Language language) { return given() .spec(requestSpecification) .header("clientId", clientId) .header("x-lang", language.getCode()) .log().all() .when() .get("/api/v1/country-info") .then() .log().all() .extract() .response(); } }
Use Case: оркестратор бизнес-сценария. Use Case вызывает Port и возвращает результат.
@Slf4j @RequiredArgsConstructor public class GetCountryInfoUseCase { private final CountryInfoServicePort countryInfoService; public Result execute(String clientId, Language language) { log.info("🚀 Начало получения информации о стране для клиента: {}", clientId); // Прямой вызов порта без валидации входных данных Result result = countryInfoService.getCountryInfo(clientId, language); // Логирование результата для отладки в CI if (result.isSuccess()) { log.debug("✅ Успешный ответ для clientId: {}", clientId); } else { log.warn("⚠️ API error for clientId={}: status={}, code={}", clientId, result.getError().map(ApiError::getHttpStatus).orElse(0), result.getError().map(ApiError::getErrorCode).orElse("UNKNOWN")); } return result; } }
Примеры тестов. Задача фреймворка — отправить запрос и вернуть ответ. Решение о том, корректен ли ответ, принимает тест через ассерты.
// Позитивный кейс @Test void shouldReturnCountryInfoForValidClient() { String clientId = TestDataGenerator.generateClientId(); Result result = useCase.execute(clientId, Language.RU); assertThat(result.isSuccess()).isTrue(); CountryInfo info = result.getValue().orElseThrow(); assertThat(info.getCountries()).isNotEmpty(); } // Негативный кейс: невалидный формат clientId @Test void shouldReturnBadRequestForInvalidClientId() { Result result = useCase.execute("INVALID_FORMAT", Language.RU); assertThat(result.isError()).isTrue(); ApiError error = result.getError().orElseThrow(); assertThat(error.getHttpStatus()).isEqualTo(400); assertThat(error.getErrorCode()).isEqualTo("INVALID_CLIENT_ID_FORMAT"); }
В реальной реализации все ожидаемые коды и сообщения ошибок вынесены в отдельный enum BusinessErrorCode. В ассертах сравнение происходит через BusinessErrorCode.INVALID_CLIENT)ID_FORMAT.getCode(). В примерах строки указаны хардкодом для наглядности и упрощения чтения кода.
Сборка зависимостей. Для инициализации слоев мы используем SpringTest. Конфигурация вынесена в отдельный класс — это исключает дублирование new Adapter(new Request(…)) в каждом тесте. Spring здесь выступает как DI-контейнер и менеджер конфигурации.
@Configuration public class FrameworkConfig { @Bean public CountryInfoRequest countryInfoRequest(RequestSpecification spec) { return new CountryInfoRequest(spec); } @Bean public CountryInfoServicePort countryInfoPort(CountryInfoRequest request) { return new RestCountryInfoServiceAdapter(request); } @Bean public GetCountryInfoUseCase getCountryInfoUseCase(CountryInfoServicePort port) { return new GetCountryInfoUseCase(port); } }
Компромиссы и процесс разработки
Внедрение новой архитектуры меняет рабочий процесс. Издержки смещены на этап проектирования нового эндпоинта, но компенсируются скоростью последующей разработки и изоляцией изменений.
На какие компромиссы идем
Чем компенсируем
Создание первого эндпоинта требует описания полного набора слоев (Port, Adapter, Request, DTO, UseCase). На старте это требует больше времени, чем при добавлении одного метода в существующий монолитный класс (Steps).
Но после настройки структуры последующие эндпоинты добавляются по готовому шаблону: QA-инженер копирует пакет, заменяет контекст и адаптирует маппинг. Так время разработки сокращается.
Устранение зависимости от общего репозитория. Именно эта цель подтолкнула нас к поискам нового подхода для автоматизации регресса.
Копирование спецификации новой ручки из микросервиса в общий репозиторий со спецификациями → проверка конфликтов → коммит и ожидание аппрува → мерж в общий репозиторий → обновление версии зависимости в репозитории регресса → написание метода в Steps → сам тест.
Такая цепочка создавала риски и издержки. А еще способствовала накоплению технического долга.
рхитектура значительно увеличивает количество классов. Вместо одного Steps, содержащего все методы, появляется структурированный пакет слоев. Это требует от инженера понимания принципов контрактов и DI, но задает четкую границу ответственности. Изменения в одном слое не затрагивают остальные.
Изоляция в одном репозитории. Перенеся логику работы с API внутрь репозитория автотестов, мы больше не синхронизируем YAML между репозиториями и не обновляем внешние зависимости при изменении спецификации. Такой подход обеспечивает независимость от смежных команд и снижение рисков.
Мы сравнили подход прямой зависимости от спецификации с изолированными абстракциями по пяти критериям.
Точка отказа. В подходе с зависимостью от спецификации изменение спецификации в чужом коммите вело к падению регресса без нашего участия. С изолированными абстракциями спецификация инкапсулирована в Request и Adapter. Тесты не зависят от путей, заголовков и структуры ответа.
Скорость написания теста. Эта метрика отражает наш опыт. Цифры могут варьироваться в зависимости от зрелости инфраструктуры команды. Когда автоматизация регресса зависит от спецификации, алгоритм выглядит так:
-
Найти и обновить YAML в общем репозитории.
-
Создать MR, дождаться ревью и мержа.
-
Обновить версию зависимости в нашем проекте.
-
Перезапустить регресс.
Итого написание 5—7 тестов для нового эндпоинта на нашем проекте занимало от 4 до 8 часов, корректировка тестов для уже существующего — от 1 до 3. Большую часть времени занимали перенос и редактирование спецификации эндпоинта в общем репозитории, отладка и обновление зависимостей в репозитории регресса.
Когда мы перешли на изолированные абстракции, стали работать по такой схеме: готовый сценарий + генерация данных. В итоге правка уже существующего или написание набора новых тестов занимает ~10 минут или от 40 минут до ~1 часа соответственно.
Читаемость. В нашем контексте тесты стали восприниматься как документация, но эффект может варьироваться в зависимости от опыта команды и стандартов код-ревью. Раньше: YamlClient.execute(“api.endpoint.getCountryInfo”) — магия без контекста. Теперь: useCase.execute(clientId, Language.RU) — бизнес-язык без деталей реализации.
Онбординг QA. В нашей команде адаптация сократилась с 2—3 недель до 3—5 дней. Результаты зависят от начального уровня специалиста и наличия документации.
Мы ушли от истории, когда нужно разбираться в структуре общего репозитория и правилах работы с YAML. Сейчас тест понятен за 5 минут — спецификация скрыта за абстракциями.
Стоимость поддержки. Когда автоматизация регресса зависела от спецификации, каждое падение влекло за собой часы расследований и координацию с другими командами. Теперь в новой изолированной истории мы можем пофиксить и локализовать проблему в одном слое.
Результаты вместо заключения
После всех изменений у нас появилась стабильность без зависимости от других команд. Ни одного падения регресса из-за изменений в общем репозитории спецификаций не случилось.
Выросла скорость разработки. Время написания типового теста сократилось в ~5 раз. Не нужно ждать мержа в общем репозитории: готовый сценарий + генерация данных — и тест готов за минуты.
Мы разработали три фреймворка, основываясь на описанной архитектуре. А еще мигрировали один, реализованный согласно старому подходу, затратив на это примерно 8 рабочих дней.
Адаптация коллег к автоматизации сократилась с недель до дней. Инциденты, которые раньше требовали часов расследования и координации с другими командами, теперь решаются за минуты: проблема локализована в одном слое. Автоматизация регресса перестала быть головной болью всей команды и стала приносить удовольствие. Тесты пишутся легко, читаются как документация, падения больше не вызывают панику. Технический долг перестал расти, фичи все чаще покрываются регрессом прямо во время тестирования, автоматизация практически не откладывается в долгий ящик.
Отказ от хардкода в пользу генератора на базе Builder облегчил работу QA с тестовыми данными. Тест вызывает метод генератора, который автоматически подставляет валидные значения для всех обязательных полей. В самом тесте при автоматизации указываются только те параметры, которые влияют на логику сценария. Например, передается невалидное значение параметра для проверки негативных сценариев.
В итоге мы получили:
-
Соблюдение DRY. Логика подготовки тестовых данных вынесена в отдельный класс, исчезли десятки строк кода с подготовкой тестовых данных. Если меняется контракт, правка вносится только в одном месте.
-
Гарантированную уникальность. Для каждого вызова генерируется полностью новый набор данных — это устранило конфликты и flaky-тесты, которые были завязаны на одно и то же значение.
Мы начали внедрение нового подхода до критического инцидента с падением регресса. В результате получили стабильный регресс и контролируемый процесс разработки тестов. Не беремся утверждать, что наш подход — истина в последней инстанции. Мы придерживаемся мнения, что контекст решает: в небольших проектах такая структура может казаться избыточной. Мы продолжаем развивать наши фреймворки и искать способы их улучшения, не останавливаясь на достигнутом.
А как вы изолируете тесты от внешних зависимостей и сталкивались ли вы с такой проблемой на своем опыте? Делитесь подходами в комментариях — обсудим.
P. S. Все примеры кода в статье сгенерированы с помощью ИИ на основе реальных архитектурных решений нашей команды. Мы сознательно изменили имена классов, структуру пакетов и детали реализации, чтобы сохранить конфиденциальность внутренних систем и избежать раскрытия приватных данных. Суть архитектурных решений, принципы и результаты переданы точно.
Источник: habr.com