Контрактные тесты OpenAI-совместимого API перед обновлением клиента

Сначала опишите поддерживаемый сценарий

Начинайте не с «проверим chat completions», а с короткой карточки операции. Укажите: кто вызывает маршрут, какая версия SDK закреплена, какие поля вы отправляете, какие поля читаете и какое сообщение получает пользователь при ошибке. Например, вашему продукту может быть нужен только текстовый ответ с одним сообщением, а streaming, tools и JSON Schema остаются вне контракта до отдельной проверки.

Такой список защищает от ложной совместимости. Наличие похожего endpoint не означает, что каждый необязательный параметр, формат tool call или метод аутентификации доступен в каждом сценарии. Отдельно отметьте обязательные бизнес-правила: allowlist моделей, максимальный размер входа, owner операции и запрет на передачу ключа из браузера. За базовой проверкой модели следуйте руководству по /v1/models, но не используйте кеш как обещание доступа.

Сделайте тест маленьким и детерминированным

Хороший smoke test отправляет один нейтральный запрос с коротким ожидаемым ответом или проверяемой структурой. Не требуйте от модели точной художественной формулировки: для недетерминированного текста проверяйте тип полей, непустой результат, допустимый finish reason и отсутствие чувствительных данных. Если вам нужен строгий JSON, валидируйте его локальной схемой и фиксируйте, что возможность была подтверждена для выбранного сценария.

Разделите тесты на быстрые и редкие. Быстрый запуск в CI проверяет сериализацию, timeout, нормализацию ошибки и контракт вашего адаптера без реального вызова. Ограниченный интеграционный тест с реальным gateway запускайте с отдельным бюджетом и по явному расписанию или перед релизом. Это снижает расходы и не превращает CI в источник нагрузки. Принципы безопасной схемы описаны в материале о JSON Schema.

Проверяйте и ожидаемые отказы

Позитивный 200 — лишь один путь. Добавьте сценарий с неразрешённым model ID, пустым обязательным полем и намеренно коротким deadline. Тест должен убедиться, что адаптер не показывает пользователю сырой upstream-ответ, не делает неограниченный повтор и не заменяет модель без решения продукта. Для 429 полезно проверить локальную очередь или понятный ответ «повторите позже», а не считать этот статус аварией, которую можно скрыть.

Для асинхронных операций особенно важно различать «запрос не отправлен» и «состояние неизвестно после timeout». Контрактный тест не должен создавать реальную дорогую задачу ради проверки. Вместо этого подставьте transport stub или используйте явно безопасный тестовый путь, если он документирован. Повторы без дублей требуют внутреннего operation ID; практический подход есть в руководстве по идемпотентности.

Серверный пример адаптера

Ниже Node.js 18+ пример проверяет собственные входные данные до сети, берёт ключ только из окружения и возвращает нейтральный результат. Он иллюстрирует контракт вашего приложения, а не заявляет существование специальной функции у производителя модели. В production добавьте долговременное хранилище request ID, аутентификацию вызывающего пользователя и тестовые фикстуры без персональных данных.

export async function contractSmoke({ prompt, model }) {
  if (!process.env.RUSSIAAPI_API_KEY || model !== process.env.RUSSIAAPI_TEXT_MODEL) {
    return { ok: false, reason: 'configuration' };
  }
  if (typeof prompt !== 'string' || prompt.length === 0 || prompt.length > 600) {
    return { ok: false, reason: 'invalid_input' };
  }
  const response = await fetch('https://russiaapi.com/v1/chat/completions', {
    method: 'POST',
    headers: { authorization: `Bearer ${process.env.RUSSIAAPI_API_KEY}`, 'content-type': 'application/json' },
    body: JSON.stringify({ model, messages: [{ role: 'user', content: prompt }] }),
    signal: AbortSignal.timeout(12_000)
  });
  if (!response.ok) return { ok: false, reason: `http_${response.status}` };
  const data = await response.json();
  return { ok: typeof data.choices?.[0]?.message?.content === 'string', requestId: response.headers.get('x-request-id') ?? null };
}

Синтаксис можно проверить командой node --check, а интеграционный запуск — только с существующим значением RUSSIAAPI_TEXT_MODEL из вашего текущего каталога. Никогда не коммитьте локальный .env, не вставляйте ключ в URL и не выводите заголовки запроса в отчёт CI.

Выпускайте изменения по наблюдаемому сигналу

После обновления SDK сначала направьте небольшой контролируемый поток или включите маршрут для внутреннего проекта. Сравнивайте долю успешных операций, категорию ошибок, длительность и локальные отказы с предыдущей версией. Не делайте вывод о качестве модели по нескольким тестам и не рекламируйте проверку как гарантию производительности или доступности.

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

Чек-лист ревизии

Документированный контракт важнее удачного единичного запроса. Перед изменением зафиксируйте версию клиента, базовый URL, выбранный model ID, ожидаемый код ответа, обязательные поля и то, что приложение считает безопасной ошибкой. Не подменяйте проверку предположениями по чужому примеру: каталог, права, параметры и поведение конкретной модели могут измениться.

Тестовый контур должен использовать обезличенный вход, отдельный собственный ключ и ограниченный бюджет. Он не должен записывать Authorization, полный prompt, ответ с персональными данными или временную ссылку на результат. Это делает проверку воспроизводимой и одновременно уменьшает риск утечки в CI, журнале или тикете.

Наблюдаемость полезна, когда по ней можно принять решение. Храните внутренний request ID, статус, длительность, тип операции, версию маршрута и безопасный итог проверки. Связывайте их с проектом только после серверной авторизации. Не делайте метрику или очередь общим каналом для данных разных tenant.

Ошибки 400, 401, 403, 429 и 5xx имеют разные действия. Не запускайте бесконечный retry и не меняйте модель молча: timeout может означать неопределённость, а повторная асинхронная задача способна создать дубль. Для проверки сначала прочитайте своё внутреннее состояние и текущую документацию, затем выполните ограниченный шаг, разрешённый вашей политикой.

До релиза выполните короткий негативный набор: отсутствующая переменная окружения, неподходящий model ID, лишнее поле, недоступный маршрут, timeout и повтор одного запроса. Проверяйте не только HTTP-статус, но и то, что клиент не вывел секрет, не смешал владельцев и не сообщил пользователю неподтверждённую готовность результата.

Эта инженерная практика не обходит лимиты, правила поставщика, применимое право или ограничения платформ. Если контракт, цена, доступность или политика обработки данных изменились, остановите рискованный rollout, обновите тест и подтвердите сценарий в актуальном каталоге RussiaAPI и своих договорных материалах.