Como Automatizar Testes de API no Travis CI Usando Apidog CLI

Sua API funciona na sua máquina. Os testes de unidade estão verdes. Você faz o merge, implanta e, uma hora depois, um colega te avisa: o endpoint /checkout está retornando um erro 500 para qualquer um com um carrinho vazio. O bug nunca esteve no código que você alterou; estava em um contrato a dois serviços de distância que ninguém re-testou. Esta é a lacuna que os testes de API em nível de integração preenchem, e é exatamente o tipo de verificação que você quer que rode automaticamente em cada commit, em vez de depender da memória de alguém.

Travis CI é um dos serviços de integração contínua hospedados mais antigos, e ainda faz uma coisa bem: ele observa seu repositório Git, inicia um ambiente limpo para cada push e pull request, e executa quaisquer comandos que você coloque em um arquivo .travis.yml. A maioria das equipes o usa para ciclos de compilação e testes de unidade. Bem menos o usam para executar testes HTTP reais contra uma API em execução, embora seja aí que os bugs caros se escondem. A razão é a fricção. Conectar um executor de testes de API a uma caixa de CI, passar segredos com segurança e obter um sinal de aprovação/reprovação é tão complicado que as pessoas pulam essa etapa.

Este guia aborda como fechar essa lacuna com o executor de linha de comando Apidog. Você projeta e depura seus testes de API no aplicativo de desktop Apidog, onde pode ver as requisições e asserções visualmente, e então executa exatamente os mesmos testes em modo headless dentro do Travis CI com um único comando. Sem reescrever a lógica de teste como código, sem manter uma estrutura de teste separada. O artigo cobre o caminho completo: um .travis.yml mínimo, instalando o executor, passando seu token de acesso com segurança, escolhendo o que executar, gerando relatórios e fazendo com que o build falhe ruidosamente quando um endpoint quebrar. Baixe o Apidog se quiser acompanhar.

Por que executar testes de API no CI?

Testes de unidade confirmam que uma função retorna o valor correto. Testes de API confirmam que todo o ciclo de requisição-resposta se comporta: a rota existe, a autenticação é imposta, o código de status está correto, o esquema JSON corresponde e os valores dentro do corpo são sensatos. Estes são modos de falha diferentes, e o segundo tipo é o que seus usuários realmente encontram.

Executá-los localmente é bom até que não seja mais. As execuções locais dependem de você se lembrar de executá-los, de sua máquina corresponder à configuração de produção e de você não estar no meio do café quando uma regressão passa despercebida. A integração contínua remove todas as três desculpas. Cada push aciona a mesma suíte no mesmo ambiente, e o resultado é anexado ao commit e ao pull request para que todos vejam.

Há uma recompensa mais profunda para equipes de API especificamente. Quando seus testes vivem ao lado do design de sua API, uma mudança disruptiva aparece como uma asserção falha no momento em que é enviada, não como um ticket de suporte. Se você quiser o contexto conceitual de onde isso se encaixa em um pipeline de entrega, o explicador o que é CI/CD é uma boa leitura complementar; este artigo se concentra na construção prática do Travis CI.

O que você precisa antes de começar

Três coisas, e você provavelmente já tem duas delas.

• Um repositório Git conectado ao Travis CI. O nível gratuito em travis-ci.com funciona para repositórios públicos e privados dentro dos limites de uso.

• Um projeto Apidog com pelo menos um cenário de teste que você já construiu e executou com sucesso no aplicativo de desktop. Um cenário de teste no Apidog é um conjunto ordenado de requisições de API com asserções; pense nisso como um fluxo ponta a ponta, como "entrar, criar um pedido, buscar o pedido, excluí-lo".
• Node.js. O Apidog CLI roda em Node, e precisa da versão 16 ou superior. O Travis fornece Node de fábrica no ambiente de linguagem node_js, então isso é principalmente uma declaração de uma linha.

Se você ainda não construiu um cenário de teste, faça isso primeiro no aplicativo. O objetivo principal deste fluxo de trabalho é que você depure visualmente uma vez, e depois automatize para sempre. Tentar criar testes cegamente dentro de um log de CI é o caminho lento. Para os fundamentos de como escrever boas verificações, asserções de API: um guia prático cobre como validar códigos de status, corpos de resposta e esquema JSON antes mesmo de você fazer um push.

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

O Apidog CLI executa seus testes armazenados na nuvem em modo headless, então ele precisa de duas peças de identidade:

1. Um token de acesso que prova que o executor está autorizado a ler seu projeto. Gere-o nas configurações da sua conta Apidog em tokens de acesso. Trate-o como uma senha; ele concede acesso à API aos dados do seu projeto.
2. Um ID de cenário de teste. Abra o cenário no aplicativo de desktop e copie seu ID, ou use a opção "Executar no CI/CD", que gera um comando pronto com o ID já preenchido.

A maneira mais fácil de obter um primeiro comando correto é deixar o Apidog escrevê-lo para você. Dentro de um cenário de teste, a opção de execução CI/CD produz algo assim:

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

Essa é a forma completa: autenticar, apontar para um cenário (-t), apontar para um ambiente (-e) e escolher um relator (-r). Copie isso, confirme que funciona no seu próprio laptop primeiro, e só então mova para o Travis. Verificar localmente economiza uma dúzia de builds vermelhos gastos depurando um erro de digitação em um token.

Passo 2: Armazene o token como uma variável Travis criptografada

Nunca cole seu token de acesso no .travis.yml. Esse arquivo é commitado para o Git, e um token vazado dá a qualquer um acesso de leitura aos dados do seu projeto de API. O Travis tem duas opções seguras.

A maneira limpa é usar variáveis de ambiente do repositório definidas na interface web do Travis. Vá para as configurações do seu repositório no Travis, encontre as variáveis de ambiente e adicione:

• APIDOG_ACCESS_TOKEN com o valor do seu token
• APIDOG_ENV_ID com o ID do ambiente contra o qual você deseja testar

Deixe a opção "exibir valor no log de build" desativada para que o token nunca seja impresso. O Travis injeta estas como variáveis de ambiente reais em cada build, e sua configuração as referencia pelo nome. Isso mantém os segredos totalmente fora do repositório, que é o comportamento que você deseja; se um colaborador fizer um fork do repositório, seu token não irá junto.

Se você preferir tudo no arquivo, o Travis também suporta variáveis criptografadas via sua CLI:

travis encrypt APIDOG_ACCESS_TOKEN="seu-token-aqui" --add env.global

Isso escreve um blob criptografado no .travis.yml que somente o build do seu repositório pode descriptografar. Ambas as abordagens funcionam. A rota da interface do usuário é mais simples para a maioria das equipes e mais fácil de girar quando um token expira.

Passo 3: Escreva o .travis.yml

Aqui está uma configuração completa e mínima que instala o Apidog CLI e executa um cenário em cada push e pull request:

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

Três blocos fazem o trabalho. language: node_js com uma versão fornece um tempo de execução Node novo o suficiente para a CLI. A etapa install instala apidog-cli globalmente para que o comando apidog esteja no PATH. A etapa script executa seus testes. O relator -r cli imprime um resumo de aprovação/reprovação legível diretamente no log do Travis, que é o que você vai observar quando algo quebrar.

Observe que o ID do cenário é codificado, mas os segredos vêm das variáveis de ambiente. Essa é a divisão correta: o ID não é sensível, o token é. Commit este arquivo, faça um push, e o Travis executa seus testes de API automaticamente. O primeiro build verde é o momento em que sua API ganha uma rede de segurança.

Se você mantém vários serviços e quer um modelo mental compartilhado entre os executores, o passo a passo automatize testes de API em CI/CD mostra o mesmo padrão aplicado a outras plataformas, e a versão para GitHub Actions é quase idêntica em espírito, caso você migre algum dia.

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

Esta é a parte que as equipes esquecem, e silenciosamente derrota todo o exercício. Um trabalho de CI só é útil se um teste falhando deixar o build vermelho. Se o executor sai com zero, não importa o que aconteça, você construiu uma impressora de log muito cara.

Boas notícias: o Apidog CLI já faz a coisa certa. Quando uma asserção falha, o processo apidog run sai com um código de status diferente de zero, e o Travis trata qualquer saída diferente de zero na fase script como uma falha de build. Então, a configuração mínima acima já falha corretamente de fábrica. Você não precisa de cola extra.

O que você pode ajustar é como a execução se comporta no meio do cenário quando uma única requisição dá erro. A flag --on-error controla isso:

• --on-error end para o cenário na primeira falha. Feedback mais rápido, menos saída.
• --on-error continue executa os passos restantes para que você veja todas as falhas em uma única passagem.
• --on-error ignore continua e não permite que erros parem a execução.

Para CI, continue geralmente é o ponto ideal: você quer a imagem completa do que quebrou sem que o trabalho seja interrompido após a primeira asserção vermelha, enquanto ainda termina com uma saída diferente de zero para que o build falhe. Uma linha de script razoável se parece com isto:

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

Evite a tentação de adicionar || true ao comando para "fazer o build passar". Isso engole o código de saída e reintroduz o ponto cego exato que você se propôs a remover.

Passo 5: Gerar e manter um relatório HTML

O relatório cli é bom para uma olhada rápida, mas quando um build falha, você geralmente quer um artefato mais rico: qual requisição, qual asserção, qual era o corpo da resposta real. A CLI gera um relatório HTML com o relator html, e você pode empilhar relatores em uma única execução.

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

-r cli,html imprime no log e escreve um arquivo HTML autônomo. --out-dir define onde o relatório é salvo, por padrão em ./apidog-reports. Para que esse relatório sobreviva após o término do build, implante-o em algum lugar que o Travis possa publicar, como um bucket S3 ou GitHub Pages, em um bloco deploy. Um padrão comum:

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

Se você preferir não gerenciar o armazenamento de artefatos, a CLI pode enviar o relatório para a nuvem Apidog com --upload-report, onde sua equipe pode abri-lo a partir de um link sem qualquer hospedagem extra. Essa é a opção de menor manutenção para equipes distribuídas.

Passo 6: Adicione ambientes, dados e execuções em matriz

Um único cenário contra um único ambiente é um bom começo. Pipelines reais crescem em três direções, e as flags da CLI mapeiam-se de forma limpa para cada uma.

Múltiplos ambientes. A flag -e seleciona quais URLs base e variáveis de ambiente usar. Execute o mesmo cenário contra o ambiente de staging em cada push e contra o ambiente de produção em um build cron noturno trocando o ID do ambiente. Os trabalhos cron do Travis são configurados por repositório na interface de configurações.

Execuções orientadas a dados. A flag -d (forma longa --iteration-data) alimenta um arquivo CSV ou JSON no seu cenário para que ele execute uma vez por linha. É assim que você cobre casos de borda: entrada válida, campos ausentes, payloads superdimensionados, caracteres especiais, tudo a partir de uma definição de cenário. Combine com -n (--iteration-count) quando você quiser um número fixo de repetições em vez de iterações baseadas em arquivo.

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

Cenários paralelos. As matrizes de build do Travis permitem executar vários cenários ao mesmo tempo em trabalhos paralelos. Defina uma matriz de variáveis de ambiente onde cada entrada carrega um ID de cenário diferente, e cada trabalho da matriz executa um. O build só fica verde quando todos eles passam.

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

À medida que as suítes crescem, organizar os cenários em suítes de teste para testes de API automatizados mantém a matriz gerenciável em vez de se tornar uma parede de IDs.

Por que isso supera a codificação manual de testes em seu script CI

Você poderia escrever testes de API diretamente em um script Travis com curl e jq, ou como uma execução Newman de uma coleção exportada. Ambos funcionam, e ambos envelhecem mal.

A abordagem curl-mais-shell transforma cada asserção em uma comparação de strings frágil. Verificar um campo JSON aninhado se torna uma invocação jq; verificar um esquema é basicamente impossível; e no momento em que sua API adiciona um campo, metade dos seus greps precisa ser reescrita. Você acaba mantendo uma segunda cópia, pior, do seu conhecimento de API em Bash.

A abordagem do executor de coleções é melhor, mas acopla seu CI a um ritual de exportação e sincronização: edite testes em uma ferramenta, exporte, comite o JSON, espere que ele não se desvie da realidade. A deriva é real, e é a fonte das reclamações "os testes passam, mas a API está quebrada". Escrevemos sobre esse modo de falha exato em por que suas coleções Postman não são uma fonte de verdade, e se você estiver executando coleções em CI hoje, como executar coleções Postman em CI sem Newman cobre o caminho de migração.

O modelo Apidog fecha o ciclo. Seus testes, seu design de API, seus ambientes e seus mock servers vivem em um só lugar. A CLI executa a versão ao vivo e atual desses testes; não há nada para exportar e nada para se desalinhar. Você depura uma asserção instável visualmente no aplicativo, salva, e a próxima execução do CI detecta a mudança. Essa única fonte de verdade é a razão principal para usar um executor dedicado em vez de uma pilha de scripts shell. Se você está avaliando-o contra sua configuração atual, o resumo das melhores alternativas ao Postman para testes de API coloca as opções lado a lado.

Uma nota sobre o Travis CI especificamente

Travis foi o CI de código aberto padrão por anos, e muitos repositórios mais antigos ainda o utilizam. Se você está começando do zero em 2026, vale a pena saber que o campo mudou; GitHub Actions, GitLab CI e CircleCI agora carregam a maioria dos novos projetos, e nossa comparação das melhores ferramentas de CI/CD detalha onde cada uma se encaixa. A boa notícia é que o Apidog CLI é agnóstico à plataforma por design. O mesmo comando apidog run que funciona no seu .travis.yml funciona em uma etapa do GitHub Actions, em um .gitlab-ci.yml do GitLab ou em um estágio do Jenkins. Se você algum dia sair do Travis, seus testes de API se movem com você inalterados; apenas as chaves YAML circundantes diferem. Essa portabilidade é um benefício silencioso, mas real, de manter a lógica de teste fora da sintaxe específica do CI.

Perguntas frequentes

Preciso instalar o aplicativo de desktop Apidog na caixa de CI? Não. O aplicativo de desktop é para projetar e depurar testes. O Travis precisa apenas do pacote npm apidog-cli e de um tempo de execução Node 16+, que o ambiente de linguagem node_js já fornece. O CLI busca e executa seus cenários armazenados na nuvem em modo headless.

Onde encontro meu token de acesso e ID do cenário? Gere o token de acesso nas configurações da sua conta Apidog em "tokens de acesso". O ID do cenário é visível no aplicativo de desktop em cada cenário de teste; a opção integrada "Executar no CI/CD" também gera um comando completo com o ID pré-preenchido, que é a maneira mais rápida de obter uma linha de base funcional.

Como mantenho o token fora do meu repositório? Defina-o como uma variável de ambiente do repositório na interface web do Travis com a exibição do log de build desativada, e então referencie-o como $APIDOG_ACCESS_TOKEN em sua configuração. Alternativamente, use travis encrypt para armazenar um valor criptografado em .travis.yml. Nunca comite o token em texto puro.

O build realmente falhará se um teste falhar? Sim. O comando apidog run sai com um código diferente de zero quando uma asserção falha, e o Travis trata qualquer saída diferente de zero na fase script como um build falho. Apenas não suprima o código de saída com || true. Use --on-error continue se quiser que todas as falhas sejam relatadas em uma única execução, mas ainda fazendo o build falhar.

Posso executar testes contra múltiplos ambientes ou com múltiplos conjuntos de dados? Sim. Use -e para alternar ambientes (staging no push, produção em um cron noturno), -d para alimentar um arquivo de dados CSV ou JSON para iterações orientadas a dados, e uma matriz de build do Travis para executar vários cenários em trabalhos paralelos.

Posso usar isso se não estiver no Travis CI? Sim. O comando CLI é idêntico em todas as plataformas. Troque o YAML circundante para GitHub Actions, GitLab CI ou Jenkins e a linha apidog run permanece a mesma.

Concluindo

Colocar testes de API no Travis CI se resume a quatro passos: armazenar seu token de acesso como uma variável criptografada, instalar apidog-cli na etapa de instalação, executar seu cenário com apidog run na etapa de script e deixar o código de saída diferente de zero falhar o build. A partir daí, você adiciona relatórios HTML, múltiplos ambientes, iterações orientadas por dados e uma matriz paralela à medida que sua suíte cresce.

A razão para fazer isso com um executor dedicado, em vez de uma parede de chamadas curl, é a fonte única de verdade. Você projeta e depura visualmente, e então executa a versão ao vivo desses testes exatos em cada commit, sem uma etapa de exportação para que as coisas se desalinhem. Sua regressão no /checkout é capturada no pull request, não em produção.

Construa seu primeiro cenário de teste, então baixe o Apidog e conecte-o ao seu próximo push. Assim que o primeiro build ficar verde, cada commit subsequente será enviado com uma rede de segurança.