Seus testes de API passam na sua máquina. Então um colega de equipe mescla uma alteração que quebra o endpoint de login, e ninguém percebe até que um cliente abra um ticket. Os testes existiam. Eles simplesmente nunca rodaram no momento em que importavam: na pull request, antes da mesclagem.
Essa lacuna é o que a integração contínua fecha. Você move os testes do seu terminal local para um pipeline que os executa automaticamente, a cada push, contra cada alteração. Para testes de API especificamente, a maneira mais limpa de fazer isso é com um executor de linha de comando que executa os cenários exatos que você já construiu, retorna um código de saída de sucesso/falha e deixa o CI decidir se a build fica verde ou vermelha.
botão
Em Resumo
- O Apidog CLI é um pacote npm, `apidog-cli`. Instale-o em uma etapa de fluxo de trabalho com `npm install -g apidog-cli`, então execute cenários com `apidog run`.
- Ele executa os cenários de teste que você projeta no aplicativo Apidog por ID. Você não porta testes para código; o CLI executa o mesmo cenário usando um token de acesso para autenticação.
- Um trabalho mínimo do GitHub Actions tem quatro etapas: checkout, configurar Node, instalar o CLI, executar `apidog run --access-token "$APIDOG_ACCESS_TOKEN" -t <scenarioId> -e <environmentId> -r junit,cli`.
- O CLI sai com código diferente de zero quando qualquer asserção falha. O GitHub lê esse código de saída, falha a verificação e bloqueia a mesclagem. Essa é a porta de qualidade; você não configura nada extra.
- Armazene o token de acesso como um segredo do GitHub Actions e passe-o através de `env:`. Nunca o comite.
- Use `-r junit` para alimentar os resultados em um dashboard, `-r html` para um artefato navegável, e `if: always()` na etapa de upload para que você ainda receba o relatório quando os testes falharem.
Por que executar testes de API em CI?
Um teste que só roda quando você lembra de executá-lo é um teste em que você não pode confiar. Execuções locais são boas enquanto você está escrevendo o cenário. Elas se desintegram no momento em que uma equipe está envolvida, porque a máquina de cada desenvolvedor é ligeiramente diferente e ninguém executa o pacote completo antes de cada push.
O CI corrige o problema de confiança tornando a execução automática e uniforme. Cada pull request aciona o mesmo trabalho, no mesmo executor limpo, contra o mesmo ambiente. Quando um endpoint começa a retornar um 500 ou um esquema de resposta muda, a verificação falha na PR que o causou, com o nome da pessoa que o enviou anexado. O feedback chega em minutos, enquanto a alteração ainda está fresca, em vez de dias depois em produção.
Os testes de API se encaixam perfeitamente nisso porque são rápidos e determinísticos. Um cenário atinge endpoints reais, faz asserções sobre códigos de status e corpos de resposta, e passa ou falha. Não há navegador instável, nem renderização para esperar. Isso os torna ideais como uma porta de mesclagem: rápidos o suficiente para rodar em cada PR, decisivos o suficiente para bloquear uma ruim. Se você quer o contexto mais amplo sobre o que é CI/CD e como as peças se encaixam, o guia sobre o que é CI/CD e como funciona aborda os fundamentos.
O que o Apidog CLI realmente faz
Aqui está a parte que mais economiza seu tempo: você não escreve código de teste para o CLI.
Você constrói seus cenários de teste visualmente no aplicativo Apidog, com as requisições, asserções, variáveis de ambiente e dados de que precisa. O CLI é um executor. Dado um ID de cenário e um token de acesso, ele busca esse cenário do seu projeto Apidog e o executa, requisição por requisição, avaliando cada asserção exatamente como o aplicativo faria. O resultado é um relatório e um código de saída.
Esse design importa para o CI. A maioria dos executores de teste pede que você mantenha uma representação de código separada de seus testes; o que você executa no pipeline se desvia do que você projetou. Com o Apidog, o pipeline executa o mesmo cenário que sua equipe já mantém no aplicativo. Atualize uma asserção no editor visual e a próxima execução do CI a incorpora. Não há segunda cópia para manter sincronizada.
O binário é `apidog`, distribuído como o pacote npm `apidog-cli`. Cada comando começa com `apidog run`. Se você quiser ver o executor integrado em um fluxo de trabalho de automação mais completo, o passo a passo sobre integrando o Apidog CLI com Claude Skills para automação de testes de API aborda esse ângulo; este artigo se concentra nos parâmetros que você precisa para um pipeline do GitHub Actions.
Antes de começar: três coisas que você precisa
Você precisa de três informações antes que o fluxo de trabalho seja executado. Duas são IDs do seu projeto Apidog; uma é um token.
- Um cenário de teste. Construa-o no aplicativo Apidog, se ainda não o fez. É isso que o CLI executa. Um único cenário de login e busca de perfil é suficiente para começar; você pode escalar mais tarde.
- O ID do cenário e o ID do ambiente. O ID do cenário informa ao CLI o que executar; o ID do ambiente informa onde (desenvolvimento, staging, produção). Ambos são visíveis no aplicativo.
- Um token de acesso. Isso autentica o CLI na sua conta Apidog para que ele possa buscar e executar o cenário.
A maneira mais limpa de obter tudo isso de uma vez é na guia CI/CD do cenário. Abra o cenário de teste que você deseja automatizar, mude para a guia CI/CD e escolha a opção de linha de comando. Clique para adicionar um token de acesso e gerar um. O Apidog monta o comando `apidog run` completo para você, com o token de acesso, o ID do cenário (`-t`) e o ID do ambiente (`-e`) já preenchidos. Copie esse comando; ele é a base para sua etapa de CI.
Uma regra que vale a pena declarar de antemão: trate o token de acesso como uma senha. Não o cole em um arquivo de fluxo de trabalho comitado. Armazene-o como um segredo do GitHub Actions e referencie-o como uma variável de ambiente. Cada exemplo abaixo usa `$APIDOG_ACCESS_TOKEN` exatamente por essa razão.
Passo 1: armazene o token de acesso como um segredo do GitHub
Abra seu repositório no GitHub. Vá para Configurações (Settings), então Segredos e variáveis (Secrets and variables), então Ações (Actions), e clique em Novo segredo do repositório (New repository secret).
- Nome: `APIDOG_ACCESS_TOKEN`
- Segredo: cole o token que o Apidog gerou para você
Salve-o. O token agora está criptografado em repouso e exposto apenas a execuções de fluxo de trabalho, nunca impresso em logs. No fluxo de trabalho, você o referenciará como `${{ secrets.APIDOG_ACCESS_TOKEN }}` e o passará para o CLI através de um bloco `env:`. O ID do cenário e o ID do ambiente não são segredos; são IDs inofensivos, então você pode escrevê-los diretamente no arquivo do fluxo de trabalho. Apenas o token precisa de proteção.
Se sua equipe trabalha em vários repositórios que acessam o mesmo projeto Apidog, defina o segredo uma vez no nível da organização e conceda acesso aos repositórios relevantes. Mesmo nome, um único lugar para rotacioná-lo.
Passo 2: o fluxo de trabalho mínimo
Crie `.github/workflows/api-tests.yml` em seu repositório. Este é o menor fluxo de trabalho que faz algo útil: ele executa seu cenário em cada pull request direcionada para `main`.
name: Testes de API
on:
pull_request:
branches: [main]
jobs:
api-tests:
runs-on: ubuntu-latest
steps:
- name: Checkout
uses: actions/checkout@v4
- name: Configurar Node.js
uses: actions/setup-node@v4
with:
node-version: '20'
- name: Instalar Apidog CLI
run: npm install -g apidog-cli
- name: Executar cenário de teste de API
run: |
apidog run \
--access-token "$APIDOG_ACCESS_TOKEN" \
-t 605067 \
-e 1629989 \
-r cli
env:
APIDOG_ACCESS_TOKEN: ${{ secrets.APIDOG_ACCESS_TOKEN }}
Substitua `605067` pelo ID do seu cenário e `1629989` pelo ID do seu ambiente. Comite este arquivo, abra uma pull request e observe a guia Checks. O trabalho inicia um executor Ubuntu, instala o Node 20, instala o CLI e executa seu cenário. Se todas as asserções passarem, a verificação fica verde. Se uma falhar, `apidog run` sai com código diferente de zero, o GitHub falha a verificação e a PR mostra um X vermelho.
Esse X vermelho é o ponto principal. Ninguém precisa ler um log para saber que algo quebrou; a verificação com falha está ali na pull request.
Uma nota sobre a etapa de instalação: o `npm install -g apidog-cli` global é simples e funciona. Se você preferir não alterar os pacotes globais do executor, pode pular a etapa de instalação e chamar o CLI através de `npx` em vez disso:
- name: Executar cenário de teste de API
run: npx apidog-cli run --access-token "$APIDOG_ACCESS_TOKEN" -t 605067 -e 1629989 -r cli
env:
APIDOG_ACCESS_TOKEN: ${{ secrets.APIDOG_ACCESS_TOKEN }}
Ambas as abordagens executam o mesmo cenário. `npx` é mais limpo em executores efêmeros; a instalação global é marginalmente mais rápida quando você armazena em cache `node_modules` entre as execuções. Escolha o que melhor se adapta ao seu estilo.
Passo 3: publique um relatório que você possa realmente ler
Uma verificação verde ou vermelha informa o resultado. Quando um teste falha, você quer saber por quê, e para isso você quer o relatório.
O parâmetro `-r` (ou `--reporters`) controla os formatos de relatório. Ele aceita `cli`, `html`, `json` e `junit`, separados por vírgula. Para CI, dois formatos são essenciais:
- `junit` emite XML no formato padrão JUnit. Quase todos os dashboards de CI e ferramentas de relatório de teste sabem como analisá-lo em uma árvore de sucesso/falha.
- `html` produz um relatório autocontido que você pode salvar como um artefato de build e abrir em um navegador, com a requisição completa e a resposta para cada etapa.
Mantenha `cli` também se você quiser uma saída legível no próprio log da build. Aqui está a etapa de execução atualizada para produzir ambos os formatos de relatório e gravá-los em um diretório, além de uma etapa de upload para que o relatório sobreviva à execução:
- name: Executar cenário de teste de API
run: |
apidog run \
--access-token "$APIDOG_ACCESS_TOKEN" \
-t 605067 \
-e 1629989 \
-n 1 \
-r html,junit,cli \
--out-dir ./apidog-reports
env:
APIDOG_ACCESS_TOKEN: ${{ secrets.APIDOG_ACCESS_TOKEN }}
- name: Carregar relatório de teste
if: always()
uses: actions/upload-artifact@v4
with:
name: apidog-report
path: ./apidog-reports
Dois detalhes fazem isso funcionar como você deseja. O parâmetro `--out-dir` informa ao CLI onde escrever os relatórios; aqui é `./apidog-reports`, que a etapa de upload então captura. E `if: always()` na etapa de upload é o importante: por padrão, o GitHub pula as etapas posteriores assim que uma etapa falha, mas você precisa do relatório principalmente quando os testes falharam. `if: always()` força o upload a ser executado independentemente do resultado do teste. Após a conclusão do trabalho, o relatório aparece em Artefatos na página de resumo da execução, pronto para download.
A flag `-n 1` define a contagem de iterações para uma execução; aumente-a se quiser que o cenário seja executado várias vezes seguidas.
Se você quiser que o GitHub exiba os resultados do JUnit em linha como uma verificação anotada em vez de um arquivo para download, adicione uma ação de `published-test-results` após a etapa de execução e aponte-a para `./apidog-reports/*.xml`. Isso transforma o XML em um resumo de aprovação/falha anexado à execução, o que é útil para conjuntos maiores onde rolar o log não é prático.
Passo 4: teste o ambiente certo na hora certa
Uma pull request deve testar contra o ambiente de staging. Um deploy para produção deve ser verificado contra a produção. O mesmo cenário pode fazer ambos; você apenas altera o ID do ambiente com `-e`.
Uma configuração comum e durável usa dois gatilhos em um único arquivo de fluxo de trabalho. As pull requests executam o cenário contra seu ambiente de staging como um portão de mesclagem. Os pushes para `main` (que é o que uma mesclagem produz) executam o mesmo cenário contra a produção como um teste de fumaça pós-deploy.
name: Testes de API
on:
pull_request:
branches: [main]
push:
branches: [main]
jobs:
verificacao-pr:
if: github.event_name == 'pull_request'
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: actions/setup-node@v4
with:
node-version: '20'
- run: npm install -g apidog-cli
- name: Testar staging
run: |
apidog run \
--access-token "$APIDOG_ACCESS_TOKEN" \
-t 605067 \
-e 1629989 \
-r junit,cli \
--out-dir ./apidog-reports
env:
APIDOG_ACCESS_TOKEN: ${{ secrets.APIDOG_ACCESS_TOKEN }}
- uses: actions/upload-artifact@v4
if: always()
with:
name: staging-report
path: ./apidog-reports
smoke-test-producao:
if: github.event_name == 'push'
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: actions/setup-node@v4
with:
node-version: '20'
- run: npm install -g apidog-cli
- name: Smoke test de produção
run: |
apidog run \
--access-token "$APIDOG_ACCESS_TOKEN" \
-t 605067 \
-e 1730055 \
-r cli \
--on-error end
env:
APIDOG_ACCESS_TOKEN: ${{ secrets.APIDOG_ACCESS_TOKEN }}
Os dois IDs de ambiente (`1629989` para staging, `1730055` para produção) são a única diferença significativa. O trabalho da PR constrói e arquiva um relatório JUnit para que os revisores possam inspecionar as falhas; o teste de fumaça de produção executa de forma enxuta e falha rapidamente com `--on-error end`, que para na primeira asserção quebrada para que você descubra rapidamente que um deploy deu errado.
`--on-error` vale a pena conhecer. Ele controla o que acontece quando uma etapa falha no meio do cenário. `end` para a execução na primeira falha (feedback rápido, bom para testes de fumaça). `continue` executa todas as etapas restantes para que você veja todas as falhas em um único relatório (bom para uma verificação de PR completa). `ignore` pula uma etapa conhecida por ser instável sem descarrilar a execução. Seja qual for a sua escolha, a execução ainda termina com um código de saída diferente de zero se algo falhou, então o portão se mantém de qualquer maneira.
Indo além: execuções em matriz, pastas e testes orientados a dados
Uma vez que o portão básico esteja no lugar, algumas flags o estendem sem muito YAML extra.
Execute uma área de funcionalidade inteira, não apenas um cenário. Troque `-t <scenarioId>` por `-f <folderId>` para executar todos os cenários dentro de uma pasta, ou `--test-suite <testSuiteId>` para executar um conjunto de testes selecionado. Os conjuntos de testes são a ferramenta certa quando você deseja um conjunto específico e ordenado de cenários executados juntos como um único trabalho lógico; o guia sobre escalando testes automatizados de API com suites de teste aborda quando usá-los.
Teste vários ambientes em paralelo. Uma matriz executa o mesmo trabalho em vários IDs de ambiente ao mesmo tempo:
jobs:
api-tests:
runs-on: ubuntu-latest
strategy:
matrix:
env-id: [1629989, 1730055]
steps:
- uses: actions/checkout@v4
- uses: actions/setup-node@v4
with:
node-version: '20'
- run: npm install -g apidog-cli
- name: Executar cenário contra ${{ matrix.env-id }}
run: |
apidog run \
--access-token "$APIDOG_ACCESS_TOKEN" \
-t 605067 \
-e ${{ matrix.env-id }} \
-r cli
env:
APIDOG_ACCESS_TOKEN: ${{ secrets.APIDOG_ACCESS_TOKEN }}
O GitHub inicia um executor por valor da matriz, então staging e produção são testados concorrentemente e cada um relata seu próprio sucesso/falha.
Impulsione iterações a partir de um arquivo de dados. A flag `-d` executa um cenário através das linhas de um arquivo CSV ou JSON, tratando cada linha como uma passagem separada: `apidog run --access-token "$APIDOG_ACCESS_TOKEN" -t 605067 -d ./test-data.csv -r junit`. É assim que você valida o mesmo endpoint contra cinquenta entradas sem construir cinquenta cenários.
Execute contra um branch. Se sua equipe usa o recurso de branch do Apidog, `--branch <branchName>` aponta a execução para um branch específico em vez de `main`, o que permite que a PR de um branch de funcionalidade teste contra as definições de cenário desse branch.
Solucionando problemas comuns de falhas de CI
- **O trabalho está verde, mas um teste deveria ter falhado.** Verifique se o código de saída da etapa `apidog run` está realmente chegando ao GitHub. Se você envolveu o comando em um pipeline de shell ou anexou `|| true`, a saída diferente de zero é engolida e o portão para de funcionar silenciosamente. Remova qualquer coisa que mascare o código de saída. Execute o comando em sua própria linha, ou como o último comando em um bloco `run:`, para que seu status de saída seja o status de saída da etapa.
- **A autenticação falha.** A causa mais comum é o nome do segredo não corresponder. A chave `env:`, a referência de valor `${{ secrets.APIDOG_ACCESS_TOKEN }}`, e o segredo que você criou em Configurações devem usar o mesmo nome. Confirme também que o token não foi regenerado no Apidog desde que você o salvou; regenerar invalida o antigo.
- **Passa localmente, falha no CI.** Adicione `--verbose` ao comando de execução temporariamente. Ele imprime a requisição completa que o executor enviou e a resposta completa que ele recebeu, o que geralmente revela a diferença, muitas vezes uma variável de ambiente que está configurada na sua máquina, mas não no ambiente de CI, ou um serviço de staging se comportando de forma diferente do seu local.
- **Os relatórios não estão aparecendo como artefatos.** Certifique-se de que `--out-dir` na etapa de execução e `path:` na etapa de upload apontem para o mesmo diretório, e que a etapa de upload tenha `if: always()`. Sem `if: always()`, um teste com falha ignora o upload e você perde o relatório exatamente quando precisa dele.
- **O executor não consegue acessar sua API.** Se seu ambiente de staging ou produção estiver atrás de um firewall ou VPN, um executor público hospedado no GitHub não conseguirá alcançá-lo. Você precisará de um executor auto-hospedado dentro de sua rede, ou uma entrada de lista de permissões para os intervalos de IP do GitHub.
Como isso se compara às alternativas
Você poderia escrever testes de API como código com um framework, integrá-los a um executor de testes e chamá-los a partir do Actions. Isso funciona, mas agora você está mantendo um conjunto de código que precisa permanecer sincronizado com a API e com o que sua equipe projeta em sua ferramenta de API. A abordagem do Apidog pula essa duplicação: o cenário que sua equipe já mantém no aplicativo é o teste que roda no CI.
Você também poderia criar scripts de chamadas `curl` brutas em uma etapa de fluxo de trabalho. Ótimo para uma única verificação de saúde, doloroso depois disso, porque você está criando manualmente asserções, troca de ambiente e relatórios que o CLI oferece gratuitamente.
O GitHub Actions não é o único lugar para isso. O mesmo comando `apidog run` pode ser usado no GitLab CI, Jenkins, CircleCI ou qualquer executor que possa executar um comando de shell e ler um código de saída. Se o GitHub Actions não é sua plataforma, os padrões aqui são transferidos diretamente; veja o guia para automatizar testes de API em CI/CD para a visão multiplataforma, ou o passo a passo sobre integrar testes automatizados do Apidog com Jenkins se você usa Jenkins.
Para construir os cenários que você executará, baixe o Apidog, projete seus testes no aplicativo e pegue o comando CLI na guia CI/CD do cenário. O executor é um pacote npm gratuito; o que você pode executar depende do seu projeto Apidog, mas o próprio executor de linha de comando não é um produto pago separado.
Conclusão
A configuração é menor do que parece. Construa um cenário no Apidog, armazene um token de acesso como um segredo do GitHub e adicione algumas etapas a um arquivo de fluxo de trabalho. A partir daí, cada pull request executa seus testes de API automaticamente, um endpoint com falha deixa a verificação vermelha antes da mesclagem, e o relatório espera na guia de Artefatos sempre que você precisar ver o que quebrou.
A razão pela qual isso permanece simples é a divisão do trabalho. O aplicativo Apidog é responsável pelos testes; o CLI os executa; o GitHub lê o código de saída. Nada precisa ser duplicado ou mantido sincronizado. Quando você atualiza uma asserção no aplicativo, a próxima execução do CI a utiliza. É isso que torna a adoção valiosa no primeiro dia de um projeto, em vez de implementá-la após o primeiro incidente em produção.
botão