Como Rodar Testes de API em CI Com apidog run

Você copiou um comando de uma aba de CI/CD, colou-o em um pipeline e ele funcionou. Então, um colega de equipe pergunta por que a compilação ainda está verde quando um teste falhou claramente, ou se você pode apontar a mesma execução para o ambiente de *staging* em vez de produção, ou como obter um relatório que seu painel de CI realmente analisará. De repente, a linha única não é mais suficiente. Você precisa saber o que cada parte dela faz.

apidog run é o comando único no coração do executor de linha de comando do Apidog. Ele executa os cenários de teste de API que você construiu no Apidog sem interface gráfica, a partir de um terminal, sem GUI e sem um humano clicando em um botão. Tudo o que o executor pode fazer, ele faz através de *flags* neste único comando: qual cenário executar, qual ambiente atingir, quantas vezes iterar, quais relatórios emitir e o que conta como falha. Aprenda a superfície de *flags* uma vez e você para de copiar e colar às cegas.

O que é apidog run

O Apidog CLI é distribuído como um pacote npm chamado apidog-cli. Você o instala uma vez e obtém um único binário, apidog, cujo subcomando principal é run. Esse subcomando pega um dos seus cenários de teste do Apidog e o executa da mesma forma que o aplicativo de desktop faria, então retorna com um código de saída e quaisquer arquivos de relatório que você solicitou.

Instale-o globalmente:

npm install -g apidog-cli

Confirme se foi resolvido:

apidog -v

O que é preciso entender antes das *flags* é sobre o que apidog run opera. Ele não define seu próprio formato de teste. O teste é o cenário que você criou no aplicativo Apidog: requisições encadeadas, asserções, valores extraídos de uma resposta para a próxima, iteração opcional orientada a dados. O CLI acessa seu projeto, encontra o cenário pelo ID e o executa. Portanto, a maioria das *flags* serve para dizer ao executor o que buscar e como se comportar durante a execução, não para escrever testes embutidos.

Um comando real mínimo se parece com isto:

apidog run --access-token $APIDOG_ACCESS_TOKEN -t 605067 -e 1629989 -n 1 -r html,cli

Isso significa: autentique com este *token*, execute o cenário de teste 605067, no ambiente 1629989, uma vez, e produza um relatório HTML mais a saída legível no terminal. Cada *flag* nessa linha é explicada abaixo, juntamente com as que esse comando omite.

A superfície completa de opções em um relance

Aqui está o conjunto completo de opções agrupadas por função. Use-o como uma tabela de consulta; as seções seguintes explicam as que precisam de mais do que uma frase.

Nomes de *flags* e padrões podem mudar entre as versões do CLI. Em caso de dúvida, o *runner* é sua própria fonte da verdade: execute apidog run --help na versão que você instalou e confie nisso mais do que em qualquer artigo, incluindo este.

Escolhendo o que executar

Três *flags* decidem o escopo de uma execução, e você escolhe exatamente uma delas por comando.

-t, --test-scenario <id> executa um único cenário. Este é o caso diário: um teste de fumaça focado, um cenário de regressão, uma coisa que você quer garantir em uma *pull request*.

-f, --test-scenario-folder <id> executa todos os cenários dentro de uma pasta. Use isso quando você organizou uma área de funcionalidade em uma pasta e deseja que todo o grupo seja executado como um único trabalho, como uma varredura de regressão noturna.

--test-suite <id> executa um conjunto de testes curado, que é um conjunto de cenários que você montou para rodar juntos como uma unidade lógica. Um conjunto é a ferramenta certa quando os cenários que você deseja não estão todos em uma pasta, mas ainda pertencem ao mesmo ciclo de teste.

Mais dois seletores refinam onde o executor procura. --project <id> nomeia o projeto em que um cenário reside, útil quando seu *token* tem acesso a mais de um. --branch <name> executa o cenário como ele existe em um *branch* específico em vez do main, o que permite validar mudanças de teste em um *branch* de funcionalidade antes de serem mescladas.

# um cenário
apidog run --access-token $APIDOG_ACCESS_TOKEN -t 605067 -e 1629989 -r cli

# uma pasta inteira
apidog run --access-token $APIDOG_ACCESS_TOKEN -f 88012 -r html,junit

# um conjunto de testes curado
apidog run --access-token $APIDOG_ACCESS_TOKEN --test-suite 40231 -r junit

Autenticando a execução

--access-token <token> é a única *flag* que toda execução online precisa. Ela comprova que a execução está autorizada a buscar e executar seu cenário. Você gera o *token* dentro da aba CI/CD de um cenário de teste no Apidog, onde o aplicativo também constrói o comando completo apidog run para você com o ID do cenário e o ID do ambiente já preenchidos.

Trate o *token* como uma senha. Não o cole em um arquivo de *pipeline* commitado ou em um *script* compartilhado. Armazene-o como um segredo em seu sistema de CI e passe-o através de uma variável de ambiente, razão pela qual cada exemplo aqui faz referência a $APIDOG_ACCESS_TOKEN em vez de uma *string* literal. Se um *token* vazar, regenere-o da mesma aba de CI/CD e o antigo deixará de funcionar.

Apontando para um ambiente e iterando

A *flag* de ambiente é o que permite que um cenário sirva a muitos propósitos. -e, --environment <id> aponta a execução para um ambiente específico, de modo que o mesmo cenário pode verificar o *staging* em um *gate* de *pull request* e a produção em um teste de fumaça pós-implantação sem que você precise duplicar nada. Se você gerencia valores entre ambientes, o guia sobre gerenciamento de ambiente e segredos para clientes de API explica como esses valores fluem.

-n, --iteration-count <n> executa o cenário n vezes seguidas. Útil para uma verificação rápida de estabilidade ou para repetir um fluxo que deveria ser idempotente.

-d, --iteration-data <path> é a *flag* orientada a dados. Aponte-a para um arquivo JSON ou CSV e o executor executa o cenário uma vez por linha, tratando cada linha como sua própria passagem com seus próprios valores de entrada. É assim que você executa um cenário de *login* em cinquenta contas, ou um fluxo de criação de pedido em uma tabela de *payloads*. O padrão mais profundo está em teste de API orientado a dados com CSV e JSON.

Três *flags* injetam valores sem editar o cenário. --variables <path> carrega variáveis de um arquivo local. --global-var chave=valor define uma variável global em linha. --env-var chave=valor sobrescreve uma única variável de ambiente apenas para esta execução. Isso é útil em CI quando um valor (uma URL base, uma *feature flag*) difere por *pipeline* e você não quer um ambiente separado para cada um. Se as variáveis no Apidog são novas para você, dominando variáveis no Apidog explica os escopos.

# executa um cenário 50 vezes em um CSV de entradas
apidog run --access-token $APIDOG_ACCESS_TOKEN -t 605067 -d ./accounts.csv -r junit

# sobrescreve uma variável de ambiente apenas para esta execução
apidog run --access-token $APIDOG_ACCESS_TOKEN -t 605067 -e 1629989 --env-var baseUrl=https://staging.internal -r cli

Repórteres: todos os formatos de saída que apidog run pode produzir

Este é o grupo que as pessoas mais procuram, então aqui está cada repórter e para que serve. Você os seleciona com -r, --reporters e pode passar vários de uma vez, separados por vírgula. O padrão é cli.

cli imprime um resumo legível no terminal. É o que um humano escaneia no log de compilação para ver as contagens de sucesso/falha e quais asserções falharam. Mantenha-o ativado mesmo ao lado de formatos de máquina para que o log permaneça útil.

html escreve um relatório HTML autocontido. Arquive-o como um artefato de compilação e abra-o em um navegador para ver a execução completa com detalhes de requisição e resposta. Este é o formato que você entrega a alguém que não estava assistindo ao *pipeline*.

junit emite XML no formato JUnit padrão. Quase todo painel de CI sabe como analisar o XML JUnit em uma árvore de sucesso/falha, exibir falhas em um *widget* de *merge-request* e rastrear resultados ao longo do tempo. Se você escolher apenas um formato de máquina para CI, escolha este.

json produz o resultado estruturado bruto. Use-o quando quiser pós-processar o resultado você mesmo: alimentá-lo em um *script*, enviar métricas para algum lugar ou construir um resumo personalizado.

Uma combinação comum de CI é HTML para humanos mais JUnit para o painel:

apidog run --access-token $APIDOG_ACCESS_TOKEN -t 605067 -r html,junit --out-dir ./apidog-reports

As *flags* de relatório restantes controlam onde a saída é gravada e o que mais ela inclui:

• --out-dir <dir> define o diretório onde os relatórios são gravados. O padrão é ./apidog-reports.
• --out-file <name> define o nome do arquivo de relatório e aceita os *placeholders* {FOLDER_NAME}, {SCENARIO_NAME} e {GENERATE_TIME}, para que você possa identificar arquivos com o nome do cenário e um carimbo de data/hora em vez de sobrescrever um único arquivo a cada execução.
• --out-json-failures-separated <value> separa as falhas em seu próprio arquivo JSON, o que torna fácil ler uma diferença apenas das falhas.
• --upload-report [value] carrega uma visão geral do relatório para a nuvem Apidog para que a execução apareça no histórico do seu projeto junto com os arquivos locais.

Controlando falhas: tratamento de erros e códigos de saída

Um executor só é útil em um *pipeline* se ele informar ao *pipeline* se os testes foram aprovados. apidog run faz isso da maneira como ferramentas de linha de comando bem-comportadas fazem: ele sai com 0 quando todas as asserções passam e um código diferente de zero quando algo falha. Esse único comportamento é a porta de qualidade inteira. O CI lê o código de saída, marca a etapa como falha e bloqueia a mesclagem ou implantação. Você não configura uma porta; o código de saída é a porta.

--on-error <behavior> molda o que acontece quando uma etapa falha no meio do cenário, e tem três valores:

• end interrompe a execução na primeira etapa falhada. Use-o para um teste de fumaça com falha rápida onde você quer *feedback* no instante em que algo quebra.
• continue executa todas as etapas restantes para que você colete todas as falhas em um único relatório. Use-o para uma varredura de regressão onde ver todas as falhas de uma vez economiza uma rodada.
• ignore permite que a execução continue após uma etapa conhecida por ser intermitente sem tratá-la como fatal. Use-o com moderação; uma etapa ignorada não deve estar escondendo uma regressão real.

De qualquer forma, se alguma asserção falhou, a execução ainda termina com um código diferente de zero, então a porta se mantém independentemente do comportamento que você escolheu. Uma coisa que silenciosamente quebra a porta: envolver o comando em algo que engole seu código de saída, como adicionar || true em um *shell*. Não faça isso. O código de saída diferente de zero é o objetivo.

Quatro *flags* ajustam o comportamento da requisição durante a execução:

• --ignore-redirects impede que o executor siga automaticamente os redirecionamentos HTTP, para que você possa fazer asserções na própria resposta de redirecionamento.
• --delay-request [n] espera n milissegundos entre as requisições, o que ajuda contra limites de taxa ou *endpoints* sensíveis à carga.
• --timeout-request [n] define o tempo máximo que uma única requisição pode levar, em milissegundos.
• --timeout-script [n] define o tempo máximo que um *script* pré ou pós-requisição pode ser executado, em milissegundos.

# teste de fumaça: para na primeira falha
apidog run --access-token $APIDOG_ACCESS_TOKEN -t 605067 -e 1629989 -r cli --on-error end

# regressão: executa tudo, coleta todas as falhas
apidog run --access-token $APIDOG_ACCESS_TOKEN -f 88012 -r html,junit --on-error continue --out-dir ./nightly-reports

TLS e certificados

Quando você testa *endpoints* por trás de TLS mútuo ou uma autoridade de certificação interna, este grupo mostra como fazer a conexão.

-k, --insecure desabilita completamente a verificação de certificado SSL. Use-o apenas contra um *host* interno confiável com um certificado autoassinado; nunca aponte para nada público, porque isso desativa a verificação que protege a conexão.

Para um TLS mútuo adequado, forneça as credenciais do cliente: --ssl-client-cert <path> para o certificado PEM, --ssl-client-key <path> para sua chave privada e --ssl-client-passphrase <passphrase> se a chave for criptografada. Quando diferentes *hosts* precisam de diferentes certificados, --ssl-client-cert-list <path> aponta para um arquivo de configuração que os mapeia. E --ssl-extra-ca-certs <path> adiciona certificados CA confiáveis extras, que é a solução limpa para uma cadeia CA interna que o executor não reconheceria de outra forma, melhor do que usar -k.

Saída e diagnósticos

O último grupo controla o que o executor imprime e alguns detalhes de execução.

--verbose imprime a requisição e resposta completas para cada etapa. Este é o seu primeiro passo quando um cenário passa localmente, mas falha no CI: ele mostra os bytes exatos que o executor enviou e recebeu, para que você possa comparar com o que você envia manualmente. --silent faz o oposto, suprimindo a saída do console para trabalhos agendados barulhentos onde você só se preocupa com o código de saída e o relatório salvo. --color <value> força a saída colorida a ser ativada ou desativada, útil quando um visualizador de *logs* de CI *mangles* códigos ANSI.

O restante é para recursos específicos do cenário:

• --external-program-path <path> aponta para um arquivo de programas externos para lógica personalizada que um cenário invoca.
• --database-connection <path> fornece uma configuração de banco de dados para cenários com etapas que consultam um banco de dados diretamente.
• --preferred-http-version <version> define a versão do protocolo HTTP que o executor prefere.
• -b, --bigint habilita o tratamento de BigInt para que grandes valores numéricos não percam precisão.
• --lang <language> define o idioma de exibição do CLI.
• -h, --help imprime o texto de ajuda, que é a lista autoritativa para sua versão instalada.

Juntando tudo: comandos que você realmente executará

Teste de fumaça contra produção logo após uma implantação, falhando rapidamente:

apidog run --access-token $APIDOG_ACCESS_TOKEN -t 605067 -e $PROD_ENV_ID -r cli --on-error end

Regressão noturna completa em uma pasta, todas as falhas em um relatório HTML e JUnit:

apidog run --access-token $APIDOG_ACCESS_TOKEN -f 88012 -r html,junit --on-error continue --out-dir ./nightly-reports

Execução orientada a dados em um CSV, saída legível por máquina para CI:

apidog run --access-token $APIDOG_ACCESS_TOKEN -t 605067 -d ./test-cases.csv -r junit

Valide as alterações de teste em um *branch* de funcionalidade antes de serem mescladas:

apidog run --access-token $APIDOG_ACCESS_TOKEN -t 605067 --branch feature-payments -e 1629989 -r cli

Depure uma falha apenas de CI despejando os detalhes da comunicação:

apidog run --access-token $APIDOG_ACCESS_TOKEN -t 605067 -e 1629989 -r cli --verbose

Se você estiver executando o CLI em um *runner* de CI efêmero e preferir não instalar globalmente, troque a instalação por npx:

npx apidog-cli run --access-token $APIDOG_ACCESS_TOKEN -t 605067 -e 1629989 -r junit

Isso cobre a mesma superfície. A escolha entre uma instalação global e npx é sobre higiene do *runner*, não capacidade. Para configurar o cenário que o CLI executa, Baixe o Apidog, construa um cenário no aplicativo, então copie o comando gerado da sua aba CI/CD e parametrize o *token*.\