Pular para o conteúdo principal

Introdução

@powerduck/openapi-cli é uma ferramenta de linha de comando que testa em lote um documento OpenAPI 3.2 contra um servidor real. Informe um arquivo de especificação ou uma URL: a ferramenta executa as operações do documento, verifica cada resposta com asserções e gera três formatos de relatório.

Ela usa @powerduck/openapi-request para executar requisições e @powerduck/openapi-parser para resolver referências $ref.

Por que usar openapi-cli​

  • Pronto para CI — por padrão, um código de saída diferente de zero indica falha nos testes ou erro de execução. A ferramenta se integra diretamente ao GitHub Actions, GitLab CI ou qualquer outro pipeline.
  • Vários protocolos integrados — uma única especificação pode descrever operações HTTP, SSE, WebSocket, GraphQL, gRPC e MCP; o mesmo executor lida com todas.
  • Dois estilos de asserção — arrays declarativos x-tests para verificações simples e scripts no estilo Postman com pm.test() / pm.expect() para casos complexos.
  • Três formatos de relatório — JSON legível por máquinas, saída CLI colorida e fácil de ler e relatório HTML interativo independente.
  • Especificações locais ou remotas — carregamento por caminho de arquivo ou URL http(s)://, com redirecionamentos e limite de tempo.
  • Filtragem flexível — seleção de operações por método, caminho, tag ou operationId, com concorrência limitada.

Protocolos compatíveis​

O executor detecta o protocolo de cada operação pelas extensões do OpenAPI ou pelos tipos de conteúdo das respostas:

ProtocoloIdentificadorComo é selecionado
HTTPhttpPadrão para operações convencionais
Eventos enviados pelo servidorsseTipo de conteúdo da resposta text/event-stream ou x-response-stream: true
WebSocketwebsocketx-protocol: "websocket"
GraphQLgraphqlx-protocol: "graphql"
gRPCgrpcx-protocol: "grpc"
MCPmcpx-protocol: "mcp"

Também é possível definir explicitamente o protocolo com a extensão x-protocol na operação ou no item de caminho.

Relatórios​

Após a execução, a ferramenta gera as saídas abaixo; por padrão, os arquivos ficam em ./openapi-cli-report:

  • report.json — o objeto TestReport completo em JSON formatado.
  • report.html — relatório HTML independente e sem dependências, com resumo, barra de progresso, botões de filtro e linhas de teste expansíveis.
  • Saída padrão — resumo CLI colorido com barra de progresso e asserções de cada teste.

Uso no código​

O mesmo fluxo está disponível como biblioteca. Resolva a configuração, execute os testes e escolha os geradores de relatório desejados:

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");

Próximos passos​