Você escreveu os testes de API. Eles passam na sua máquina. E é exatamente lá que eles ficam, porque executá-los é algo que alguém precisa lembrar de fazer. Um colega de equipe implementa uma alteração na tarde de sexta-feira, o endpoint de autenticação silenciosamente começa a retornar um 500 em um caminho de código, e a primeira pessoa a descobrir é um usuário na segunda-feira. A cobertura estava lá o tempo todo. Ninguém a executou no momento em que teria detectado a regressão.
A solução é mover os testes do seu editor para o pipeline, para que eles sejam executados a cada push sem a necessidade de intervenção humana. Isso significa que você precisa de um comando que execute seus testes de API sem interface gráfica (headless), retorne um resultado claro de sucesso ou falha, e se encaixe em qualquer sistema de CI que você já use. O CLI do Apidog faz isso. Você constrói seus cenários de teste visualmente no Apidog e os executa a partir de um único comando de terminal que qualquer executor de CI com Node.js pode executar. Sem GUI, sem reescrever testes como código, sem serviço extra para hospedar.
Este é um guia de copiar e colar. Abaixo, você encontrará arquivos de pipeline prontos para uso para GitHub Actions, GitLab CI, Jenkins, CircleCI e Azure Pipelines, além de alguns padrões que mantêm uma construção verde honesta. Pegue o bloco para sua plataforma, troque seus IDs e um segredo, e você terá testes de API protegendo cada merge até o final do dia. Se você quiser a referência exaustiva de flags, o tópico mais amplo de como automatizar testes de API em CI/CD cobre a estratégia; esta página é sobre como obter um pipeline funcional copiado e colado.
O que você está configurando
O CLI do Apidog é um pacote npm, apidog-cli. Ele executa os cenários de teste que você cria no aplicativo Apidog: requisições encadeadas, asserções, valores extraídos de uma resposta para a próxima, iteração orientada por dados. O CLI não inventa seu próprio formato de teste. Ele acessa seu projeto, encontra o cenário por ID, o executa da mesma forma que o aplicativo faria e retorna um código de saída.
Esse código de saída é o ponto chave. Quando todas as asserções passam, a execução sai com 0. Quando algo falha, ela sai com um código diferente de zero. Os sistemas de CI leem esse código de saída, marcam a etapa como falha e bloqueiam o merge ou a implantação. Você não configura um portão; o portão é o código de saída. Enquanto a etapa apidog run estiver no seu pipeline, uma asserção quebrada interrompe a linha.
Três coisas fazem uma execução funcionar, e você as verá em todos os blocos abaixo:
- Um token de acesso, que comprova que a execução tem permissão para executar seu cenário. Trate-o como uma senha. Armazene-o como um segredo de CI, nunca em um arquivo commitado.
- Um ID de cenário (ou ID de pasta, ou ID de suíte de testes), que diz o que executar.
- Um ID de ambiente, que diz onde executar: desenvolvimento, staging ou produção.
Você não digita esses IDs manualmente. Abra o cenário de teste no Apidog, vá para a aba CI/CD, escolha a opção de linha de comando e gere um token de acesso. O Apidog lhe entregará o comando completo apidog run com o ID do cenário e o ID do ambiente já preenchidos. Copie-o uma vez e, em seguida, mova o token para um segredo. Se você ainda não construiu um cenário, comece com como escrever cenários de teste com o Apidog e retorne quando tiver um funcionando.
O único comando em que tudo se baseia
Aqui está a execução canônica. Cada arquivo de pipeline é um wrapper em torno desta linha:
apidog run \
--access-token $APIDOG_ACCESS_TOKEN \
-t 605067 \
-e 1629989 \
-n 1 \
-r html,junit \
--out-dir ./apidog-reports
O que cada parte faz:
--access-tokenautentica a execução. Ele lê da variável de ambiente$APIDOG_ACCESS_TOKEN, que você preenche a partir de um segredo.-t 605067executa o cenário de teste com esse ID. Troque-tpor-f <folderId>para executar uma pasta inteira, ou--test-suite <id>para executar uma suíte de testes curada.-e 1629989direciona para um ambiente. É assim que o mesmo cenário atinge o staging em uma verificação de PR e a produção em um teste de fumaça pós-implantação.-n 1executa o cenário uma vez. Aumente para fazer um loop, ou combine com-d <file>para iterar a partir de um arquivo de dados CSV ou JSON.-r html,junitescolhe os formatos de relatório.junitemite o XML que seu dashboard de CI analisa em uma árvore de aprovação/reprovação;htmlé um relatório navegável que você salva como um artefato de build. Adicioneclise quiser uma saída legível no log também.--out-dir ./apidog-reportsé onde os relatórios são salvos.
Os relatórios são a diferença entre "a build ficou vermelha" e "aqui está a asserção que falhou e a resposta que a quebrou". O JUnit XML é o formato que quase todas as plataformas entendem nativamente, então ele aparece em todos os cinco blocos abaixo.
GitHub Actions
Coloque isso em .github/workflows/api-tests.yml. Ele executa seu cenário em cada pull request para main, carrega o relatório como um artefato e falha a verificação se qualquer asserção falhar.
name: API tests
on:
pull_request:
branches: [main]
jobs:
api-tests:
runs-on: ubuntu-latest
steps:
- name: Checkout
uses: actions/checkout@v4
- name: Set up Node.js
uses: actions/setup-node@v4
with:
node-version: '20'
- name: Install Apidog CLI
run: npm install -g apidog-cli
- name: Run API test scenario
run: |
apidog run \
--access-token "$APIDOG_ACCESS_TOKEN" \
-t 605067 \
-e 1629989 \
-n 1 \
-r html,junit \
--out-dir ./apidog-reports
env:
APIDOG_ACCESS_TOKEN: ${{ secrets.APIDOG_ACCESS_TOKEN }}
- name: Upload report
if: always()
uses: actions/upload-artifact@v4
with:
name: apidog-report
path: ./apidog-reports
Dois detalhes importantes. O token reside em Settings → Secrets and variables → Actions como APIDOG_ACCESS_TOKEN e chega à etapa via env:. E if: always() na etapa de upload significa que você ainda receberá o relatório quando os testes falharem, que é o único momento em que você realmente precisa lê-lo. Se um cenário falhar, a etapa apidog run sai com um código diferente de zero, a job fica vermelha e o PR mostra uma verificação falha. Para uma análise mais aprofundada desta plataforma específica, veja como automatizar testes de API no GitHub Actions.
GitLab CI
A mesma ideia em .gitlab-ci.yml. A imagem node:20 já possui o tempo de execução, então a única configuração é a instalação.
stages:
- test
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
Armazene APIDOG_ACCESS_TOKEN em Settings → CI/CD → Variables como uma variável mascarada e protegida para que nunca seja impressa em um log. O bloco reports: junit: é a parte que os usuários do GitLab tendem a esquecer: ele instrui o GitLab a analisar o XML e renderizar os resultados diretamente no widget de solicitação de merge. Um revisor vê quais asserções falharam sem precisar baixar nada.
Jenkins
Para um pipeline declarativo, armazene o token como uma credencial Jenkins e puxe-o para o ambiente, então chame o CLI em uma etapa. O bloco post alimenta o XML JUnit nos gráficos de tendência de teste do Jenkins e mantém o relatório HTML na build.
pipeline {
agent any
environment {
APIDOG_ACCESS_TOKEN = credentials('apidog-access-token')
}
stages {
stage('API tests') {
steps {
sh 'npm install -g apidog-cli'
sh '''
apidog run \
--access-token $APIDOG_ACCESS_TOKEN \
-t 605067 \
-e 1629989 \
-n 1 \
-r html,junit \
--out-dir apidog-reports
'''
}
}
}
post {
always {
junit 'apidog-reports/*.xml'
archiveArtifacts artifacts: 'apidog-reports/**', allowEmptyArchive: true
}
}
}
Se seus agentes de build já tiverem o CLI em cache, remova a linha npm install e chame apidog run diretamente. O Apidog também oferece um guia de integração específico para Jenkins, caso você prefira o caminho do plugin em vez de uma etapa de shell: integrar testes automatizados do Apidog com Jenkins para CI/CD.
CircleCI
Em .circleci/config.yml, use a imagem de conveniência Node e armazene o token como uma variável de ambiente do projeto em Project Settings → Environment Variables.
version: 2.1
jobs:
api-tests:
docker:
- image: cimg/node:20.11
steps:
- checkout
- run:
name: Install Apidog CLI
command: npm install -g apidog-cli
- run:
name: Run API test scenario
command: |
apidog run \
--access-token "$APIDOG_ACCESS_TOKEN" \
-t 605067 \
-e 1629989 \
-r junit,cli \
--out-dir ./apidog-reports
- store_test_results:
path: ./apidog-reports
- store_artifacts:
path: ./apidog-reports
destination: apidog-reports
workflows:
test:
jobs:
- api-tests
store_test_results é o equivalente do CircleCI ao bloco JUnit do GitLab; aponte-o para o diretório de relatórios e o CircleCI exibirá as asserções falhas em sua aba de Testes. store_artifacts mantém o relatório HTML anexado para que você possa abri-lo na página da build.
Azure Pipelines
Em azure-pipelines.yml, instale o Node com a tarefa, execute o CLI e publique os resultados do JUnit. Adicione APIDOG_ACCESS_TOKEN como uma variável secreta no pipeline (ou puxe de um grupo de variáveis do Azure Key Vault), então mapeie-o para o env da etapa do script.
trigger:
- main
pool:
vmImage: ubuntu-latest
steps:
- task: NodeTool@0
inputs:
versionSpec: '20.x'
displayName: 'Install Node.js'
- script: npm install -g apidog-cli
displayName: 'Install Apidog CLI'
- script: |
apidog run \
--access-token "$APIDOG_ACCESS_TOKEN" \
-t 605067 \
-e 1629989 \
-r junit,html \
--out-dir ./apidog-reports
displayName: 'Run API test scenario'
env:
APIDOG_ACCESS_TOKEN: $(APIDOG_ACCESS_TOKEN)
- task: PublishTestResults@2
condition: always()
inputs:
testResultsFormat: 'JUnit'
testResultsFiles: 'apidog-reports/*.xml'
testRunTitle: 'Apidog API tests'
A macro $(APIDOG_ACCESS_TOKEN) lê a variável secreta do pipeline; mapeá-la através de env a mantém fora da linha de comando visível. PublishTestResults@2 com condition: always() faz com que os resultados apareçam na aba de Testes, independentemente de a execução ter sido bem-sucedida ou falha. Para um tratamento mais completo desta plataforma, o Apidog possui um tutorial dedicado sobre testes de API em pipelines do Azure DevOps.
Padrões que mantêm o portão honesto
Um pipeline que executa seus testes é a base. Essas receitas são o que o torna útil no dia a dia.
Teste de fumaça logo após a implantação. Execute um cenário rápido contra a produção no momento em que uma versão é lançada, apontado para o ambiente de produção, e pare na primeira falha:
apidog run --access-token $APIDOG_ACCESS_TOKEN -t 605067 -e <prodEnvId> -r cli --on-error end
Regressão completa durante a noite. Execute uma pasta inteira de cenários em um agendamento e colete todas as falhas em um único relatório, em vez de parar na primeira:
apidog run --access-token $APIDOG_ACCESS_TOKEN -f <folderId> -r html,junit --on-error continue --out-dir ./nightly-reports
--on-error é o controle aqui. end falha rapidamente, o que você quer para um portão de implantação. continue executa todas as etapas para que um relatório noturno mostre todas as quebras de uma vez. De qualquer forma, a execução ainda sai com código diferente de zero se algo falhou, então o portão se mantém.
Execute um cenário sobre várias entradas. Dirija as iterações a partir de um arquivo de dados e trate cada linha como sua própria passagem:
apidog run --access-token $APIDOG_ACCESS_TOKEN -t 605067 -d ./test-data.csv -r junit
Teste um branch de funcionalidade, não o main. Execute os cenários exatamente como eles existem em um branch:
apidog run --access-token $APIDOG_ACCESS_TOKEN -t 605067 --branch feature-payments -e 1629989 -r cli
Depure uma falha apenas em CI. Quando um cenário passa localmente, mas falha no pipeline, adicione --verbose. Ele imprime a requisição exata que o executor enviou e a resposta exata que ele recebeu, o que quase sempre é como você encontra a diferença de ambiente que está causando a lacuna.
Quando a build mente para você
Alguns modos de falha aparecem com frequência suficiente para serem destacados, porque cada um deles derrota silenciosamente o portão.
A build permanece verde quando um teste deveria falhar. Este é o perigoso. Quase sempre significa que o código de saída está sendo suprimido. Se você envolveu o comando em um pipeline de shell, ou adicionou || true para "impedir que quebrasse a build", você também o impediu de detectar qualquer coisa. Remova tudo que mascare a saída diferente de zero. A etapa apidog run deve ser a coisa que a etapa de CI lê.
Erros de autenticação. O token está errado, expirado ou nunca chegou ao comando. Confirme se o segredo do CI está realmente preenchido (um eco mascarado de seu comprimento, nunca o valor), e regenere-o da aba CI/CD do cenário, se necessário.
"Cenário não encontrado." O ID do cenário, o ID do projeto ou o branch não coincidem. Copie novamente o comando da aba CI/CD para garantir que os IDs estejam atualizados e verifique novamente se --branch aponta para onde você pensa.
Passa localmente, falha no CI. Quase sempre uma diferença de ambiente. O executor pode direcionar para um ambiente -e diferente, estar atrás de um firewall que não consegue alcançar seu host, ou faltar uma variável que o cenário precisa. Execute com --verbose e compare a requisição produzida pelo executor com a que você envia localmente.
Falhas de TLS contra hosts internos. Se o seu endpoint usa uma CA interna, passe o certificado CA extra em vez de desabilitar a verificação. Recorra a -k (ignorar verificação SSL) apenas como último recurso em um host interno confiável com um certificado autoassinado, nunca contra algo público.
Por que construir visualmente e executar sem interface gráfica
Existe uma escolha de design real por trás de tudo isso, e vale um parágrafo. Com executores script-first, o teste e sua execução são o mesmo arquivo, então um script frágil é tanto seu teste quanto seu gargalo. Com o Apidog, o cenário em seu projeto é o teste, e o CLI apenas o executa onde uma pessoa não pode estar. Ninguém mantém duas representações da mesma verificação. Você cria rapidamente no construtor visual, executa automaticamente no pipeline, e os dois permanecem sincronizados porque são o mesmo artefato. Essa é uma grande parte do porquê as equipes tratam o Apidog como uma alternativa ao Postman para testes de API quando o CI entra em cena, e por que asserções de API sólidas importam mais do que o executor em que você as envolve.
O ciclo é simples depois de iniciado. Projete e depure requisições no aplicativo. Encadeie-as em um cenário com asserções. Faça o push do seu código, e o CLI executa esse cenário no CI a cada alteração. Quando algo quebra, o relatório nomeia a asserção e o código de saída interrompe a implantação. Você corrige, faz o push novamente, e o mesmo portão confirma a correção.
Se seus testes ainda estão vivendo no editor de alguém, essa é a lacuna a ser fechada esta semana. Baixe o Apidog, faça um cenário passar, copie o comando apidog run da sua aba CI/CD e cole o bloco acima para sua plataforma. Você terá testes de API protegendo cada merge na mesma tarde.
Perguntas frequentes
O CLI do Apidog é gratuito para usar em CI? O CLI é um pacote npm gratuito: npm install -g apidog-cli. Ele executa os cenários do seu projeto Apidog, então o que você pode executar depende do seu plano Apidog, mas o próprio executor de linha de comando não é um produto pago separado.
Preciso reescrever meus testes como código? Não. Você constrói cenários visualmente no Apidog e o CLI os executa por ID. O cenário é o teste; o CLI é apenas o executor. Essa é a principal diferença em relação aos executores baseados em script.
Como um teste que falha realmente falha na minha build? Através do código de saída. Quando qualquer asserção falha, apidog run sai com um código diferente de zero. Seu sistema de CI lê isso, marca a etapa como falha e bloqueia o merge ou a implantação. Você não adiciona nenhuma configuração extra para que o portão funcione.
Qual formato de relatório devo usar? Use junit para o XML legível por máquina que seu painel de CI analisa em resultados de aprovação/reprovação, e adicione html se você quiser um relatório navegável salvo como um artefato de build. Uma combinação comum é -r junit,html. Mantenha cli também se você quiser uma saída legível no log da build.
Preciso instalar o Apidog no servidor de CI? Não. O executor de CI só precisa do Node.js (v16 ou superior) e do pacote apidog-cli. Sem aplicativo desktop, sem GUI, sem arquivo de licença na máquina. O pacote mais um token de acesso é suficiente.
Posso executá-lo sem uma instalação global? Sim. Use npx apidog-cli run ... para executá-lo sem uma instalação global persistente, o que é mais limpo em executores efêmeros que são derrubados após cada job.
Qual a diferença entre isso e o Newman? O Newman executa coleções Postman a partir da linha de comando. O CLI do Apidog executa cenários de teste do Apidog. As funções são paralelas, mas o executor do Apidog executa cenários que você criou no aplicativo e vem como um único pacote apidog-cli. Veja Postman CLI vs Newman para o lado Postman dessa comparação.
Onde consigo o token de acesso e os IDs? Tudo na aba CI/CD do cenário de teste no Apidog. Escolha a opção de linha de comando, gere um token de acesso e copie o comando completo apidog run que o Apidog cria com os IDs de cenário e ambiente já preenchidos. Em seguida, mova o token para um segredo de CI e referencie-o como $APIDOG_ACCESS_TOKEN.