Como Rodar Testes de API do Apidog CLI no Drone CI

Você executa testes de API do Apidog CLI no Drone CI adicionando um passo de pipeline Docker que usa uma imagem Node, instala o apidog-cli e executa apidog run em um ambiente. Seu token de acesso Apidog reside em um segredo do Drone e é injetado via from_secret. Este guia apresenta um arquivo .drone.yml para copiar e colar, o tratamento de segredos, controle de ramificação e como expor o relatório de teste, já que o Drone não possui um armazenamento de artefatos integrado.

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, a prática de construir e testar código automaticamente a cada alteração. Se você quiser uma revisão sobre o conceito em si, veja o que é CI/CD.

A característica distintiva do Drone é simples: cada passo do pipeline é executado dentro de seu próprio contêiner Docker. Não há um agente de build compartilhado com uma proliferação de ferramentas pré-instaladas. Você escolhe uma imagem para cada passo, e o Drone executa seus comandos dentro dela. Isso torna os builds reproduzíveis e fáceis de entender.

Você define um pipeline em um arquivo .drone.yml na raiz do seu repositório. Um pipeline Docker possui três chaves de nível superior: kind, type e name. O trabalho acontece em steps, onde cada passo declara um name, uma image e uma lista de commands.

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 de shell com set -e e set -x, então o build falha rapidamente no primeiro código de saída diferente de zero e exibe cada comando antes de executá-lo. Os comandos sobrescrevem o entrypoint do contêiner, e o diretório de trabalho é a raiz do seu repositório.

Por Que Executar Testes de API em um Passo de Contêiner

Testes de API protegem contra desvio de contrato. Uma alteração no backend que silenciosamente altera o formato de uma resposta ou o código de status pode quebrar todos os clientes a jusante. A execução desses testes a cada push captura a regressão antes que ela seja entregue.

O Apidog se encaixa bem neste modelo. Você cria e mantém seus testes visualmente no aplicativo Apidog, e então executa exatamente os mesmos cenários de teste pela linha de comando com o Apidog CLI. Sem reescrita de scripts, sem um harness de teste separado. Para uma orientação mais ampla sobre a integração de testes de API em pipelines, leia boas práticas de CI/CD para testes de API.

Apidog é uma plataforma API tudo-em-um para design, depuração, teste, mocking e documentação. A CLI é a parte que transforma seus cenários de teste salvos em um único comando repetível, que é exatamente o que um passo do Drone precisa.

O Comando Apidog CLI Que Você Irá Executar

Instale a CLI com npm e, em seguida, execute um cenário de teste. Na CI, você aponta a execução para um cenário salvo com flags, para que não haja um arquivo de coleção local para gerenciar.

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

Aqui está o que cada flag faz:

• --access-token passa seu token de acesso Apidog. Não há forma abreviada.
• -t é o ID do cenário de teste que você deseja executar.
• -e é o ID do ambiente, e é obrigatório. Isso seleciona qual URL base e variáveis a execução usa.
• -r lista os reporters. Os valores válidos são cli, html, json e junit.

Você pode adicionar mais flags conforme necessário:

• -n ou --iteration-count repete a execução um número definido de vezes.
• -d ou --iteration-data recebe um caminho de arquivo CSV ou JSON, ou um ID numérico de conjunto de dados armazenado, para execuções orientadas por dados.
• --out-dir define o diretório de saída do relatório.
• --upload-report envia uma visão geral do relatório para a nuvem Apidog, onde você pode visualizá-lo no aplicativo. Você pode usá-lo como uma flag simples.
• --on-error controla o comportamento de falha com continue, end ou ignore.
• --project <id> e --branch <name> direcionam uma branch específica do projeto.

Para uma visão completa do comando e suas opções, consulte o guia completo do Apidog CLI e o passo a passo sobre como testar uma API REST pela linha de comando.

Um .drone.yml Completo para Testes Apidog

Aqui está um pipeline funcional. Ele usa uma imagem Node, instala a CLI e executa seu cenário. O token vem de um segredo do Drone, em vez de ser codificado.

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 e 89012 pelo ID do seu ambiente. Ambos são visíveis no aplicativo Apidog. Como o passo usa o reporter cli, o detalhamento completo de aprovação/falha é impresso diretamente no log de build do Drone, onde qualquer pessoa que esteja revisando o build pode lê-lo.

Armazenando Segredos no Drone CI

Nunca envie um token de API para seu repositório. O Drone mantém os segredos fora do YAML e os injeta em tempo de execução.

Você faz referência a um segredo dentro do bloco environment de um passo (ou do bloco settings de um plugin) com from_secret. O valor que você escreve é o nome do segredo, não o próprio token.

environment:
  APIDOG_ACCESS_TOKEN:
    from_secret: apidog_access_token

Existem duas maneiras comuns de criar o segredo. A primeira é a interface do Drone: abra seu repositório, vá para Configurações, depois Segredos, e adicione um segredo chamado apidog_access_token com seu token como valor. A segunda é a ferramenta de linha de comando do Drone.

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

Confirme os nomes exatos das flags com a documentação da CLI do Drone para sua versão, pois as flags da CLI podem mudar entre os lançamentos. O Drone também suporta uma variante de segredo criptografado no repositório onde drone encrypt produz um blob criptografado que você incorpora como um documento YAML kind: secret separado. Para a maioria das equipes, os segredos do repositório adicionados pela interface ou por drone secret add são mais simples e o ponto de partida recomendado.

Manter o token em um segredo é a mesma disciplina que você aplicaria em qualquer outro lugar. Para mais informações sobre como a CLI gerencia credenciais, consulte o guia sobre autenticação do Apidog CLI.

Controlando Execuções por Ramificação e Evento

O Drone oferece duas alavancas para controlar quando o trabalho é executado: trigger no nível do pipeline e when no nível do passo.

Um bloco trigger decide se todo o pipeline é executado. Todas as condições devem ser avaliadas como verdadeiras, então o exemplo abaixo é executado apenas em pushes e pull requests visando main.

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

Um bloco when fica dentro de um único passo e controla apenas aquele passo. Isso é útil quando você deseja que a maior parte do pipeline seja executada em todos os lugares, mas reserve uma passagem de teste mais pesada para uma branch.

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

Ambos os blocos suportam padrões glob e subchaves de inclusão/exclusão. Os tipos de evento suportados incluem push, pull_request, tag, promote, rollback, cron e custom.

Expondo Relatórios de Teste Sem um Repositório de Artefatos

O Drone não possui hospedagem nativa de artefatos. Isso muda a forma como você lida com os relatórios, mas você tem duas opções claras.

A primeira é a mais simples: use o reporter cli para que os resultados sejam impressos no log de build. Para a maioria das equipes, isso é suficiente, pois o log já mostra quais asserções passaram e quais falharam.

A segunda opção é gerar um relatório HTML e carregá-lo em algum lugar durável. O Drone publica um plugin oficial do S3, plugins/s3, que envia arquivos para S3 ou qualquer armazenamento compatível com S3. Gere o relatório com o reporter html e --out-dir, e então adicione um passo de upload.

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

O plugin lê suas credenciais AWS de segredos através de from_secret, o mesmo mecanismo que você usou para o token Apidog. A chave source é um padrão glob de arquivos para carregar, e target é o prefixo de destino no bucket.

Se você quiser um olhar mais aprofundado sobre o que o relatório contém e como lê-lo, veja o detalhamento dos relatórios de teste do Apidog CLI.

Adicionando Execuções Orientadas por Dados

Às vezes, um cenário precisa ser executado contra muitas linhas de entrada: dez IDs de usuário, uma dúzia de payloads, um conjunto de casos de borda. A CLI lida com isso com -d, que aceita um caminho de arquivo CSV ou JSON ou um ID de conjunto de dados armazenado.

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

Cada linha em data.csv se torna uma iteração, com os valores das colunas vinculados às variáveis do seu cenário. O padrão completo é abordado em testes orientados por dados do Apidog CLI.

Como Isso se Compara a Outras Ferramentas de CI

O padrão do Drone, instalar a CLI em um contêiner limpo e executar um comando, se estende a quase todos os sistemas de CI. A sintaxe do wrapper difere, mas o passo Apidog é o mesmo.

Se você também executa pipelines em outros lugares, o Apidog tem guias detalhados correspondentes para GitHub Actions e Azure Pipelines. A ideia compartilhada é que seus testes residem no Apidog e a ferramenta de CI simplesmente os aciona.

Uma observação honesta sobre o escopo: o Apidog CLI executa testes funcionais e de contrato, não testes de carga em larga escala. Se você precisa de milhares de usuários virtuais concorrentes para estressar um endpoint, procure uma ferramenta de teste de carga dedicada. Para verificar se sua API se comporta corretamente em cada commit, a CLI em um passo do Drone faz o trabalho muito bem.

Crie os Testes Visualmente, Execute-os Com Um Comando

O fluxo de trabalho que torna isso agradável é a divisão entre autoria e execução. Você projeta endpoints e monta cenários de teste visualmente no Apidog, encadeando requisições, fazendo asserções em códigos de status e campos de resposta, e reutilizando variáveis de ambiente. Nenhum código é necessário para construir a suíte.

Então a CI executa essa mesma suíte com um comando CLI dentro de um passo de contêiner. Quando um colega de equipe atualiza um teste no aplicativo Apidog, o próximo build do Drone o detecta automaticamente. Não há uma segunda cópia dos testes para manter sincronizada.

Baixe o Apidog gratuitamente para construir seu primeiro cenário de teste e, em seguida, coloque o .drone.yml acima em seu repositório 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 seu próprio contêiner Docker, com pipelines definidos em um arquivo .drone.yml. Isso mantém os builds reproduzíveis e evita a proliferação de ferramentas pré-instaladas de agentes de build tradicionais.

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 se tornou Harness CI Community Edition, com camadas empresariais pagas disponíveis. Para a maioria das equipes, a versão de código aberto auto-hospedada cobre a execução de testes de API como os deste guia.

O Drone CI é de código aberto?

Sim. O Drone é uma das ferramentas de CI nativas de contêineres originais e continua sendo de código aberto. Quando a Harness o adquiriu em 2020, a empresa comprometeu-se a manter o projeto de código aberto, e você ainda pode auto-hospedá-lo.

Como o Drone CI é usado?

As equipes usam o Drone para construir, testar e entregar código automaticamente em cada push ou pull request. Você envia um .drone.yml para seu repositório, o Drone o lê e executa cada passo em um contêiner. Os passos comuns incluem compilar código, executar testes de unidade, executar testes de API e carregar artefatos para armazenamento externo.

Como você armazena segredos no Drone CI?

Você adiciona segredos através da tela de Configurações e depois Segredos do repositório na interface do Drone, ou com drone secret add pela CLI. Em seguida, você faz referência a cada segredo dentro do bloco environment de um passo ou do bloco settings de um plugin usando from_secret, onde o valor é o nome do segredo. O token em si nunca aparece em seu YAML.

Posso executar testes Apidog na CI sem escrever scripts?

Sim. Você constrói cenários de teste visualmente no aplicativo Apidog e, em seguida, os executa na CI com um único comando apidog run. O passo do Drone só precisa de uma imagem Node, uma linha npm install -g apidog-cli e o comando de execução apontado para os IDs do seu cenário e ambiente.