DEV Community

Cover image for Como Rodar Testes de API com Apidog CLI no CircleCI
Lucas
Lucas

Posted on • Originally published at apidog.com

Como Rodar Testes de API com Apidog CLI no CircleCI

Para executar testes de API do Apidog CLI no CircleCI, crie .circleci/config.yml, use um executor Docker cimg/node, instale apidog-cli com npm e rode apidog run com token de acesso, ID do cenário de teste e ID do ambiente. Guarde esses valores como variáveis de ambiente no CircleCI e publique relatórios JUnit/HTML com store_test_results e store_artifacts.

Experimente o Apidog hoje

Este guia foca na execução dos testes no CircleCI. Se você ainda está escolhendo uma ferramenta de CI, veja a comparação entre CircleCI e Jenkins. Aqui, assumimos que o CircleCI já está conectado ao seu repositório e que você quer rodar sua suíte de API a cada push.

O que você vai configurar

O pipeline terá um job chamado api-tests que:

  1. Faz checkout do repositório.
  2. Instala o Apidog CLI.
  3. Executa um cenário de teste do Apidog.
  4. Gera relatórios no terminal, JUnit e HTML.
  5. Publica os resultados no CircleCI.

A configuração fica em:

.circleci/config.yml
Enter fullscreen mode Exit fullscreen mode

O CircleCI lê esse arquivo a cada push e executa os jobs definidos nele.

Conceitos básicos do CircleCI

Uma configuração do CircleCI usa três blocos principais:

  • Jobs: unidades de trabalho, como instalar dependências e executar testes.
  • Executores: ambientes onde os jobs rodam. Neste guia, usamos Docker com cimg/node.
  • Workflows: definem quais jobs rodam e em qual ordem.

Para testes de API, a ideia é simples: criar um job que executa apidog run e um workflow que chama esse job.

Por que rodar testes de API no CircleCI

Rodar testes de API em CI ajuda a detectar problemas antes do deploy, como:

  • mudanças inesperadas no contrato da API;
  • campos removidos ou renomeados;
  • falhas em autenticação;
  • respostas com status code incorreto;
  • regressões em fluxos críticos.

O Apidog CLI permite executar no CI os mesmos cenários criados no Apidog, sem precisar reescrever asserções em um framework separado.

Se quiser aprofundar a estratégia de testes em pipelines, veja também as 12 melhores práticas de CI/CD para testes de API.

Pré-requisitos

Antes de configurar o CircleCI, tenha estes dados no Apidog:

  • Token de acesso: usado pelo CLI para autenticar a execução. Veja o guia de autenticação do Apidog CLI.
  • ID do cenário de teste: identifica qual cenário será executado.
  • ID do ambiente: define a URL base e as variáveis usadas na execução, como staging ou produção.

Você também precisa de:

  • uma conta CircleCI;
  • o projeto habilitado no painel do CircleCI;
  • um repositório Git com permissão para criar .circleci/config.yml.

Configure variáveis de ambiente no CircleCI

Não coloque tokens diretamente no config.yml. Esse arquivo fica versionado no Git.

No CircleCI, crie as seguintes variáveis:

APIDOG_ACCESS_TOKEN
APIDOG_TEST_SCENARIO_ID
APIDOG_ENVIRONMENT_ID
Enter fullscreen mode Exit fullscreen mode

Você pode adicioná-las de duas formas:

Opção 1: variáveis do projeto

Use quando o token será usado apenas por um repositório.

No CircleCI:

  1. Abra o projeto.
  2. Vá em Project Settings.
  3. Acesse Environment Variables.
  4. Adicione as três variáveis.

Opção 2: contextos

Use quando vários repositórios compartilham os mesmos segredos.

No CircleCI:

  1. Vá em Organization Settings.
  2. Abra Contexts.
  3. Crie um contexto, por exemplo apidog-secrets.
  4. Adicione as variáveis ao contexto.
  5. Referencie o contexto no workflow.

Configuração completa do .circleci/config.yml

Crie o arquivo abaixo em .circleci/config.yml:

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
Enter fullscreen mode Exit fullscreen mode

Depois:

git add .circleci/config.yml
git commit -m "Add Apidog API tests to CircleCI"
git push
Enter fullscreen mode Exit fullscreen mode

O CircleCI deve iniciar o pipeline automaticamente.

Entendendo o executor 

docker:
  - image: cimg/node:20.11
Enter fullscreen mode Exit fullscreen mode

cimg/node é uma imagem Docker mantida pelo CircleCI para projetos Node.js. Ela já inclui Node.js, npm e ferramentas comuns de build.

A tag 20.11 fixa a versão do Node. Se sua equipe usa outra versão, ajuste a tag:

docker:
  - image: cimg/node:18.19
Enter fullscreen mode Exit fullscreen mode

Entendendo as etapas do job

Checkout do código 

- checkout
Enter fullscreen mode Exit fullscreen mode

Baixa o repositório para o ambiente do job.

Instalação do Apidog CLI 

- run:
    name: Install Apidog CLI
    command: npm install -g apidog-cli
Enter fullscreen mode Exit fullscreen mode

Instala o CLI globalmente no contêiner.

Execução dos testes 

apidog run \
  --access-token $APIDOG_ACCESS_TOKEN \
  -t $APIDOG_TEST_SCENARIO_ID \
  -e $APIDOG_ENVIRONMENT_ID \
  -r cli,junit,html \
  --out-dir ./reports
Enter fullscreen mode Exit fullscreen mode

Flags usadas:

  • --access-token: autentica o CLI.
  • -t: define o ID do cenário de teste.
  • -e: define o ID do ambiente.
  • -r: define os reporters.
  • --out-dir: define onde os relatórios serão gravados.

Neste exemplo, usamos três reporters:

cli,junit,html
Enter fullscreen mode Exit fullscreen mode

Eles geram:

  • saída no log do CircleCI;
  • relatório JUnit para a aba de testes;
  • relatório HTML para download como artifact.

Publicando relatórios no CircleCI 

- store_test_results:
    path: ./reports

- store_artifacts:
    path: ./reports
Enter fullscreen mode Exit fullscreen mode

store_test_results envia os arquivos JUnit para o CircleCI. Assim, o build mostra uma aba de testes com falhas, nomes dos casos e duração.

store_artifacts publica os arquivos gerados em ./reports, incluindo o relatório HTML.

Para entender melhor os formatos de saída, consulte o guia de relatórios de teste do Apidog CLI.

Rodar testes apenas em branches específicas

Se você não quiser executar a suíte de API em todas as branches, adicione filtros no workflow:

workflows:
  test-api:
    jobs:
      - api-tests:
          filters:
            branches:
              only:
                - main
                - develop
Enter fullscreen mode Exit fullscreen mode

Com isso, o job api-tests roda apenas em pushes para main e develop.

Usar um contexto do CircleCI

Se você criou um contexto chamado apidog-secrets, referencie-o assim:

workflows:
  test-api:
    jobs:
      - api-tests:
          context:
            - apidog-secrets
Enter fullscreen mode Exit fullscreen mode

O job passa a acessar as variáveis definidas no contexto, como:

APIDOG_ACCESS_TOKEN
APIDOG_TEST_SCENARIO_ID
APIDOG_ENVIRONMENT_ID
Enter fullscreen mode Exit fullscreen mode

Isso facilita rotação de tokens e compartilhamento entre projetos.

Execuções orientadas a dados

Para rodar o mesmo cenário com múltiplos dados de entrada, use -d:

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
Enter fullscreen mode Exit fullscreen mode

A flag -d aceita um arquivo CSV ou JSON, ou um ID numérico de conjunto de dados armazenado.

Exemplo com CSV:

email,password
user1@example.com,secret123
user2@example.com,secret456
Enter fullscreen mode Exit fullscreen mode

Veja mais no guia de testes orientados a dados.

Controlar comportamento em falhas

Você pode ajustar o comportamento da execução com --on-error.

Exemplo:

apidog run \
  --access-token $APIDOG_ACCESS_TOKEN \
  -t $APIDOG_TEST_SCENARIO_ID \
  -e $APIDOG_ENVIRONMENT_ID \
  --on-error end \
  -r cli,junit,html \
  --out-dir ./reports
Enter fullscreen mode Exit fullscreen mode

Valores aceitos:

  • continue: continua mesmo após erro.
  • end: encerra ao encontrar erro.
  • ignore: ignora erros na execução.

Use end quando quiser falhar rápido em fluxos críticos.

Executar testes de uma branch do Apidog

Se seu projeto usa branches no Apidog, informe o projeto e a branch:

apidog run \
  --access-token $APIDOG_ACCESS_TOKEN \
  --project $APIDOG_PROJECT_ID \
  --branch feature-auth \
  -t $APIDOG_TEST_SCENARIO_ID \
  -e $APIDOG_ENVIRONMENT_ID \
  -r cli,junit,html \
  --out-dir ./reports
Enter fullscreen mode Exit fullscreen mode

Nesse caso, adicione também a variável:

APIDOG_PROJECT_ID
Enter fullscreen mode Exit fullscreen mode

Enviar relatório para a nuvem do Apidog

Para enviar uma visão geral do relatório para o Apidog, adicione:

--upload-report
Enter fullscreen mode Exit fullscreen mode

Exemplo:

apidog run \
  --access-token $APIDOG_ACCESS_TOKEN \
  -t $APIDOG_TEST_SCENARIO_ID \
  -e $APIDOG_ENVIRONMENT_ID \
  -r cli,junit,html \
  --out-dir ./reports \
  --upload-report
Enter fullscreen mode Exit fullscreen mode

Como isso se encaixa no fluxo do Apidog

O fluxo recomendado é:

  1. Criar ou editar o cenário no Apidog.
  2. Definir asserções de status code, headers e corpo da resposta.
  3. Salvar o cenário.
  4. Rodar o mesmo cenário no CircleCI com apidog run.

Você pode criar um cenário de teste a partir da linha de comando ou usar o construtor visual do Apidog.

A configuração de CI fica estável. Quando alguém altera asserções no Apidog, o próximo build do CircleCI executa a versão atualizada do cenário.

A divisão fica clara:

  • Apidog define o que testar.
  • CircleCI define quando e onde executar.

Se quiser comparar alternativas de CI para equipes de API, veja o resumo de ferramentas de integração contínua para equipes de API.

Checklist de implementação

Antes de finalizar, confirme:

  • [ ] .circleci/config.yml existe na raiz do repositório.
  • [ ] APIDOG_ACCESS_TOKEN está configurado no CircleCI.
  • [ ] APIDOG_TEST_SCENARIO_ID está configurado.
  • [ ] APIDOG_ENVIRONMENT_ID está configurado.
  • [ ] O comando apidog run usa -r cli,junit,html.
  • [ ] store_test_results aponta para ./reports.
  • [ ] store_artifacts aponta para ./reports.
  • [ ] O pipeline roda ao fazer push.

Pronto para colocar sua suíte de API em cada push? Baixe o Apidog, crie um cenário de teste e adicione a configuração acima ao 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ê .circleci/config.yml e executa automaticamente etapas de build, teste e deploy a cada push.

Para que é usado o CircleCI?

Equipes usam CircleCI para automatizar tarefas como:

  • compilar código;
  • executar testes unitários;
  • executar testes de integração;
  • validar contratos de API;
  • construir imagens Docker;
  • publicar releases em staging ou produção.

Neste guia, o CircleCI executa testes de API do Apidog CLI.

O CircleCI é gratuito?

O CircleCI possui um plano gratuito com uma alocação mensal de créditos de build, útil para pequenos projetos e repositórios pessoais. Equipes que precisam de mais concorrência, minutos ou máquinas maiores podem usar planos pagos. Consulte a página de preços atual do CircleCI para limites exatos.

O CircleCI é de código aberto?

Não. CircleCI é um produto comercial hospedado. Você o configura com YAML e pode executá-lo na infraestrutura do CircleCI ou em runners auto-hospedados.

Se você precisa de um servidor CI totalmente open source, Jenkins é uma alternativa comum. A comparação CircleCI vs Jenkins aborda esse cenário.

Como funciona o CircleCI?

Quando você faz um commit, o CircleCI detecta a mudança, lê .circleci/config.yml e inicia o executor definido, como um contêiner Docker cimg/node.

Depois, ele executa as etapas dos jobs em ordem e envia o resultado para o provedor Git. Workflows permitem encadear e paralelizar jobs.

Para uma visão mais ampla de pipelines de entrega, consulte o guia O que é CI/CD.

Top comments (0)