Перейти к основному содержимому

Введение

@powerduck/openapi-cli — утилита командной строки для пакетного тестирования документа OpenAPI 3.2 на работающем сервере. Укажите файл спецификации или URL: утилита выполнит операции документа, проверит каждый ответ с помощью утверждений и создаст отчёты в трёх форматах.

Для выполнения запросов используется @powerduck/openapi-request, а для разрешения ссылок $ref — @powerduck/openapi-parser.

Зачем использовать openapi-cli​

  • Готовность к CI — по умолчанию ненулевой код завершения означает провал тестов или ошибку выполнения. Утилита напрямую интегрируется в GitHub Actions, GitLab CI и другие конвейеры.
  • Несколько протоколов из коробки — одна спецификация может описывать операции HTTP, SSE, WebSocket, GraphQL, gRPC и MCP; их обрабатывает один и тот же исполнитель.
  • Два вида проверок — декларативные массивы x-tests для простых случаев и скрипты в стиле Postman с pm.test() / pm.expect() для сложных.
  • Три формата отчётов — машиночитаемый JSON, удобный цветной вывод CLI и автономный интерактивный HTML-отчёт.
  • Локальные и удалённые спецификации — загрузка по пути к файлу или URL http(s):// с обработкой перенаправлений и ограничением времени ожидания.
  • Гибкая фильтрация — выбор операций по методу, пути, тегу или operationId с ограничением параллелизма.

Поддерживаемые протоколы​

Исполнитель определяет протокол каждой операции по расширениям OpenAPI или типам содержимого ответов:

ПротоколИдентификаторУсловие выбора
HTTPhttpПо умолчанию для стандартных операций
События, отправляемые серверомsseТип содержимого ответа text/event-stream или x-response-stream: true
WebSocketwebsocketx-protocol: "websocket"
GraphQLgraphqlx-protocol: "graphql"
gRPCgrpcx-protocol: "grpc"
MCPmcpx-protocol: "mcp"

Протокол также можно явно задать расширением x-protocol на уровне операции или элемента пути.

Отчёты​

После запуска утилита формирует следующие результаты; файлы по умолчанию сохраняются в ./openapi-cli-report:

  • report.json — полный объект TestReport в виде отформатированного JSON.
  • report.html — автономный HTML-отчёт без зависимостей с итоговой сводкой, индикатором выполнения, кнопками фильтрации и раскрывающимися строками тестов.
  • Стандартный вывод — цветная сводка CLI с индикатором выполнения и проверками каждого теста.

Использование из кода​

Тот же процесс доступен в виде библиотеки. Подготовьте конфигурацию, запустите тесты и выберите нужные генераторы отчётов:

import { resolveConfig, runTests, printCliReport, generateJsonReport } from "@powerduck/openapi-cli";

const config = resolveConfig({ spec: "./openapi.json" });
const report = await runTests(config);
printCliReport(report);
generateJsonReport(report, "./reports");

Следующие шаги​