Команда запускает ревью API-контракта перед релизом. Архитектор смотрит на спецификацию OpenAPI и видит корректную структуру, но QA-инженер спрашивает: «А что будет, если клиент пришлёт поле email длиной 256 символов? А если статус будет строкой, а не enum?». Ответов в документе нет. Контракт описывает, как должно работать всё правильно, но молчит о том, что сломается при нарушении ожиданий. Тест-кейсы, выведенные непосредственно из контрактных ограничений, закрывают этот пробел: они превращают декларативные правила в исполняемые проверки.
Источник правды: спецификация OpenAPI 3.0
В учебном примере используем OpenAPI 3.0. Указание nullable: true вместе с type допускает null; наличие свойства регулируется отдельно через required. Это относится и к строкам, и к другим применимым типам. В 3.1 схема использует соответствующий диалект JSON Schema. Проверяют поддержку форматов и настройки выбранного валидатора, поскольку описание format не гарантирует одинаковую проверку всеми инструментами.
Мы фокусируемся на одной операции: POST /orders. Выбор этой операции обусловлен её сложностью: она содержит тело запроса с вложенными объектами, ограничениями длины строк, перечислениями и условными требованиями. Другие методы (GET, DELETE) имеют меньшую поверхность для ошибок валидации тела, поэтому их тестирование сводится преимущественно к проверке параметров пути и заголовков.
Экстракция ограничений из схемы
Процесс начинается с анализа блока requestBody и связанной схемы OrderRequest. Мы извлекаем четыре категории ограничений:
- Типы данных: каждый путь в схеме имеет объявленный тип (
string,integer,boolean). Несоответствие типа — базовый негативный кейс. - Обязательность: массив
requiredв схеме определяет, какие поля должны присутствовать. Отсутствие обязательного поля приводит к ошибке 400 Bad Request. - Валидаторы:
minLength,maxLength,minimum,maximum,pattern,enum. Каждое ограничение порождает три теста: значение ровно на границе, значение за границей, значение внутри диапазона. - Условная логика: хотя OpenAPI 3.0 не поддерживает полноценный
if/then/else(это функция 3.1), мы можем смоделировать условность через описание вdescriptionили через использованиеoneOf/anyOf. Для простоты в этом примере мы считаем, что полеdiscountобязательно, только еслиstatusравно'confirmed'. Это требование зафиксировано в документации, но не выражено формально в схеме, поэтому тест должен проверять эту бизнес-логику отдельно.
Построение позитивных тестов
Позитивные тесты подтверждают, что система работает штатно при соблюдении всех контрактных условий. Мы строим их методом «минимально валидного объекта» и «максимально насыщенного объекта».
Минимально валидный объект содержит только поля из списка required с наименьшими допустимыми значениями. Например, для email — строка длиной 3 символа (если minLength: 3), для количества товара — 1. Такой тест проверяет, что сервер не требует лишних необязательных полей.
Максимально насыщенный объект включает все возможные поля, включая необязательные, с предельно большими значениями (максимальная длина строк, максимальные числа). Этот тест выявляет проблемы с переполнением буферов или неожиданные зависимости между полями.
Для обоих случаев ожидаемый ответ — 201 Created с телом созданного заказа. Если сервер возвращает 200 OK, это нарушение контракта (метод POST для создания ресурса должен возвращать 201 или 202). Если возвращается 204 No Content, также ошибка, так как контракт ожидает тело ответа.
Построение негативных тестов
Негативные тесты проверяют устойчивость системы к невалидным данным. Каждый валидатор порождает пару тестов: «ровно на границе» (должно пройти) и «чуть за границей» (должно упасть с 400). Важно разделять ошибки валидации схемы и ошибки бизнес-логики. Ошибка схемы (например, quantity: -1 при minimum: 1) должна возвращать 400 с понятным сообщением. Ошибка бизнес-логики (например, попытка создать заказ для несуществующего клиента) возвращает 404 или 422, в зависимости от дизайна API.
Для email различают формат строки, разрешённую предметную область и доступность адреса. Формат не доказывает существование ящика. Адрес test@localhost может проверять отдельное правило запрета локальных доменов, но не соответствует показанному шаблону, который требует точку и суффикс. Набор должен отделять ошибку синтаксиса от ограничения продукта, а ожидание связывается с фактически выбранным валидатором.
Учебный пример: операция POST /orders
Рассмотрим фрагмент спецификации OpenAPI 3.0 для учебного сервиса управления заказами:
/components:
schemas:
OrderRequest:
type: object
required:
- customer_id
- items
properties:
customer_id:
type: integer
minimum: 1
items:
type: array
minItems: 1
items:
$ref: '#/components/schemas/OrderItem'
status:
type: string
enum: ['pending', 'confirmed', 'shipped']
default: 'pending'
discount:
type: number
minimum: 0
maximum: 100
nullable: true
OrderItem:
type: object
required:
- product_id
- quantity
properties:
product_id:
type: integer
minimum: 1
quantity:
type: integer
minimum: 1
maximum: 100
note:
type: string
maxLength: 200
/paths:
/orders:
post:
operationId: createOrder
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/OrderRequest'
responses:
'201':
description: Заказ создан
content:
application/json:
schema:
$ref: '#/components/schemas/OrderResponse'
'400':
description: Некорректные данные
'401':
description: Требуется аутентификация
'409':
description: Дубликат заказа (идемпотентность)
Из этого фрагмента мы извлекаем следующие проверки. Обратите внимание: поле discount имеет nullable: true, значит, значение null допустимо. Однако, согласно бизнес-правилам (описанным в разделе «Условная логика»), если status = 'confirmed', discount не может быть null. Это правило не выражено в схеме, поэтому его проверка — часть негативных тестов бизнес-логики.
Таблица тест-кейсов
Ниже представлена таблица, объединяющая позитивные и негативные сценарии. Столбец «Ожидаемый статус» указывает HTTP-код, который сервер должен вернуть. Сообщения об ошибках приведены как примеры того, что должно содержаться в теле ответа 400, чтобы помочь клиенту исправить ошибку.
| ID | Тип | Описание сценария | Тело запроса (фрагмент) | Ожидаемый статус | Ожидаемое сообщение об ошибке |
|---|---|---|---|---|---|
| T01 | Позитивный | Минимально валидный заказ: только обязательные поля, статус по умолчанию | {"customer_id": 1, "items": [{"product_id": 101, "quantity": 1}]} | 201 | - |
| T02 | Позитивный | Максимально насыщенный заказ: все поля, предельные значения | {"customer_id": 999999, "items": [{"product_id": 999999, "quantity": 100, "note": "...200 chars..."]}, {"product_id": 1, "quantity": 1}], "status": "shipped", "discount": 100} | 201 | - |
| T03 | Негативный | Отсутствует обязательное поле customer_id | {"items": [...]} | 400 | Field 'customer_id' is required |
| T04 | Негативный | customer_id меньше минимального (0) | {"customer_id": 0, ...} | 400 | Value must be greater than or equal to 1 |
| T05 | Негативный | Пустой массив items (нарушение minItems: 1) | {"customer_id": 1, "items": []} | 400 | Array must have at least 1 item(s) |
| T06 | Негативный | quantity в элементе items превышает максимум (101) | {..., "items": [{"product_id": 1, "quantity": 101}]} | 400 | Quantity cannot exceed 100 |
| T07 | Негативный | Status вне списка enum ('cancelled') | {..., "status": "cancelled"} | 400 | Invalid status value. Allowed: pending, confirmed, shipped |
| T08 | Негативный | Discount > 100 (нарушение maximum) | {..., "discount": 101} | 400 | Discount cannot exceed 100% |
| T09 | Негативный | Business logic: status='confirmed', discount=null (нарушение условного правила) | {..., "status": "confirmed", "discount": null} | 422 | Discount is required when order is confirmed |
| T10 | Негативный | Note длиннее 200 символов (201 char) | {..., "items": [{..., "note": "a" * 201}]} | 400 | Note length exceeds maximum of 200 characters |
Обратите внимание на T09: здесь мы используем статус 422 Unprocessable Entity, а не 400, потому что данные соответствуют схеме (null допустим для nullable поля), но нарушают бизнес-правило. Это важное различие: 400 означает «ваш запрос синтаксически некорректен по схеме», 422 означает «ваш запрос синтаксически корректен, но мы не можем обработать его из-за бизнес-ограничений». Смешение этих кодов затрудняет отладку на стороне клиента.
Ограничения метода и риски
Генерация тестов исключительно из OpenAPI имеет пределы. Во-первых, спецификация не описывает поведение при сетевых сбоях, таймаутах или параллельных запросах. Эти сценарии требуют отдельных нагрузочных и отказоустойчивых тестов. Во-вторых, OpenAPI 3.0 не поддерживает сложные взаимные зависимости между полями (кроме allOf/oneOf, которые трудно читать). Если бизнес-логика включает правила вроде «если A, то B», они должны быть явно задокументированы в description или в отдельном гайде, иначе тесты будут неполными.
Также важно помнить: наличие nullable: true не делает поле опциональным. Поле может быть обязательным (required), но принимать значение null. Тест должен проверять оба случая: отсутствие поля (ошибка) и присутствие поля со значением null (может быть валидно или невалидно, в зависимости от контекста). В нашем примере discount не входит в required, но если он присутствует, он может быть null. Однако, как показано в T09, в определённом контексте null становится невалидным.
Инструментальная поддержка
Для автоматизации части процесса можно использовать инструменты генерации тестов, такие как Schemathesis или Dredd. Они читают OpenAPI-спецификацию и автоматически создают негативные тесты на основе валидаторов. Однако эти инструменты не понимают бизнес-логики. Поэтому рекомендуемый подход — гибрид: автоматическая генерация базовых негативных тестов (T03–T08) и ручное добавление бизнес-тестов (T09). Автоматические тесты легко поддерживать: при изменении схемы они обновляются сами. Ручные тесты требуют внимания аналитика при каждом изменении бизнес-правил.
При работе с инструментом редактором OpenAPI рекомендуется сначала верифицировать синтаксис файла, затем экспортировать схему в JSON для использования в тестовом фреймворке. Это обеспечивает соответствие между тем, что описано в интерфейсе, и тем, что проверяется в тестах.
Частые ошибки при создании тестов из контракта
- Игнорирование
defaultзначений: Тест не учитывает, что если поле не передано, сервер использует значение по умолчанию. Нужно явно передавать значение, отличное от дефолтного, чтобы проверить обработку явного ввода. - Смешение 400 и 422: Использование 400 для бизнес-ошибок усложняет диагностику. Клиент не понимает, нужно ли менять формат данных или выбрать другие значения.
- Непроверка
nullableв сочетании сrequired: Если поле обязательное и nullable, тест должен проверять, что передачаnullдопускается, а отсутствие поля — нет. - Зависимость от
format: Как упоминалось выше,format: emailне гарантирует валидацию. Тест должен содержать неформатную строку, чтобы убедиться, что сервер проверяет формат в коде. - Отсутствие тестов на идемпотентность: Хотя это не часть валидации схемы, для POST-операций важно проверить, что повторная отправка того же запроса (с Idempotency-Key) не создаёт дубликат. Это связано с темой идемпотентности и повторов.
Итог
Построение тест-кейсов из API-контракта — это систематический процесс перевода декларативных ограничений OpenAPI в исполняемые проверки. Начните с экстракции типов, обязательности и валидаторов из схемы. Постройте позитивные тесты для минимального и максимального валидных объектов. Затем сгенерируйте негативные тесты для каждого нарушения границы. Наконец, добавьте ручные тесты для бизнес-правил, которые не выражены формально в схеме. Результат — таблица, которая покрывает всю поверхность валидации операции и служит эталоном для разработки и поддержки. Такой подход снижает риск регрессий при изменениях API и ускоряет ревью контрактов, поскольку каждая проверка имеет прямое основание в спецификации.
