Автотесты как документация: «чистый» код и генератор на Regex

Привет, Хабр! Проблема рассинхронизации автотестов и тестовой документации знакома многим. Код постоянно меняется, а кейсы в Confluence — нет. В итоге документация становится бесполезной, а время команды тратится на выяснение того, что же на самом деле проверяет тот или иной тест.

Есть занятия, которые наполняют жизнь QA-инженера особым, экзистенциальным смыслом, и ручное ведение тест-кейсов, бесспорно, одно из них. Этот медитативный ритуал — найти нужную страницу в Confluence, сверить её с кодом, осознать их полную асинхронность, глубоко вздохнуть и начать творить — несравненно закаляет дух. Но, увы, в какой-то момент безжалостные требования бизнеса к скорости заставили меня пожертвовать этим священным процессом и, скрепя сердце, написать скрипт, который делает всю эту замечательную работу за меня.

Идея генерировать документацию из кода тестов не нова, и на Хабре можно найти немало успешных примеров ее реализации. Проанализировав существующие подходы, я поставил себе цель — добиться того же результата, но с минимальным вмешательством в код самих тестов. Моё решение — это комбинация чистого бизнес-ориентированного синтаксиса в тестах и простого, но мощного генератора, который парсит шаги Allure. Вот как это работает.

Основная цель

Я хочу, чтобы такой лаконичный тест, лишенный деталей реализации Allure:

# tests/test_users.py   import allure from schemas.user import UserSchema   @allure.title("Успешное получение данных пользователя") class TestGetUser:     def test_get_user_by_id(self, api_client, Assertions):         # Код теста — это чистый бизнес-сценарий         response = api_client.get_user(user_id=2)          Assertions.assert_status_code(response, 200)         Assertions.assert_pydantic_schema(response, UserSchema)         Assertions.assert_json_value_by_name(response, "first_name", "Janet") 

…автоматически, после каждого запуска, превращался вот в такую понятную документацию.

Что получается на выходе: Примеры тест-кейсов

Вот как выглядят .md файлы, которые генерирует наша система.

Пример 1: GET-запрос

### Успешное получение данных пользователя  **1. Отправить GET запрос на https://reqres.in/api/users/2** **2. Проверка статус-кода. ОР: 200** **3. Проверка соответствия ответа схеме Pydantic 'UserSchema'. ОР: Успешная валидация** **4. Проверка значения ключа 'first_name'. ОР: 'Janet'**  ---

Пример 2: POST-запрос с телом

### Успешное создание пользователя  **1. Отправить POST запрос на https://reqres.in/api/users с телом: {'name': 'morpheus', 'job': 'leader'}** **2. Проверка статус-кода. ОР: 201** **3. Проверка значения ключа 'name'. ОР: 'morpheus'**  ---

Документация получается подробной и всегда на 100% соответствующей коду. Теперь давайте разберем, как это устроено под капотом.

Шаг 1: «Умный» API-клиент — сердце системы

Главная магия происходит в кастомном классе для отправки запросов. Вместо того чтобы прятать данные в скрытые аттачменты, делаем их проще и надежнее: вся необходимая для генератора информация встраивается прямо в название шага Allure.

# helpers/api_requests.py   import allure import requests import json  class ApiRequests:     @staticmethod     def post(url: str, data: dict = None, headers: dict = None, cookies: dict = None):         return ApiRequests._send(url, data, headers, cookies, "POST")      @staticmethod     def get(url: str, data: dict = None, headers: dict = None, cookies: dict = None):         return ApiRequests._send(url, data, headers, cookies, "GET")      @staticmethod     def _send(url: str, data: dict, headers: dict, cookies: dict, method: str):         # ФОРМИРУЕМ НАШУ СПЕЦИАЛЬНУЮ СТРОКУ ДЛЯ ALLURE         # Она содержит все, что нужно знать генератору: метод, URL и тело.         with allure.step(f"{method} {url}, Request Body: {data}"):             if headers is None: headers = {}             if cookies is None: cookies = {}              # Для POST/PUT/PATCH запросов используем `json=data`,             # чтобы автоматически устанавливать правильный Content-Type.             if method in ['POST', 'PUT', 'PATCH']:                 r = requests.request(method, url, json=data, headers=headers, cookies=cookies)             else: # Для GET, DELETE и других передаем данные как параметры URL                 r = requests.request(method, url, params=data, headers=headers, cookies=cookies)                          return r 

Эта простая строка f"{method} {url}, Request Body: {data}" — это контракт. Генератор будет знать, как её разобрать.

Шаг 2: «Умные» ассерты — строительные блоки

Вторая важная часть — это хелпер для проверок. Здесь также прячем логику allure.step внутрь, используя формат «Проверка X. ОР: Y».

# helpers/assertions.py   import allure from requests import Response  class Assertions:     @staticmethod     def assert_status_code(response: Response, code: int):         """Проверяет, что статус-код ответа равен ожидаемому."""         with allure.step(f"Проверка статус-кода. ОР: {code}"):             assert response.status_code == code, \                 f"Неверный статус-код. Ожидался: {code}, фактический: {response.status_code}"      @staticmethod     def assert_json_value_by_name(response_or_dict, name: str, expected_value: any, step_name: str = None):         """Проверяет значение в JSON по ключу."""         description = step_name or f"Проверка значения ключа '{name}'"         with allure.step(f"{description}. ОР: '{expected_value}'"):             response_as_dict = Assertions._get_json(response_or_dict)             assert name in response_as_dict, f"Ключ '{name}' отсутствует в JSON ответе."             actual_value = response_as_dict.get(name)             assert actual_value == expected_value, \                 f"Неверное значение для ключа '{name}'. Ожидалось: '{expected_value}', фактическое: '{actual_value}'"      @staticmethod     def assert_pydantic_schema(response_or_dict, schema: BaseModel):         """Проверяет соответствие JSON ответа Pydantic-схеме."""         with allure.step(f"Проверка соответствия ответа схеме Pydantic '{schema.__name__}'. ОР: Успешная валидация"):             json_to_validate = Assertions._get_json(response_or_dict)             try:                 schema.model_validate(json_to_validate)             except ValidationError as e:                 allure.attach(body=e.json(), name="Pydantic validation error", attachment_type=allure.attachment_type.JSON)                 raise AssertionError(f"JSON не соответствует схеме '{schema.__name__}':\n{e}") 

Шаг 3: Генератор на Regex — двигатель системы

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

# generate_test_cases.py   import os import json import pathlib import re  ALLURE_RESULTS_DIR = 'allure_results' TEST_CASES_OUTPUT_DIR = 'test_cases'  def generate_test_cases():     results_path = pathlib.Path(ALLURE_RESULTS_DIR)     output_path = pathlib.Path(TEST_CASES_OUTPUT_DIR)      if not results_path.is_dir():         print(f"Директория '{ALLURE_RESULTS_DIR}' не найдена.")         return     output_path.mkdir(exist_ok=True)      # Регулярное выражение для парсинга шага с запросом     request_pattern = re.compile(         r"^(GET|POST|PUT|DELETE|PATCH|HEAD|OPTIONS)\s+(.*?),\s+Request Body:\s+(.*)$"     )      for result_file in results_path.glob('*-result.json'):         with open(result_file, 'r', encoding='utf-8') as f:             data = json.load(f)          if 'name' not in data or 'steps' not in data:             continue                  test_case_title = next((label['value'] for label in data.get('labels', []) if label['name'] == 'title'), data['name'])         md_content = f"### {test_case_title}\n\n"                  for i, step in enumerate(data['steps'], 1):             step_name = step.get('name', 'Шаг без названия')             match = request_pattern.match(step_name)                          if match:                 method, url, body_str = match.groups()                 step_text = f"Отправить {method} запрос на {url}"                 if body_str != 'None':                     step_text += f" с телом: {body_str}"                 md_content += f"**{i}. {step_text}**\n"             else:                 md_content += f"**{i}. {step_name}**\n"                      test_file_name = data.get('fullName', data['name']).split('.')[-2].replace("test_", "")         output_file = output_path / f"{test_file_name}.md"         with open(output_file, 'a', encoding='utf-8') as f:             f.write(md_content + "\n---\n")  if __name__ == "__main__":     generate_test_cases() 

Заключение

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

Ключевые преимущества этого решения:

• Чистый код тестов: Тесты описывают бизнес-логику, а не детали отчетности.

• Надежность: Парсинг строки с помощью Regex прост и устойчив.

• Актуальность: Документация генерируется после каждого запуска и никогда не устаревает.

• Прозрачность: Любой член команды может понять, что делает тест, просто прочитав .md файл.

При желании, можно пойти дальше — добавить интеграцию с Jira, что бы кейсы обновлялись автоматически, после каждого запуска. Немного изменить генератор тестов, что бы он подготавливал данные, подходящие для взаимодействия с API Jira. Для меня это пока что далекий беклог, и возможно когда-то я это реализую, но сейчас мне лень 🙂

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

Делитесь мнением об этой реализации в комментариях 🙂