Um teste que não imprime nada útil é um teste em que ninguém confia. Seu pipeline fica vermelho, alguém abre o log de build e tudo o que encontra é uma parede de timestamps e um código de saída diferente de zero. Qual asserção falhou? Contra qual ambiente? Em qual linha do arquivo de dados? A execução sabia. Apenas nunca registrou isso em um lugar onde você pudesse ler mais tarde.
Essa é a lacuna que um relatório preenche. Quando você executa testes de API pela linha de comando, o relatório é a parte com a qual você realmente convive: o artefato que você arquiva, o arquivo que seu painel de CI analisa, a coisa que você entrega a um colega de equipe às 9h que não estava monitorando o pipeline às 2h. O veredito do teste é apenas metade do trabalho. A outra metade é tornar esse veredito legível para um humano e para uma máquina ao mesmo tempo.
O executor de linha de comando do Apidog lida com ambos. O Apidog possui um CLI que executa os cenários de teste que você construiu visualmente no aplicativo, e uma flag controla cada relatório que ele produz: -r, --reporters. Você passa uma lista separada por vírgulas, o executor escreve cada formato no disco e você decide quem lê o quê. Este guia trata dessa flag e dos arquivos que ela produz: para que serve cada relatório, o que é gravado no disco, onde é gravado e como conectar cada um a um fluxo de trabalho real. Se você deseja uma visão mais ampla de todas as flags que o executor aceita, a referência de comando apidog run abrange a superfície completa; esta página se concentra nos relatórios.
Por que o relatório importa mais do que a execução
Execute um cenário localmente e você o vê acontecer. Você vê cada requisição ser disparada, cada asserção ficar verde, o resumo no final. O ciclo de feedback é o terminal à sua frente, ao vivo.
Na CI, esse ciclo desaparece. A execução acontece em uma máquina que você nunca vê, em um momento em que você não estava assistindo, e o único registro é o que foi gravado em disco antes que o executor fosse encerrado. Se a execução não produziu relatório, uma falha apenas informa que algo quebrou. Você fica tendo que refazer tudo localmente e torcer para que quebre da mesma forma.
Um bom relatório encurta essa distância. Ele captura qual cenário foi executado, contra qual ambiente, quantas iterações, quais asserções passaram, quais falharam, e os detalhes da requisição e resposta por trás de cada falha. Tenha isso em disco e uma falha às 2h da manhã se torna uma leitura de cinco minutos na manhã seguinte, em vez de uma caçada para reprodução. Essa é a razão pela qual a flag de relatório existe, e é por isso que escolher o formato certo para cada público vale alguns minutos de reflexão.
A única flag que controla todos os relatórios
O CLI do Apidog é um pacote npm chamado apidog-cli. Instale-o uma vez e você terá um único binário, apidog, cujo principal subcomando é run. Instale-o globalmente:
npm install -g apidog-cli
Todo relatório que o executor pode produzir vem de uma flag nesse comando: -r, --reporters. Ele aceita uma lista separada por vírgulas, e os quatro valores que aceita são cli, html, json e junit. O padrão, se você não passar nada, é cli.
Uma execução completa com dois relatórios se parece com isto:
apidog run --access-token $APIDOG_ACCESS_TOKEN -t 605067 -e 1629989 -n 1 -r html,cli
Isso autentica com um token, executa o cenário de teste 605067 contra o ambiente 1629989 uma vez, e emite tanto um arquivo HTML quanto uma saída de terminal legível. Os IDs são o ID do cenário e o ID do ambiente; você copia ambos, juntamente com o token de acesso, da aba CI/CD do cenário no Apidog, em vez de digitá-los manualmente. Se alguma dessas configurações não lhe for familiar, o guia completo do Apidog CLI aborda a instalação, tokens e sua primeira execução do início ao fim.
A ideia chave: uma execução pode produzir vários relatórios ao mesmo tempo. Você não está escolhendo um único formato. Você está escolhendo um público para cada saída e listando-os juntos. Uma linha de CI típica emite um arquivo HTML legível por humanos e um arquivo JUnit legível por máquinas da mesma execução, para que a mesma execução sirva tanto a uma pessoa quanto a um painel.
cli: o relatório que você lê no log de build
O relatório cli imprime um resumo legível diretamente no terminal. É o padrão e é o que um humano escaneia primeiro.
apidog run --access-token $APIDOG_ACCESS_TOKEN -t 605067 -e 1629989 -r cli
O que ele oferece é o veredito ao vivo: quantas requisições foram executadas, quantas asserções passaram e falharam, e quais asserções específicas falharam. Em um log de build de CI, este é o bloco que alguém lê quando clica em um job que falhou. Ele informa rapidamente se a falha é de uma asserção quebrada ou cinquenta, e qual endpoint está envolvido, antes de se preocupar em baixar qualquer coisa.
Mantenha cli ativado mesmo quando estiver escrevendo formatos de máquina. Não custa nada e mantém o log de build útil por si só. Um pipeline que emite apenas XML JUnit produz um painel perfeito e um log inútil; qualquer um que leia a saída bruta não vê nada além do executor iniciando e encerrando. Adicionar cli à lista corrige isso:
apidog run --access-token $APIDOG_ACCESS_TOKEN -t 605067 -e 1629989 -r cli,junit --out-dir ./apidog-reports
Mais duas flags moldam o que cli imprime. --verbose o expande para a requisição e resposta completas de cada etapa, o que é seu primeiro passo quando um cenário passa em seu laptop, mas falha no pipeline; o detalhe da comunicação mostra exatamente o que o executor enviou e recebeu. --silent faz o oposto e suprime totalmente a saída do console, o que é adequado para um job agendado barulhento onde você só se preocupa com o código de saída e o arquivo salvo.
html: o relatório que você entrega a um humano
O relatório html escreve um arquivo HTML autocontido. Abra-o em qualquer navegador e você terá a execução completa disposta visualmente: cada requisição, as asserções sobre ela, status de sucesso e falha, e os detalhes da requisição e resposta por trás de cada etapa. Nada para instalar, nenhum servidor para executar; é um arquivo que você clica duas vezes.
Este é o formato que você arquiva e compartilha. Salve-o como um artefato de build e o relatório sobreviverá à execução do pipeline, para que uma semana depois você ainda possa abrir o relatório exato da implantação que falhou. É também o que você envia para a pessoa que pergunta "o que falhou?" sem fazê-la instalar o CLI ou reexecutar nada. Ela abre o arquivo, vê a etapa vermelha, lê o corpo da resposta que disparou a asserção e pronto.
O HTML ganha mais destaque em uma execução orientada a dados. Quando um cenário percorre um CSV de cinquenta linhas, o relatório HTML mostra o resultado por iteração, para que você possa ver que as linhas 1 a 49 passaram e a linha 50 falhou porque uma conta tinha um token desatualizado. Uma contagem de sucesso ou falha por si só não pode lhe dizer isso. Se você executar cenários em arquivos de dados, o padrão é abordado em testes de API orientados a dados com CSV e JSON.
A desvantagem: HTML é para olhos, não para análise (parsing). Não tente extrair (scrape) o status de sucesso/falha dele em um script. Para isso servem JSON e JUnit.
junit: o relatório que seu painel de CI analisa
O relatório junit emite XML no formato padrão JUnit. Esse formato importa porque é a língua franca dos relatórios de teste de CI. Quase todo sistema de CI — GitHub Actions, GitLab CI, Jenkins, CircleCI, Azure Pipelines — sabe como ler XML JUnit e transformá-lo em uma árvore de sucesso/falha, exibir falhas em um widget de merge-request e tendências de resultados em builds ao longo do tempo.
apidog run --access-token $APIDOG_ACCESS_TOKEN -t 605067 -e 1629989 -r junit --out-dir ./apidog-reports
Se você escolher apenas um formato de máquina para CI, escolha este. A recompensa é que seus resultados de teste não vivem apenas em um arquivo de log, mas começam a viver no painel que sua equipe já consulta. Um revisor abre uma pull request e vê as asserções que falharam renderizadas diretamente, sem procurar no log, sem baixar artefatos.
Configurá-lo envolve duas etapas: produzir o XML e, em seguida, dizer ao seu sistema de CI onde encontrá-lo. No GitLab CI, essa segunda etapa é o bloco reports: junit::
api-tests:
stage: test
image: node:20
script:
- npm install -g apidog-cli
- apidog run --access-token "$APIDOG_ACCESS_TOKEN" -t 605067 -e 1629989 -r junit,cli --out-dir ./apidog-reports
artifacts:
when: always
paths:
- apidog-reports/
reports:
junit: apidog-reports/*.xml
No Jenkins, o equivalente é a etapa junit em um bloco post apontado para os mesmos arquivos. No GitHub Actions, você faz o upload do diretório como um artefato e deixa uma ação que reconhece JUnit renderizá-lo. O fluxo de trabalho completo do GitHub, incluindo o upload de artefatos que é executado mesmo quando os testes falham, está em executando testes Apidog CLI no GitHub Actions.
json: o relatório que seus scripts pós-processam
O relatório json produz o resultado estruturado bruto. Onde HTML é para olhos e JUnit é para painéis, JSON é para o código que você mesmo escreve.
apidog run --access-token $APIDOG_ACCESS_TOKEN -t 605067 -e 1629989 -r json --out-dir ./apidog-reports
Recorra a ele quando os formatos embutidos não se encaixam no que você deseja fazer com o resultado. Envie métricas de taxa de aprovação para um sistema de monitoramento. Construa um resumo personalizado para o Slack. Alimente o resultado em um script que decide se deve reverter uma implantação. Compare a execução de hoje com a de ontem. Qualquer coisa programática começa com o JSON, porque é o formato que você pode analisar sem adivinhar a estrutura.
Uma flag de relatório é construída especificamente para a saída JSON. --out-json-failures-separated <value> separa as falhas em seu próprio arquivo JSON. Isso lhe dá um documento apenas com falhas, que é muito mais fácil de ler e comparar (diff) do que escanear um resultado completo para o punhado de etapas que falharam. Em uma grande varredura de regressão onde a maioria das etapas passa, um arquivo apenas com falhas é a diferença entre um olhar rápido e um grep.
Onde os arquivos são salvos: --out-dir, --out-file e placeholders
Escolher formatos é metade da história. A outra metade é controlar onde os arquivos são salvos e como são nomeados, o que importa no momento em que você mantém mais de um relatório de execução.
--out-dir <dir> define o diretório para onde os relatórios são gravados. O padrão é ./apidog-reports. Em CI, aponte-o para um local que sua etapa de artefatos possa encontrar e mantenha-o consistente para que sua configuração de upload nunca precise mudar:
apidog run --access-token $APIDOG_ACCESS_TOKEN -t 605067 -e 1629989 -r html,junit --out-dir ./apidog-reports
--out-file <name> define o nome do arquivo de relatório, e é aqui que ele se torna útil. Sem ele, cada execução tende a sobrescrever a anterior, então você sempre mantém apenas o relatório mais recente. A flag aceita placeholders que o executor preenche no momento da gravação:
{SCENARIO_NAME}se torna o nome do cenário que foi executado.{FOLDER_NAME}se torna o nome da pasta quando você executa uma pasta de cenários.{GENERATE_TIME}se torna um timestamp.
Carimbe um nome de arquivo com o nome do cenário e um timestamp e cada execução gravará um arquivo distinto e autoexplicativo, em vez de sobrescrever o anterior:
apidog run --access-token $APIDOG_ACCESS_TOKEN -t 605067 -e 1629989 -r html --out-file "{SCENARIO_NAME}-{GENERATE_TIME}"
Agora seu diretório de relatórios parece um histórico. Você pode dizer qual relatório veio de qual cenário e quando foi executado sem abrir um único arquivo, o que é exatamente o que você deseja quando está escaneando uma pasta de execuções noturnas para encontrar aquela em que as coisas deram errado pela primeira vez.
Mais uma flag de relatório completa o lado da nuvem. --upload-report [value] faz o upload de uma visão geral do relatório para a nuvem Apidog, para que a execução também apareça no histórico do seu projeto junto com os arquivos locais. É a opção a ser usada quando você deseja que o resultado seja visível dentro do próprio Apidog, não apenas como um arquivo no executor de CI.
Uma estratégia de relatório por público
A maneira mais clara de decidir é mapear cada relatório para quem o lê, e então passar os que você precisa juntos.
- Uma pessoa escaneando o log de build agora lê
cli. Sempre o inclua. - Uma pessoa abrindo um relatório salvo mais tarde lê
html. Arquive-o como um artefato. - O painel de CI lê
junit. É o que renderiza as falhas na pull request e as tendências dos resultados entre os builds. - Um script que você escreveu lê
json. É o único formato destinado a ser analisado pelo seu próprio código.
Para a maioria dos pipelines de CI, a combinação de trabalho é HTML para humanos mais JUnit para o painel, com CLI mantido ativo para que o log bruto permaneça legível:
apidog run --access-token $APIDOG_ACCESS_TOKEN -t 605067 -e 1629989 -r cli,html,junit --out-dir ./apidog-reports
Essa única execução produz um log legível, um artefato navegável e um arquivo XML analisável. Três públicos, uma execução, sem duplicação.
Uma ressalva que vale a pena mencionar claramente: o relatório informa o que aconteceu, mas o código de saída é o que faz o pipeline agir sobre isso. O Apidog CLI sai com um código diferente de zero quando qualquer asserção falha, e esse código de saída, e não o relatório, é o que falha o build e bloqueia o merge. O relatório explica a falha; o código de saída a impõe. Não envolva o comando em algo que engula esse código, como adicionar || true em um shell, ou você obterá um relatório vermelho perfeito anexado a um build que ainda ficou verde. A versão mais aprofundada dessa lógica de quality gate está no guia para automatizar testes de API em CI/CD.
Unindo tudo
Execute um cenário em CI e emita todos os três artefatos úteis para três públicos:
apidog run --access-token $APIDOG_ACCESS_TOKEN -t 605067 -e 1629989 -n 1 -r cli,html,junit --out-dir ./apidog-reports
Execute uma varredura de pasta noturna, colete todas as falhas em um relatório e dê a cada arquivo um nome autoexplicativo:
apidog run --access-token $APIDOG_ACCESS_TOKEN -f 88012 -r html,junit --on-error continue --out-dir ./nightly-reports --out-file "{FOLDER_NAME}-{GENERATE_TIME}"
Execute um cenário orientado a dados e mantenha um JSON apenas com falhas para comparações rápidas:
apidog run --access-token $APIDOG_ACCESS_TOKEN -t 605067 -d ./accounts.csv -r json --out-json-failures-separated true --out-dir ./apidog-reports
Se você preferir não instalar o CLI globalmente em um executor efêmero, troque a instalação por npx e mantenha as mesmas flags de relatório:
npx apidog-cli run --access-token $APIDOG_ACCESS_TOKEN -t 605067 -e 1629989 -r html,junit --out-dir ./apidog-reports
O comportamento do relatório é idêntico em ambos os casos; a escolha entre uma instalação global e npx é sobre a higiene do executor, não sobre quais relatórios você obtém.
Nomes de flags, padrões e relatórios podem mudar entre os lançamentos do CLI, então o executor é sempre sua própria fonte de verdade. Execute apidog run --help na versão que você tem instalada e confie nisso mais do que em qualquer artigo, incluindo este. Para configurar o cenário que o CLI executa em primeiro lugar, Baixe o Apidog, construa um cenário no aplicativo, depois copie o comando gerado da aba CI/CD e adicione os relatórios de que você precisa.