A maioria dos testes de API começa sua vida em uma GUI. Você clica por aí, adiciona algumas asserções e os executa manualmente. Isso funciona até que você precise que os mesmos testes sejam executados a cada push, a cada noite, ou dentro de um pipeline onde ninguém está assistindo. Nesse ponto, você deseja um comando que possa digitar, roteirizar e canalizar para o CI.
Esse comando é o Apidog CLI. Este tutorial o guiará através do teste de uma API REST real de ponta a ponta a partir do seu terminal: instale a ferramenta, importe uma API, configure um ambiente, construa um cenário de teste, execute-o com asserções, alimente-o com dados e colete relatórios. Cada comando e saída abaixo vem de uma execução real no Apidog CLI versão 2.2.2 contra uma API pública ativa, para que você possa acompanhar e obter os mesmos resultados.
Se você quiser o lado visual da mesma plataforma, pode baixar o Apidog e projetar os testes no aplicativo primeiro. Mas tudo aqui permanece na linha de comando.
O que você construirá
Você testará restful-api.dev, uma API REST pública gratuita com CRUD real sobre um recurso /objects. Ao final, você terá:
- Um projeto Apidog semeado a partir de um arquivo OpenAPI
- Um cenário de teste de três etapas que cria um objeto, o lê de volta e o exclui, fazendo asserções em cada etapa
- Uma execução orientada a dados que repete uma requisição uma vez por linha de dados de teste
- Relatórios CLI, HTML, JSON e JUnit, além de um relatório em nuvem compartilhável
O mesmo fluxo se adapta à sua própria API, e é a base para executar testes de API em CI/CD.
Antes de começar
Você precisa do Node.js 16 ou mais recente e de uma conta Apidog. Se você está comparando *runners* primeiro, a versão curta é que o Apidog CLI executa cenários de teste completos e gerencia recursos de API como código, o que o diferencia de Newman e do Postman CLI.
Passo 1: Instalar e fazer login
Instale o CLI globalmente a partir do npm:
npm install -g apidog-cli@latest
Confirme que está lá:
apidog --version
# 2.2.2
Agora autentique-se. Obtenha um token do aplicativo Apidog sob o seu avatar, Configurações da Conta, Token de Acesso à API, então execute:
apidog login --with-token <SEU_TOKEN>
O token é salvo em ~/.apidog/config.toml, então você só faz isso uma vez por máquina. Verifique quem você é:
Cada comando retorna JSON estruturado com um sinalizador success e agentHints úteis, o que facilita o *scripting* da saída ou o direcionamento para jq.
Passo 2: Criar um projeto
Escolha a equipe na qual criar o projeto e, em seguida, crie-o:
apidog team list
apidog project create --team 329562 --name "CLI Field Test"
Você recebe o ID do novo projeto.
Salve-o em uma variável de *shell* para que o restante deste tutorial seja copiar e colar:
PID=1314366 # substitua pelo seu ID de projeto
apidog project get $PID
Passo 3: Importar sua API REST
Você poderia criar *endpoints* manualmente, mas importar um arquivo OpenAPI é mais rápido e espelha como projetos reais começam. Aqui está uma pequena especificação descrevendo os *endpoints* CRUD de /objects (salve-o como objects-api.openapi.json):
{
"openapi": "3.0.3",
"info": { "title": "Objects API", "version": "1.0.0" },
"servers": [{ "url": "https://api.restful-api.dev" }],
"paths": {
"/objects": {
"get": { "summary": "List objects" },
"post": { "summary": "Create object" }
},
"/objects/{id}": {
"get": { "summary": "Get object by id" },
"put": { "summary": "Update object" },
"delete": { "summary": "Delete object" }
}
}
}
Importe-o:
apidog import --project $PID --format openapi --file ./objects-api.openapi.json
# "createCount": 5 (5 endpoints criados, 0 erros)
O importador também lê openapi, postman, har, insomnia, jmeter e muito mais. Liste o que foi adicionado:
apidog endpoint list --project $PID
# 37921721 get /objects
# 37921722 post /objects
# 37921723 get /objects/{id}
# 37921724 put /objects/{id}
# 37921725 delete /objects/{id}
Passo 4: Configurar um ambiente
Um ambiente contém a URL base e quaisquer variáveis que seus testes reutilizam. Crie um e salve seu ID:
apidog environment create "Production" --project $PID --base-url "https://api.restful-api.dev"
apidog environment list --project $PID
# { "id": 6334917, "name": "Production", "baseUrls": { "default": "https://api.restful-api.dev" } }
ENV=6334917 # substitua pelo seu ID de ambiente
Você passará -e $ENV para o comando de execução mais tarde, para que o teste saiba onde enviar as requisições.
Passo 5: Superar o bloqueio de escrita de automação
Aqui está a primeira coisa que confunde as pessoas. Cenários de teste e dados de teste são recursos de automação, e escrevê-los em sua ramificação principal a partir de uma ferramenta externa é bloqueado por padrão:
apidog test-scenario create --project $PID --name "x" --description "" --folder-id 0 --priority 1
# "error": { "code": "403075", "message": "Automation caller branch required" }
Isso é uma salvaguarda, não um *bug*. Você tem duas maneiras de contornar isso:
- Ativar a permissão de edição direta no aplicativo de desktop Apidog em Configurações do Projeto, Configurações de Recursos, Configurações de Recursos de IA, Permissões de Edição de IA Externa.
- Trabalhar em uma ramificação de IA, que mantém as alterações de automação isoladas até que você decida mesclar. Este caminho permanece totalmente na linha de comando, então é isso que usaremos.
Crie a ramificação a partir de main:
apidog branch create --project $PID --type ai \
--name "ai/20260616-from-main-cli-field-test" --from main
BR="ai/20260616-from-main-cli-field-test"
O padrão de nomenclatura ai/AAAAMMDD-from-<origem>-<recurso> é a convenção que o CLI espera. Note que import, environment create e edições de *endpoint* não são bloqueados; apenas os recursos de automação são.
Passo 6: Construir um cenário de teste
Um cenário é um fluxo ordenado de requisições com asserções entre elas. Você cria o *shell* primeiro, depois adiciona as etapas. Crie-o em sua ramificação de IA:
apidog test-scenario create --project $PID --branch "$BR" \
--name "Ciclo de vida CRUD de Objetos" \
--description "Cria, lê e depois exclui um objeto e faz asserções em cada etapa" \
--folder-id 0 --priority 1
SID=1836498 # o ID do cenário retornado
As etapas são adicionadas através de update com um arquivo JSON. A regra de ouro para qualquer escrita JSON é validar antes de enviar, para que você nunca envie uma carga malformada:
apidog cli-schema get test-scenario-update # veja o formato exato
apidog cli-schema validate test-scenario-update --file ./steps-crud.json
# "data file is valid"
Cada etapa é uma requisição mais um pequeno *script* que verifica a resposta e passa os dados para a próxima etapa. Aqui está o formato da etapa de criação, que envia um novo objeto e salva seu id para etapas posteriores:
{
"type": "customHttp",
"name": "Create object",
"customHttpRequest": {
"path": "https://api.restful-api.dev/objects",
"method": "post",
"requestBody": { "type": "json", "data": "{\"name\":\"Apidog CLI Field Test\",\"data\":{\"price\":42}}" },
"postProcessors": [{
"type": "customScript",
"data": "pm.test('create returns 200', function () { pm.response.to.have.status(200); });\nvar body = pm.response.json();\npm.globals.set('objId', body.id);",
"enable": true
}],
"projectId": 1314366
}
}
As próximas etapas reutilizam {{objId}} na URL para buscar e depois excluir o mesmo objeto. Aplique o arquivo completo de três etapas:
apidog test-scenario update $SID --project $PID --branch "$BR" --file ./steps-crud.json
# "success": true
Você não precisa criar cenários como JSON. Construí-los visualmente no Apidog e executá-los a partir do CLI é igualmente válido. O caminho JSON importa quando você quer seus testes versionados e revisados como qualquer outro código.
Passo 7: Executar a partir da linha de comando
Este é o resultado. Execute o cenário com o *reporter* CLI:
apidog run -t $SID --project $PID --branch "$BR" -e $ENV -r cli
❏ Ciclo de vida CRUD de Objetos
↳ Criar objeto POST .../objects [200 OK]
✓ criar retorna 200 ✓ resposta tem um id ✓ nome foi ecoado de volta
↳ Obter o objeto criado GET .../objects/ff80...3de [200 OK]
✓ obter retorna 200 ✓ id corresponde ao objeto criado ✓ preço persistido nos dados
↳ Excluir o objeto DELETE .../objects/ff80...3de [200 OK]
✓ excluir retorna 200
Requisições Http 3 / 0 falharam
Asserções 7 / 0 falharam
Três requisições, sete asserções, zero falhas, e o id criado fluiu da primeira etapa para as duas seguintes. Isso é um teste de API completo rodando sem um único clique.
Quer arquivos em vez de saída no console? Peça vários *reporters* de uma vez e aponte-os para uma pasta:
apidog run -t $SID --project $PID --branch "$BR" -e $ENV \
-r cli,html,json,junit --out-dir ./reports --out-file "crud-report"
ls ./reports
# crud-report.html crud-report.json crud-report.xml
O XML do JUnit é o que seu servidor CI lê para mostrar aprovação/falha por *build*. O relatório HTML é o que você compartilha com os colegas de equipe.
Passo 8: Executar o mesmo teste contra várias entradas
Suítes de teste reais cobrem mais de um caso. Execuções orientadas a dados repetem um cenário uma vez por linha de dados, para que você teste dez entradas sem escrever dez cenários. Esta é a mesma ideia de testes parametrizados a partir de CSV e JSON.
Coloque suas linhas em um arquivo:
[
{ "name": "Pixel 8 Pro", "price": 999 },
{ "name": "iPhone 15", "price": 899 },
{ "name": "Galaxy S24", "price": 799 }
]
Referencie os dados com -d, e deixe o cenário ler {{name}} e {{price}} de cada linha:
apidog run -t $DID --project $PID --branch "$BR" -e $ENV -d ./objects-data.json -r cli
Iteração 1/3 … ✓ linha criada (200) ✓ nome corresponde à linha de dados
Iteração 2/3 … ✓ linha criada (200) ✓ nome corresponde à linha de dados
Iteração 3/3 … ✓ linha criada (200) ✓ nome corresponde à linha de dados
Iterações 3 / 0 falharam Asserções 6 / 0 falharam
Três linhas de entrada, três iterações de saída. Troque o arquivo por um CSV e nada mais muda.
Passo 9: Coletar relatórios
As execuções locais escrevem arquivos. Para obter um relatório que toda a sua equipe possa abrir em um navegador, adicione --upload-report:
apidog run -t $SID --project $PID --branch "$BR" -e $ENV -r cli --upload-report
# Os dados das execuções do Apidog CLI foram enviados para a nuvem com sucesso.
# https://app.apidog.com/link/project/1314366/api-test/test-report/2605398
Um detalhe que vale a pena saber: um relatório na nuvem é marcado com a ramificação em que foi executado. Como esta execução aconteceu na sua ramificação de IA, um simples apidog test-report list --project $PID (que visa main) não o mostrará. Busque-o pelo ID do link de upload em vez disso:
apidog test-report get 2605398 --project $PID
apidog test-report download 2605398 --project $PID --format json --output ./cloud-report.json
Passo 10: Exportar sua API como documentação ou uma especificação
O CLI também exporta dados. Exporte o projeto como um arquivo OpenAPI, Markdown ou documentação HTML:
apidog export --project $PID --format openapi --oas-version 3.0 --output ./openapi-export.json
apidog export --project $PID --format markdown --output ./api-docs.md
apidog export --project $PID --format html --output ./api-docs.html
Isso é útil para *commitar* uma nova especificação a cada alteração ou publicar documentação estática a partir de um *pipeline*.
Passo 11: Conectá-lo ao CI/CD
Tudo o que você executou manualmente se torna três linhas em um pipeline. O núcleo é instalar, depois executar com o *reporter* JUnit para que o servidor CI possa ler os resultados:
- run: npm install -g apidog-cli@latest
- run: apidog login --with-token $APIDOG_TOKEN
- run: apidog run -t $SID --project $PID -e $ENV -r junit --out-dir ./reports
Armazene o *token* como um segredo e faça com que o *build* falhe quando um teste falhar (o CLI retorna um código de saída diferente de zero em caso de falhas). Para um *workflow* completo e pronto para copiar e colar, consulte o guia sobre como executar testes do Apidog CLI no GitHub Actions, ou explore ferramentas de automação de testes de API que se encaixam em um *pipeline*.
Concluindo
Você passou de um terminal vazio para um teste de API *data-driven* e bem-sucedido com relatórios compartilháveis, e nunca saiu da linha de comando. O padrão é sempre o mesmo: importe ou projete sua API, crie um ambiente, construa um cenário com asserções e, em seguida, execute-o com apidog run. Uma vez que esse comando funcione localmente, incluí-lo no CI é uma alteração de três linhas.
Aponte os mesmos passos para sua própria API, *commite* os arquivos de cenário junto com seu código, e seus testes rodarão onde quer que um *shell* funcione. Baixe o Apidog para começar, e mantenha as alternativas ao curl para teste de API REST à mão para as verificações rápidas para as quais o CLI é um exagero.