Приветствую, Хабр!

Меня зовут Владислав Тимашенков, я занимаюсь автоматизацией тестирования в ГК Infowatch.

Наша команда столкнулась с популярными болями автотестов для API:

• одно изменение в API требует обновления нескольких тестов;

• проверка структуры ответа распределена по тестам и не централизована;

• валидация вложенных структур и генерируемых полей требует дополнительного кода.

И мы задались вопросом: какой инструмент для валидации контракта нам подойдёт?

В этой статье расскажем о нашем переосмыслении подхода к тестированию API с помощью внедрения Pydantic.

Рассмотрим простой пример теста на создание пользователя:

# ../your_project/tests/user/test_crud_user.py

 

def test_create_user():

    user_creation_body = {

        "USERNAME": "John_Smith",

        "EMAIL": "john@example.com",

        "DISPLAY_NAME": "John Smith",

    }

    response = requests.post(f"{SOME_URL}/user", json=user_creation_body)

    response.raise_for_status()

    data = response.json()

    assert data["USERNAME"] == user_creation_body["USERNAME"]

    assert data["EMAIL"] == user_creation_body["EMAIL"]

    assert data["DISPLAY_NAME"] == user_creation_body["DISPLAY_NAME"]

    assert isinstance(data["USER_ID"], int)

Тест проверяет успешность выполнения запроса и соответствие данных в конкретных полях. Но такой подход имеет ряд недостатков:

• Нет проверки всей структуры данных ответа

• Нет единого описания контракта

• Дублирование assert (валидация типа для data["USER_ID"] нужна во всех тестах с участием сущности USER)

• Изменения API могут пройти незаметно в непроверяемых полях

Поэтому мы решили выделить контракт API в отдельный слой валидации. Для этого нужен инструмент, который:

• Валидирует структуру на основе единого контракта

• Реализован независимо

• Падает при расхождении с API

• Внедряется и масштабируется поэтапно

Сначала мы попробовали Template и описывали ответы в виде эталонных json для сравнения структуры и значения ответа с заранее заданным шаблоном. Это частично закрывало потребности по структуре данных, но давало минимальные возможности по валидации полей и масштабированию.

Pydantic v2 решает эти задачи за счет строгой типизации, встроенной валидации и предсказуемого поведения, поэтому он лучше всего соответствовал нашим требованиям.

Запрос из теста в предыдущем примере

requests.post(f"{SOME_URL}/user", json=user_creation_body).json()

Вернет нам следующий json:

{

 "USER_ID": 69,

 "USERNAME": "John_Smith",

 "DISPLAY_NAME": "John Smith",

 "EMAIL": "john@example.com",

 "NOTE": null,

 "CREATE_DATE": "2026-01-01T00:01:30.897869",

 "STATUS": 1

}

Из документации к API проекта мы можем узнать требования к значениям полей. Создадим по ней Pydantic-модель для тела ответа. Модель описывает структуры данных с помощью аннотаций типов Python. Она определяет, какие поля ожидаются в ответе, их типы и ограничения, а также автоматически валидирует данные при создании объекта. Каждое поле является атрибутом модели с удобным вызовом.

# ../your_project/models/user/response.py

 

 

from datetime import datetime

from enum import IntEnum

from pydantic import BaseModel, ConfigDict, EmailStr, Field, PositiveInt

 

 

class UserStatuses(IntEnum):

   active = 1

   inactive = 0

 

 

class UserResponseModel(BaseModel):

  # Конфигурируем модель: задаем правила валидации и обработки полей.

  model_config = ConfigDict(

    extra="forbid",  # Запрет новых полей в ответе API.

    populate_by_name=True,  # Возможность использовать как alias полей, так и их имена.

    alias_generator=lambda field_name: field_name.upper() # Генерируем alias (UPPER_CASE) для сопоставления формата полей в модели и в API.

  )

 

  # Допускается только позитивное число

  user_id: PositiveInt

 

  # Строка длиной от 8 до 32 символов

  username: str = Field(min_length=8, max_length=32)

  display_name: str = Field(min_length=8, max_length=32)

 

  # Валидный формат email. Под капотом EmailStr либо email-validator.

  email: EmailStr

 

  # Необязательное поле.

  note: str | None = None

 

  # Дата и время в формате datetime.

  create_date: datetime

 

  # Значение из enum UserStatuses

  status: UserStatuses

Теперь в проекте есть модуль с описанием контракта для создания юзера. Он отвечает на вопрос: «Каким должен быть ответ?». По сути это исполняемая документация для API, клиентское описание контракта.

Обновленный тест проверяет структуру через pydantic-модель, а assert’ы отвечают только за бизнес-логику.

# ../your_project/tests/user/test_crud_user.py

 

from ..models.user.response import UserResponseModel

 

def test_create_user():

    user_creation_body = {

        "USERNAME": "John_Smith",

        "EMAIL": "john@example.com",

        "DISPLAY_NAME": "John Smith",

    }

    response = requests.post(f"{SOME_URL}/user", json=user_creation_body)

    response.raise_for_status()

    data = response.json()

 

    user_model = UserResponseModel.model_validate(data)

    

    # Поля из тела ответа - атрибуты Pydantic-модели

    assert user_model.USERNAME == user_creation_body["USERNAME"]

    assert user_model.EMAIL == user_creation_body["EMAIL"]

    assert user_model.DISPLAY_NAME == user_creation_body["DISPLAY_NAME"]

Теперь, если в поле “CREATE_DATE” вернется значение “31-03-2026” и добавится новое поле "IS_BLOCKED": false, то тест упадёт, даже если на эти поля нет assert. 

Для примера посмотрим сырое исключение ValidationError:

pydantic_core._pydantic_core.ValidationError: 2 validation errors for UserResponseModel

 

CREATE_DATE

  Input should be a valid datetime or date, invalid character in year [type=datetime_from_date_parsing, input_value='31-03-2026', input_type=str]

    For further information visit https://errors.pydantic.dev/2.11/v/datetime_from_date_parsing

 

IS_BLOCKED

  Extra inputs are not permitted [type=extra_forbidden, input_value=False, input_type=bool]

    For further information visit https://errors.pydantic.dev/2.11/v/extra_forbidden

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

Например, NotificationModel использует уже готовые модели UserResponseModel и TemplateModel:

# ../your_project/models/notifications/response.py

from datetime import datetime

from ..models.user.response import UserResponseModel

from ..models.templates.response import TemplateResponseModel

from pydantic import BaseModel

 

class NotificationResponseModel(BaseModel):

    model_config = ConfigDict(

      extra="forbid",

      populate_by_name=True,

      alias_generator=lambda field_name: field_name.upper()

   )   

   notification_id: str

   display_name: str

   create_date: datetime

   # Автоматические рекурсивные валидации по каждому элементу списка

   recipients: list[UserResponseModel]

   templates: list[TemplateResponseModel]

А UserResponseModel участвует и в создании NotificationResponseModel, и в тесте test_add_notification без дублирования кода. Любое изменение в Pydantic-модели автоматически задействовано во всех тестах и моделях, которые её используют.

# ../your_project/tests/notification/test_add_notification.py

 

from ..models.notifications.response import NotificationResponseModel

 

 

def test_add_notification():

    notification_add_body = {

        "DISPLAY_NAME": "John Smith",

        "RECIPIENTS": [..],

        "TEMPLATES": [..],

    }

    response = requests.post(f"{SOME_URL}/notification", json=notification_add_body)

    data = response.json()

    notification_model = NotificationResponseModel.model_validate(data)

    assert notification_model.DISPLAY_NAME == notification_add_body["DISPLAY_NAME"]

Наш опыт внедрения подхода с Pydantic

Мы декомпозировали эпик на задачи и поэтапно реализовали поддержку Pydantic во фреймворке проекта, описали наиболее важные «ручки» для сложных сущностей, добавляли модели при изменениях существующих тестов и выносили повторяющиеся структуры в общие модели.

Не пришлось переписывать все и сразу, на одну «ручку» приходится примерно 1-3 модели в зависимости от структуры. Отличным инструментом для ускорения генерации моделей стал datamodel-code-generator. По OpenAPI-спецификации он в один вызов генерирует модели, которые затем можно привести к стилю проекта и дополнить валидацией. Пример:

datamodel-codegen \

  --input your_openapi_spec.yaml \             # путь к исходной OpenAPI-спецификации

  --input-file-type openapi \                  # указываем тип спецификации

  --output your_path/ \                        # путь для генерации моделей

  --target-python-version 3.13 \               # версия Python для использования актуального синтаксиса

  --output-model-type pydantic_v2.BaseModel \  # использовать Pydantic v2 BaseModel как базовый класс моделей

  --snake-case-field \                         # конвертировать имена полей в snake_case

  --use-double-quotes \                        # использовать двойные кавычки в сгенерированном коде

  --use-schema-description \                   # переносить описание из схемы в docstring или Field(description=...)

  --formatters ruff-check ruff-format          # проверять код через Ruff (линтеры + автоформатирование)

Примерно за полгода удалось написать 280+ моделей, которые закрыли 1740+ полей и покрыли большую часть контракта. Очень ценным побочным эффектом стало то, что мы перетрясли API продукта и обнаружили ряд неочевидных и ранее незамеченных проблем: несовпадение типов, неожиданные значения, поля и логики, отсутствующие в документации.

Как итог, мы изменили сам подход к тестированию API ключевого продукта InfoWatch:

• Проверки разделены на два независимых слоя: валидации структуры ответа и валидацию бизнес-логики.

• Автоматически и централизованно отслеживаем изменения в API

• Сократили количество assert в тестах за счёт переноса проверок структуры в модели

• Увеличили покрытие за счет переиспользования моделей

Этот подход особенно хорошо масштабируется в больших проектах, где API активно развивается.