Como Rodar Testes de API do Apidog CLI no Drone CI

Você pode executar testes de API do Apidog CLI no Drone CI adicionando um passo Docker ao pipeline: use uma imagem Node, instale apidog-cli e rode apidog run. O token do Apidog deve ficar em um segredo do Drone e ser injetado com from_secret. Abaixo está um fluxo completo com .drone.yml, segredos, filtros por branch/evento e opções para expor relatórios.

Experimente o Apidog hoje

O que é o Drone CI e como funciona

Drone é uma plataforma CI/CD de código aberto, nativa de contêineres, agora parte da Harness. CI/CD significa integração contínua e entrega contínua: construir, testar e entregar código automaticamente a cada alteração. Para revisar o conceito, veja o que é CI/CD.

A principal diferença do Drone é que cada passo do pipeline roda dentro do seu próprio contêiner Docker. Em vez de depender de um agente compartilhado cheio de ferramentas pré-instaladas, você escolhe a imagem de cada passo e executa os comandos dentro dela. Isso torna o build mais reproduzível e fácil de depurar.

Você define o pipeline em um arquivo .drone.yml na raiz do repositório. Um pipeline Docker normalmente usa:

• kind
• type
• name
• steps

Exemplo mínimo:

kind: pipeline
type: docker
name: api-tests

steps:
  - name: greeting
    image: alpine
    commands:
      - echo hello
      - echo world

O Drone executa os commands como um script shell com comportamento equivalente a set -e e set -x: o build falha no primeiro código de saída diferente de zero e imprime cada comando antes de executá-lo. O diretório de trabalho é a raiz do repositório.

Por que executar testes de API em um passo de contêiner

Testes de API ajudam a evitar regressões de contrato. Uma mudança no backend que altera silenciosamente o formato da resposta, o código de status ou algum campo esperado pode quebrar clientes downstream.

Com o Apidog, você cria e mantém os testes visualmente no aplicativo e executa os mesmos cenários na CI com o Apidog CLI. Não é necessário duplicar a suíte em scripts separados. Para boas práticas de integração de testes de API em pipelines, leia boas práticas de CI/CD para testes de API.

Apidog é uma plataforma para design, depuração, teste, mocking e documentação de APIs. A CLI transforma os cenários salvos em um comando repetível, ideal para um passo do Drone.

Comando Apidog CLI usado no pipeline

Na CI, instale a CLI com npm e execute um cenário salvo no Apidog:

npm install -g apidog-cli
apidog run --access-token $APIDOG_ACCESS_TOKEN -t 1234567 -e 89012 -r cli

Flags principais:

• --access-token: token de acesso do Apidog. Não há forma abreviada.
• -t: ID do cenário de teste.
• -e: ID do ambiente. É obrigatório e define URL base e variáveis.
• -r: reporters. Valores válidos: cli, html, json e junit.

Flags úteis em CI:

• -n ou --iteration-count: repete a execução um número definido de vezes.
• -d ou --iteration-data: usa um arquivo CSV/JSON ou um ID de conjunto de dados armazenado para testes orientados por dados.
• --out-dir: define o diretório de saída dos relatórios.
• --upload-report: envia uma visão geral do relatório para a nuvem Apidog.
• --on-error: controla o comportamento em falhas com continue, end ou ignore.
• --project <id> e --branch <name>: direcionam uma branch específica do projeto.

Para a referência completa, consulte o guia completo do Apidog CLI e o passo a passo sobre como testar uma API REST pela linha de comando.

.drone.yml completo para testes Apidog

Use este pipeline como ponto de partida:

kind: pipeline
type: docker
name: apidog-api-tests

steps:
  - name: run-api-tests
    image: node:20-alpine
    environment:
      APIDOG_ACCESS_TOKEN:
        from_secret: apidog_access_token
    commands:
      - npm install -g apidog-cli
      - apidog run --access-token $APIDOG_ACCESS_TOKEN -t 1234567 -e 89012 -r cli

trigger:
  branch:
    - main
  event:
    - push
    - pull_request

Substitua:

• 1234567 pelo ID do seu cenário de teste.
• 89012 pelo ID do seu ambiente.

Com o reporter cli, o resultado aparece diretamente no log do build do Drone. Isso facilita a revisão de quais asserções passaram ou falharam sem depender de artefatos externos.

Armazenando segredos no Drone CI

Nunca coloque o token do Apidog diretamente no .drone.yml.

No Drone, você injeta segredos no bloco environment usando from_secret:

environment:
  APIDOG_ACCESS_TOKEN:
    from_secret: apidog_access_token

O valor apidog_access_token é o nome do segredo no Drone, não o token em si.

Opção 1: criar o segredo pela interface

No Drone:

1. Abra o repositório.
2. Vá para Settings.
3. Abra Secrets.
4. Crie um segredo chamado apidog_access_token.
5. Cole o token do Apidog como valor.

Opção 2: criar o segredo pela CLI

drone secret add \
  --repository sua-org/seu-repo \
  --name apidog_access_token \
  --data seu-token-apidog

Confirme os nomes das flags na documentação da CLI do Drone da sua versão, pois elas podem variar entre releases.

O Drone também suporta segredos criptografados no repositório com drone encrypt, gerando um documento YAML separado do tipo kind: secret. Para a maioria dos times, usar segredos do repositório pela interface ou por drone secret add é o caminho mais simples.

Para mais detalhes sobre credenciais na CLI, veja o guia de autenticação do Apidog CLI.

Controlando execuções por branch e evento

O Drone permite controlar quando o pipeline roda de duas formas:

• trigger: no nível do pipeline.
• when: no nível de um passo específico.

Usando trigger

O bloco trigger decide se o pipeline inteiro será executado. Todas as condições precisam ser verdadeiras.

trigger:
  branch:
    - main
  event:
    - push
    - pull_request

Esse exemplo roda apenas em push e pull_request para a branch main.

Usando when

Use when quando apenas um passo deve ser condicionado por branch ou evento:

steps:
  - name: run-api-tests
    image: node:20-alpine
    environment:
      APIDOG_ACCESS_TOKEN:
        from_secret: apidog_access_token
    commands:
      - npm install -g apidog-cli
      - apidog run --access-token $APIDOG_ACCESS_TOKEN -t 1234567 -e 89012 -r cli
    when:
      branch:
        - main
      event:
        - push

Isso é útil quando o pipeline roda em várias branches, mas os testes de API mais completos devem rodar apenas em main.

Eventos suportados incluem:

• push
• pull_request
• tag
• promote
• rollback
• cron
• custom

Os blocos também suportam padrões glob e subchaves de inclusão/exclusão.

Expondo relatórios de teste sem armazenamento nativo de artefatos

O Drone não possui hospedagem nativa de artefatos. Para relatórios do Apidog CLI, você tem duas opções práticas.

Opção 1: usar o reporter cli

Essa é a abordagem mais simples:

commands:
  - npm install -g apidog-cli
  - apidog run --access-token $APIDOG_ACCESS_TOKEN -t 1234567 -e 89012 -r cli

O resultado aparece no log do build, incluindo aprovações e falhas.

Opção 2: gerar HTML e enviar para S3

Se você precisa compartilhar um relatório HTML, gere o relatório com html e envie os arquivos para um storage externo. O Drone publica o plugin plugins/s3, que envia arquivos para S3 ou storage compatível.

kind: pipeline
type: docker
name: apidog-api-tests

steps:
  - name: run-api-tests
    image: node:20-alpine
    environment:
      APIDOG_ACCESS_TOKEN:
        from_secret: apidog_access_token
    commands:
      - npm install -g apidog-cli
      - apidog run --access-token $APIDOG_ACCESS_TOKEN -t 1234567 -e 89012 -r cli,html --out-dir reports

  - name: upload-report
    image: plugins/s3
    settings:
      bucket: meu-bucket
      region: us-east-1
      source: reports/**/*
      target: /apidog-reports
      access_key:
        from_secret: aws_access_key
      secret_key:
        from_secret: aws_secret_key

Notas importantes:

• source define quais arquivos serão enviados.
• target define o prefixo de destino no bucket.
• access_key e secret_key também devem vir de segredos do Drone.

Para entender o conteúdo dos relatórios, veja o guia de relatórios de teste do Apidog CLI.

Adicionando execuções orientadas por dados

Use -d quando o mesmo cenário precisa rodar com várias entradas: IDs de usuário, payloads, casos de borda ou combinações de parâmetros.

Exemplo usando CSV:

commands:
  - npm install -g apidog-cli
  - apidog run --access-token $APIDOG_ACCESS_TOKEN -t 1234567 -e 89012 -d ./data.csv -r cli

Cada linha de data.csv vira uma iteração. Os valores das colunas são vinculados às variáveis do cenário no Apidog.

O padrão completo é descrito em testes orientados por dados do Apidog CLI.

Comparação com outras ferramentas de CI

O padrão usado no Drone é o mesmo em muitos sistemas de CI:

1. Usar uma imagem com Node.
2. Instalar apidog-cli.
3. Injetar o token por segredo.
4. Executar apidog run.

A sintaxe do pipeline muda, mas o comando do Apidog permanece o mesmo.

Se você também usa outros provedores, consulte os guias para GitHub Actions e Azure Pipelines.

Observação de escopo: o Apidog CLI executa testes funcionais e de contrato. Ele não substitui ferramentas dedicadas de teste de carga para milhares de usuários virtuais concorrentes.

Crie os testes visualmente, execute-os com um comando

O fluxo recomendado é separar autoria e execução:

1. Modele endpoints no Apidog.
2. Monte cenários de teste visualmente.
3. Adicione asserções para status code, campos de resposta e regras de contrato.
4. Configure ambientes e variáveis.
5. Execute a suíte na CI com apidog run.

Quando alguém atualiza um cenário no Apidog, o próximo build do Drone executa a versão atualizada. Não há uma segunda cópia da suíte para manter sincronizada.

Baixe o Apidog gratuitamente para criar seu primeiro cenário e use o .drone.yml acima para executá-lo em cada push.

Perguntas frequentes

O que é Drone CI?

Drone é uma plataforma CI/CD de código aberto, nativa de contêineres, agora parte da Harness. Ele executa cada passo do pipeline dentro de um contêiner Docker próprio, com pipelines definidos em um arquivo .drone.yml.

O Drone CI é gratuito?

O projeto principal do Drone é de código aberto e gratuito para auto-hospedagem. Após a aquisição pela Harness, o Drone passou a fazer parte do Harness CI Community Edition, com camadas empresariais pagas disponíveis.

O Drone CI é de código aberto?

Sim. O Drone continua sendo uma ferramenta CI nativa de contêineres de código aberto. A Harness adquiriu o projeto em 2020 e se comprometeu a mantê-lo aberto.

Como o Drone CI é usado?

Times usam o Drone para construir, testar e entregar código automaticamente em push ou pull_request. Você adiciona um .drone.yml ao repositório, e o Drone executa cada passo em um contêiner. Passos comuns incluem build, testes unitários, testes de API e upload de artefatos para armazenamento externo.

Como armazenar segredos no Drone CI?

Crie segredos pela interface do Drone em Settings > Secrets ou com drone secret add. Depois, referencie o segredo no environment de um passo ou no settings de um plugin usando from_secret. O valor real do token não aparece no YAML.

Posso executar testes Apidog na CI sem escrever scripts?

Sim. Você cria os cenários visualmente no Apidog e executa na CI com um único comando apidog run. No Drone, o passo precisa de uma imagem Node, npm install -g apidog-cli e o comando apontando para os IDs do cenário e do ambiente.