Para executar testes de API do Apidog CLI no CircleCI, adicione um arquivo .circleci/config.yml que usa um executor Docker cimg/node, instala apidog-cli com npm e executa apidog run com seu token de acesso, ID do cenário de teste e ID do ambiente. Armazene o token e os IDs como variáveis de ambiente do CircleCI e, em seguida, publique os relatórios JUnit e HTML com store_test_results e store_artifacts. Este guia detalha cada parte para que você possa copiar, colar e lançar.
Este artigo trata da execução de testes, não da escolha de uma plataforma de CI. Se você ainda está decidindo entre ferramentas, a comparação entre CircleCI e Jenkins cobre esse terreno. Aqui, assumimos que você já escolheu o CircleCI e deseja que sua suíte de API seja executada a cada push.
O que é CircleCI e como funciona
CircleCI é um serviço de integração e entrega contínua baseado em nuvem. Ele monitora seu repositório Git e, quando você faz um commit, executa as etapas de build, teste e deploy que você definiu. Você descreve essas etapas em um único arquivo YAML, para que seu pipeline viva no controle de versão junto com seu código.
Tudo começa com .circleci/config.yml na raiz do seu repositório. O CircleCI lê este arquivo a cada push e o transforma em um pipeline. O formato de configuração atual é a versão 2.1, que adiciona blocos de construção reutilizáveis como orbs, comandos e parâmetros em cima do motor base 2.0.
Uma configuração do CircleCI possui três conceitos centrais:
- Jobs são unidades de trabalho. Cada job executa uma série de etapas, como verificar o código, instalar dependências ou executar um comando de teste.
- Executores definem onde um job é executado. Um executor Docker executa suas etapas dentro de uma imagem de contêiner que você escolhe, como
cimg/nodepara projetos Node.js. - Workflows orquestram jobs. Um workflow decide quais jobs são executados, em que ordem e se são executados em paralelo ou em sequência.
Essa separação é importante para o teste de API. Você define um job que instala o Apidog CLI e executa seus cenários, e então um workflow que o aciona nas branches que você deseja.
Por que executar testes de API no CircleCI
Executar sua suíte de API em CI detecta quebras de contrato antes que elas cheguem à produção. Uma mudança de esquema, um campo renomeado ou um fluxo de autenticação quebrado aparece como um build vermelho em vez de um ticket de suporte.
O Apidog CLI foi criado exatamente para isso. Você projeta e depura um cenário de teste no aplicativo Apidog e, em seguida, executa esse mesmo cenário sem interface gráfica no CI com um único comando. Sem reescrever asserções em código e sem um harness de teste separado para manter.
Se você deseja uma visão mais ampla de como as verificações automatizadas se encaixam em um pipeline, o guia 12 melhores práticas de CI/CD para testes de API é uma boa leitura complementar.
Pré-requisitos
Antes de escrever a configuração, prepare o seguinte no aplicativo Apidog:
- Um token de acesso. Gere-o nas configurações da sua conta Apidog. Isso autentica o CLI em ambientes sem interface gráfica. O guia de autenticação do Apidog CLI aborda a criação de token e o tratamento de segredos de CI em detalhes.
- Um ID de cenário de teste. Abra o cenário de teste que você deseja executar e copie seu ID do URL ou das configurações do cenário.
- Um ID de ambiente. Isso informa ao CLI qual URL base e quais variáveis usar, como staging ou produção.
Você também precisará de uma conta CircleCI conectada ao seu provedor Git, com o projeto habilitado no painel do CircleCI.
Armazenar segredos como variáveis de ambiente
Nunca codifique seu token de acesso em config.yml. O arquivo é commitado no Git, portanto, um token lá é um token vazado.
O CircleCI oferece duas opções seguras:
- Variáveis de ambiente do projeto. Na interface do CircleCI, abra Configurações do Projeto, depois Variáveis de Ambiente e adicione cada valor. Elas são criptografadas e expostas aos jobs como
$VARS. - Contextos. Um contexto é um grupo nomeado de variáveis de ambiente compartilhado entre projetos. Você o cria em Configurações da Organização, depois Contextos, e o referencia a partir de um workflow. Contextos são úteis quando vários repositórios compartilham o mesmo token Apidog.
Para este guia, adicione três variáveis: APIDOG_ACCESS_TOKEN, APIDOG_TEST_SCENARIO_ID e APIDOG_ENVIRONMENT_ID. O CLI as lê em tempo de execução, e nada sensível fica no seu repositório.
O config.yml completo
Aqui está uma configuração completa, que você pode copiar e colar. Coloque-a em .circleci/config.yml, defina suas três variáveis de ambiente e faça o push.
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 Apidog API tests
command: |
apidog run \
--access-token $APIDOG_ACCESS_TOKEN \
-t $APIDOG_TEST_SCENARIO_ID \
-e $APIDOG_ENVIRONMENT_ID \
-r cli,junit,html \
--out-dir ./reports
- store_test_results:
path: ./reports
- store_artifacts:
path: ./reports
workflows:
test-api:
jobs:
- api-tests
Vou detalhar o que cada parte faz.
O executor
docker:
- image: cimg/node:20.11
cimg/node é a imagem de conveniência do CircleCI para Node.js. Ela vem com Node, npm e ferramentas de build comuns pré-instalados, então npm install -g apidog-cli funciona sem configuração extra. A tag :20.11 fixa uma versão do Node; fixe na versão que sua equipe padroniza.
As etapas
checkout puxa seu repositório para o diretório de trabalho do job. A primeira etapa run instala o CLI globalmente. A segunda etapa run executa seus testes.
Observe o comando de teste de perto:
apidog run \
--access-token $APIDOG_ACCESS_TOKEN \
-t $APIDOG_TEST_SCENARIO_ID \
-e $APIDOG_ENVIRONMENT_ID \
-r cli,junit,html \
--out-dir ./reports
Cada flag faz uma coisa:
--access-tokenautentica a execução. Não possui forma abreviada.-tseleciona o cenário de teste pelo ID.-eseleciona o ambiente. Esta flag é obrigatória; o CLI precisa saber qual URL base e variáveis usar.-rdefine os reporters. Aqui você solicita três:cliimprime resultados ao vivo no log do build,junitescreve XML legível por máquina ehtmlescreve um relatório navegável.--out-dirinforma ao CLI onde gravar os arquivos de relatório.
Publicando os relatórios
- store_test_results:
path: ./reports
- store_artifacts:
path: ./reports
store_test_results aponta o CircleCI para o JUnit XML em ./reports. O CircleCI o analisa e mostra uma aba de Testes no build, de modo que as falhas são listadas por nome com dados de tempo. Isso transforma uma parede de texto de log em uma visão estruturada de aprovação/reprovação.
store_artifacts carrega o mesmo diretório como arquivos para download, incluindo o relatório HTML. Após um build, você abre a aba de Artifacts e visualiza o relatório renderizado no seu navegador. O guia de relatórios de teste do Apidog CLI explica os formatos CLI, HTML e JSON com mais profundidade.
O workflow
workflows:
test-api:
jobs:
- api-tests
Este workflow executa o job api-tests a cada push. Você pode adicionar filtros para restringi-lo a certas branches, ou adicionar outros jobs que são executados antes ou depois dele. Para um único job de teste, este bloco mínimo é tudo o que você precisa.
Executar testes apenas na branch principal
Você pode não querer uma execução completa da API em cada branch de funcionalidade. Adicione um filtro de branch ao workflow:
workflows:
test-api:
jobs:
- api-tests:
filters:
branches:
only:
- main
- develop
Agora o job é executado apenas em pushes para main e develop. Outras branches o ignoram, o que mantém seus minutos de build focados nas branches que serão lançadas.
Usar um Contexto em vez de variáveis de projeto
Se vários repositórios compartilham um token Apidog, um Contexto o mantém em um só lugar. Crie o Contexto nas Configurações da Organização, adicione suas variáveis lá e, em seguida, referencie-o:
workflows:
test-api:
jobs:
- api-tests:
context:
- apidog-secrets
O job agora lê APIDOG_ACCESS_TOKEN e o restante do Contexto apidog-secrets. Gire o token uma vez, e cada projeto pegará o novo valor.
Execuções orientadas a dados e outras opções
O CLI possui mais flags do que as usadas neste guia. Duas delas valem a pena conhecer para CI.
Você pode repetir um cenário em linhas de dados de teste com -d e -n:
apidog run \
--access-token $APIDOG_ACCESS_TOKEN \
-t $APIDOG_TEST_SCENARIO_ID \
-e $APIDOG_ENVIRONMENT_ID \
-d ./data/users.csv \
-r cli,junit \
--out-dir ./reports
A flag -d recebe um caminho de arquivo CSV ou JSON, ou um ID numérico de conjunto de dados armazenados, e executa o cenário uma vez por linha. O guia de testes orientados a dados mostra como estruturar esses arquivos.
Você também pode controlar como a execução lida com falhas com --on-error, que aceita continue, end ou ignore. E para projetos que usam branches do Apidog, --project <id> --branch <name> direciona uma branch específica. Para enviar uma visão geral do relatório para a nuvem Apidog, adicione --upload-report como uma flag simples.
Como isso se encaixa no fluxo de trabalho do Apidog
O objetivo do Apidog CLI é que você não escreva nem mantenha código de teste. Você constrói um cenário de teste a partir da linha de comando ou no construtor de teste visual, define asserções em códigos de status e corpos de resposta e o salva. O CI então executa esse cenário exato.
Como o cenário vive no seu projeto Apidog, sua equipe edita testes em um só lugar. A configuração de CI raramente muda; ela apenas chama apidog run. Quando alguém adiciona uma asserção no aplicativo, o próximo build do CircleCI a capta sem uma edição no YAML.
Isso mantém uma divisão limpa. O Apidog é responsável pelo que é testado. O CircleCI é responsável por quando e onde é executado. Se você quiser comparar o CircleCI com outros runners para este tipo de trabalho, o resumo das ferramentas de integração contínua para equipes de API expõe as vantagens e desvantagens.
Pronto para colocar sua suíte de API em cada push? Baixe o Apidog, crie um cenário de teste e insira a configuração acima em seu repositório.
Perguntas Frequentes
O que é CircleCI?
CircleCI é uma plataforma de integração e entrega contínua em nuvem. Ela se conecta ao seu repositório Git, lê um arquivo .circleci/config.yml e executa automaticamente as etapas de build, teste e deploy toda vez que você faz um push de código. Isso elimina a necessidade de executar essas etapas manualmente em sua própria máquina.
Para que é usado o CircleCI?
As equipes usam o CircleCI para automatizar testes e deployments. As tarefas comuns incluem compilar código, executar testes unitários e de integração, verificar contratos de API, construir imagens Docker e enviar releases para staging ou produção. Neste guia, o job executa testes de API do Apidog CLI a cada push.
O CircleCI é gratuito?
O CircleCI possui um plano gratuito que inclui uma alocação mensal de créditos de build, o que é suficiente para pequenos projetos e repositórios pessoais. Equipes maiores que precisam de mais concorrência, mais minutos de build ou máquinas maiores migram para planos pagos Performance e Scale. Verifique a página de preços atual do CircleCI para limites exatos.
O CircleCI é de código aberto?
Não, o CircleCI é um produto comercial hospedado, não de código aberto. Você o configura por meio de um arquivo YAML e o executa na infraestrutura do CircleCI ou em um runner auto-hospedado. Se você precisa de um servidor CI totalmente de código aberto, o Jenkins é a alternativa comum, que a comparação CircleCI vs Jenkins discute.
Como funciona o CircleCI?
Quando você faz um commit, o CircleCI detecta a mudança, lê .circleci/config.yml e inicializa o executor que você definiu, como um contêiner Docker cimg/node. Ele executa cada etapa em seus jobs em ordem e, em seguida, relata os resultados ao seu provedor Git. Workflows permitem encadear e paralelizar jobs. Para uma visão mais ampla de como isso se encaixa em um pipeline de entrega, consulte o guia O que é CI/CD.