DEV Community

Cover image for Como Automatizar Testes de API no Travis CI Usando Apidog CLI
Lucas
Lucas

Posted on • Originally published at apidog.com

Como Automatizar Testes de API no Travis CI Usando Apidog CLI

Sua API funciona localmente, os testes unitários passam e o merge parece seguro. Uma hora depois do deploy, alguém percebe que /checkout retorna 500 quando o carrinho está vazio. O problema não estava na função alterada, mas em um contrato entre serviços que ninguém executou novamente. Testes de API em nível de integração fecham essa lacuna — e devem rodar automaticamente a cada commit.

Experimente o Apidog hoje

Travis CI observa seu repositório Git, cria um ambiente limpo para cada push ou pull request e executa os comandos definidos no .travis.yml. Muitas equipes usam isso para build e testes unitários, mas deixam de fora testes HTTP reais contra uma API em execução — justamente onde regressões caras aparecem.

Neste guia, você vai executar cenários de teste criados no Apidog dentro do Travis CI usando o apidog-cli. O fluxo é simples: você cria e depura os testes visualmente no app desktop, depois executa os mesmos cenários em modo headless no CI. Sem reescrever testes em Bash, sem manter uma suíte paralela. Se quiser acompanhar, baixe o Apidog.

Por que executar testes de API no CI?

Testes unitários validam funções isoladas. Testes de API validam o ciclo completo de requisição e resposta:

  • a rota existe;
  • a autenticação está correta;
  • o status HTTP é o esperado;
  • o corpo JSON tem o formato certo;
  • os dados retornados fazem sentido;
  • contratos entre serviços continuam compatíveis.

Executar isso apenas localmente não escala. Alguém precisa lembrar de rodar os testes, a máquina local precisa estar configurada corretamente e regressões podem passar despercebidas. No CI, cada push executa a mesma suíte no mesmo ambiente e anexa o resultado ao commit ou pull request.

Se quiser o contexto de pipeline, leia também o que é CI/CD. Aqui o foco é a implementação prática no Travis CI.

Pré-requisitos

Você precisa de:

  • Um repositório Git conectado ao Travis CI.
  • Um projeto Apidog com pelo menos um cenário de teste já criado e executado com sucesso no app desktop.
  • Node.js 16 ou superior. O Travis fornece isso usando language: node_js.

Captura de tela das configurações do Travis CI para variáveis de ambiente

No Apidog, um cenário de teste é uma sequência de requisições com asserções. Por exemplo:

  1. fazer login;
  2. criar um pedido;
  3. buscar o pedido;
  4. validar o corpo da resposta;
  5. excluir o pedido.

Crie e depure esse fluxo no app antes de levá-lo para o CI. Depurar testes diretamente em logs do Travis é mais lento. Para escrever verificações melhores, veja asserções de API: um guia prático.

Passo 1: Obtenha o token de acesso e o ID do cenário

O apidog-cli precisa de duas informações para executar seus testes na nuvem:

  1. Token de acesso: autoriza o CLI a ler seus projetos e cenários.
  2. ID do cenário de teste: identifica qual fluxo deve ser executado.

No Apidog, abra o cenário e use a opção Executar no CI/CD para gerar um comando base. Ele será parecido com isto:

apidog run --access-token <seu-token-de-acesso> -t 5564321 -e 4417023 -r cli
Enter fullscreen mode Exit fullscreen mode

Onde:

  • --access-token autentica a execução;
  • -t define o ID do cenário;
  • -e define o ID do ambiente;
  • -r cli gera saída legível no terminal.

Antes de configurar o Travis, teste o comando localmente:

npm install -g apidog-cli

apidog run --access-token <seu-token-de-acesso> -t 5564321 -e 4417023 -r cli
Enter fullscreen mode Exit fullscreen mode

Se funcionar localmente, fica muito mais fácil isolar problemas depois no CI.

Passo 2: Salve o token como variável segura no Travis

Não coloque o token diretamente no .travis.yml. Esse arquivo vai para o Git, e um token vazado pode expor dados do seu projeto de API.

A forma recomendada é usar variáveis de ambiente no Travis:

  1. Abra as configurações do repositório no Travis.
  2. Vá até Environment Variables.
  3. Adicione: 
APIDOG_ACCESS_TOKEN=<seu-token>
APIDOG_ENV_ID=<id-do-ambiente>
Enter fullscreen mode Exit fullscreen mode

Mantenha desativada a opção de exibir o valor nos logs do build.

Depois, no .travis.yml, referencie essas variáveis assim:

$APIDOG_ACCESS_TOKEN
$APIDOG_ENV_ID
Enter fullscreen mode Exit fullscreen mode

Se preferir usar a CLI do Travis, você também pode criptografar o valor:

travis encrypt APIDOG_ACCESS_TOKEN="seu-token-aqui" --add env.global
Enter fullscreen mode Exit fullscreen mode

Para a maioria dos times, configurar pela interface web é mais simples e facilita a rotação do token.

Passo 3: Crie o .travis.yml

Comece com uma configuração mínima:

language: node_js

node_js:
  - "18"

cache:
  npm: true

install:
  - npm install -g apidog-cli

script:
  - apidog run --access-token $APIDOG_ACCESS_TOKEN -t 5564321 -e $APIDOG_ENV_ID -r cli
Enter fullscreen mode Exit fullscreen mode

O que cada bloco faz:

  • language: node_js: inicia um ambiente Node no Travis.
  • node_js: "18": garante uma versão compatível com o CLI.
  • install: instala o apidog-cli.
  • script: executa o cenário de teste.
  • -r cli: imprime o resultado no log do Travis.

O ID do cenário (5564321) pode ficar no YAML porque não é segredo. O token deve vir sempre da variável de ambiente.

Faça commit e push:

git add .travis.yml
git commit -m "Executa testes de API no Travis CI"
git push
Enter fullscreen mode Exit fullscreen mode

O Travis deve iniciar um build e executar o cenário automaticamente.

Se você usa outros provedores de CI/CD, o padrão é o mesmo. Veja também automatize testes de API em CI/CD e a versão para GitHub Actions.

Passo 4: Faça o build falhar quando o teste falhar

Um teste de API no CI só é útil se uma falha deixar o build vermelho.

O apidog run já retorna código de saída diferente de zero quando uma asserção falha. O Travis interpreta isso como falha no build.

Ou seja, este comando já é suficiente:

script:
  - apidog run --access-token $APIDOG_ACCESS_TOKEN -t 5564321 -e $APIDOG_ENV_ID -r cli
Enter fullscreen mode Exit fullscreen mode

Você pode controlar o comportamento diante de erros com --on-error:

  • --on-error end: encerra no primeiro erro.
  • --on-error continue: continua executando os próximos passos e mostra mais falhas.
  • --on-error ignore: ignora erros durante a execução.

Para CI, uma boa opção é:

script:
  - apidog run --access-token $APIDOG_ACCESS_TOKEN -t 5564321 -e $APIDOG_ENV_ID -r cli --on-error continue
Enter fullscreen mode Exit fullscreen mode

Assim, você vê mais falhas em uma única execução, mas o build ainda fica vermelho se houver erro.

Evite isto:

script:
  - apidog run --access-token $APIDOG_ACCESS_TOKEN -t 5564321 -e $APIDOG_ENV_ID -r cli || true
Enter fullscreen mode Exit fullscreen mode

|| true engole o código de saída e faz o build passar mesmo com testes quebrados.

Passo 5: Gere um relatório HTML

O relatório no terminal é útil, mas em falhas reais você geralmente quer mais detalhes:

  • qual requisição falhou;
  • qual asserção falhou;
  • qual era o corpo real da resposta;
  • qual era o valor esperado.

Use o relator html junto com cli:

script:
  - apidog run --access-token $APIDOG_ACCESS_TOKEN -t 5564321 -e $APIDOG_ENV_ID -r cli,html --out-dir ./apidog-reports
Enter fullscreen mode Exit fullscreen mode

Isso faz duas coisas:

  • imprime o resumo no log do Travis;
  • grava um relatório HTML em ./apidog-reports.

Para publicar o relatório, você pode usar GitHub Pages:

deploy:
  provider: pages
  skip_cleanup: true
  github_token: $GITHUB_TOKEN
  local_dir: apidog-reports
  on:
    branch: main
Enter fullscreen mode Exit fullscreen mode

Outra opção é enviar o relatório para a nuvem do Apidog:

apidog run --access-token $APIDOG_ACCESS_TOKEN -t 5564321 -e $APIDOG_ENV_ID -r cli,html --upload-report
Enter fullscreen mode Exit fullscreen mode

Essa abordagem evita manter infraestrutura própria para artefatos.

Passo 6: Execute múltiplos ambientes, dados e cenários

Depois do primeiro cenário, normalmente a suíte cresce. Você pode evoluir em três direções.

Múltiplos ambientes

Use -e para trocar o ambiente:

apidog run --access-token $APIDOG_ACCESS_TOKEN -t 5564321 -e $APIDOG_ENV_ID -r cli
Enter fullscreen mode Exit fullscreen mode

Exemplos comuns:

  • rodar contra staging em cada push;
  • rodar contra produção em um cron noturno;
  • usar ambientes separados por branch.

No Travis, cron jobs são configurados nas opções do repositório.

Testes orientados por dados

Use -d ou --iteration-data para passar um CSV ou JSON:

apidog run --access-token $APIDOG_ACCESS_TOKEN -t 5564321 -e $APIDOG_ENV_ID -d ./test-data.csv -r cli
Enter fullscreen mode Exit fullscreen mode

Isso permite testar o mesmo fluxo com múltiplas entradas:

email,password,expected_status
user@example.com,correct-password,200
user@example.com,wrong-password,401
invalid-email,any-password,400
Enter fullscreen mode Exit fullscreen mode

Também existe -n ou --iteration-count para repetir a execução um número fixo de vezes.

Cenários paralelos com matriz do Travis

Para executar vários cenários em paralelo, use uma matriz de variáveis:

language: node_js

node_js:
  - "18"

install:
  - npm install -g apidog-cli

env:
  - SCENARIO_ID=5564321   # fluxo de checkout
  - SCENARIO_ID=5564322   # fluxo de autenticação
  - SCENARIO_ID=5564323   # fluxo de busca

script:
  - apidog run --access-token $APIDOG_ACCESS_TOKEN -t $SCENARIO_ID -e $APIDOG_ENV_ID -r cli --on-error continue
Enter fullscreen mode Exit fullscreen mode

Cada entrada em env vira um job separado. O build só passa se todos os cenários passarem.

Quando a suíte crescer, organize os testes em suítes de teste para testes de API automatizados.

Por que não escrever tudo com curl?

Você poderia testar APIs no Travis com curl, jq e Bash:

response=$(curl -s -o response.json -w "%{http_code}" https://api.exemplo.com/checkout)

if [ "$response" != "200" ]; then
  exit 1
fi
Enter fullscreen mode Exit fullscreen mode

Isso funciona para casos simples, mas degrada rápido:

  • asserções viram comparações frágeis de strings;
  • validar JSON aninhado exige scripts maiores;
  • validar schema fica trabalhoso;
  • cenários com autenticação, variáveis e dependências entre requisições ficam difíceis de manter.

Executores baseados em coleções também ajudam, mas podem criar outro problema: exportar, versionar e sincronizar arquivos separados da fonte real da API. Quando a coleção exportada fica desatualizada, os testes deixam de refletir o estado atual do projeto.

Esse problema é discutido em por que suas coleções Postman não são uma fonte de verdade. Se você executa coleções no CI hoje, veja também como executar coleções Postman em CI sem Newman.

Com o Apidog, os testes, ambientes, design da API e mock servers ficam no mesmo lugar. O CI executa a versão atual dos cenários, sem etapa manual de exportação. Para comparar alternativas, veja melhores alternativas ao Postman para testes de API.

Observação sobre Travis CI

Travis CI ainda é comum em muitos projetos, especialmente repositórios mais antigos. Se você está começando um pipeline novo, também vale avaliar GitHub Actions, GitLab CI, CircleCI e Jenkins. A comparação em melhores ferramentas de CI/CD ajuda nessa escolha.

A parte boa: o comando principal não muda.

apidog run --access-token $APIDOG_ACCESS_TOKEN -t 5564321 -e $APIDOG_ENV_ID -r cli
Enter fullscreen mode Exit fullscreen mode

O que muda entre provedores é apenas o YAML ao redor. A lógica dos testes continua fora da sintaxe específica do CI.

Perguntas frequentes

Preciso instalar o app desktop do Apidog no Travis?

Não. O app desktop é usado para criar e depurar os testes. No Travis, você instala apenas o pacote npm:

npm install -g apidog-cli
Enter fullscreen mode Exit fullscreen mode

O CLI executa os cenários armazenados na nuvem em modo headless.

Onde encontro o token e o ID do cenário?

Gere o token nas configurações da sua conta Apidog, em tokens de acesso. O ID do cenário aparece no app desktop. A opção Executar no CI/CD também gera um comando completo com o ID preenchido.

Como mantenho o token fora do repositório?

Defina APIDOG_ACCESS_TOKEN como variável de ambiente no Travis e desative a exibição no log. Depois, use:

$APIDOG_ACCESS_TOKEN
Enter fullscreen mode Exit fullscreen mode

Nunca comite o token em texto puro.

O build falha mesmo se apenas uma asserção falhar?

Sim. Quando uma asserção falha, apidog run retorna código diferente de zero. O Travis marca o build como falho.

Use --on-error continue se quiser coletar mais falhas em uma única execução.

Posso executar testes contra múltiplos ambientes?

Sim. Use -e para selecionar o ambiente:

apidog run --access-token $APIDOG_ACCESS_TOKEN -t 5564321 -e $APIDOG_ENV_ID -r cli
Enter fullscreen mode Exit fullscreen mode

Você pode alternar entre staging, produção ou ambientes por branch.

Posso usar dados externos?

Sim. Use -d com CSV ou JSON:

apidog run --access-token $APIDOG_ACCESS_TOKEN -t 5564321 -e $APIDOG_ENV_ID -d ./test-data.csv -r cli
Enter fullscreen mode Exit fullscreen mode

Posso usar isso fora do Travis CI?

Sim. O comando apidog run é o mesmo. Você só troca a configuração do provedor, como GitHub Actions, GitLab CI ou Jenkins. A versão para GitHub Actions segue a mesma ideia.

Conclusão

Para executar testes de API no Travis CI:

  1. crie e valide um cenário no Apidog;
  2. salve o token como variável segura no Travis;
  3. instale apidog-cli no build;
  4. execute apidog run no bloco script;
  5. deixe o código de saída falhar o build;
  6. adicione relatórios, dados e matriz conforme a suíte crescer.

Configuração mínima:

language: node_js

node_js:
  - "18"

install:
  - npm install -g apidog-cli

script:
  - apidog run --access-token $APIDOG_ACCESS_TOKEN -t 5564321 -e $APIDOG_ENV_ID -r cli --on-error continue
Enter fullscreen mode Exit fullscreen mode

Esse fluxo transforma seus cenários de API em uma rede de segurança automática. A regressão no /checkout deixa de aparecer em produção e passa a quebrar o pull request.

Crie seu primeiro cenário, conecte ao Travis e faça o próximo push com testes de API rodando no CI.

Top comments (0)