DEV Community

Cover image for Como Rodar Testes de API Automatizados no Buildkite
Lucas
Lucas

Posted on • Originally published at apidog.com

Como Rodar Testes de API Automatizados no Buildkite

Você pode executar testes de API automatizados no Buildkite criando uma etapa de comando em .buildkite/pipeline.yml: instale a CLI do Apidog, execute apidog run contra um ambiente e publique o relatório HTML como artefato do build. O fluxo abaixo mostra uma implementação completa, incluindo como passar o token do Apidog com segurança usando secrets do Buildkite.

Experimente o Apidog hoje

Antes de começar: Buildkite é uma plataforma de CI/CD. Ele não é o Docker BuildKit, que é o backend de build de imagens do Docker. Este guia trata apenas da plataforma Buildkite.

O que é Buildkite

Buildkite é uma plataforma de CI/CD baseada em um modelo híbrido:

  • O painel hospedado do Buildkite orquestra os builds.
  • Os agentes executam os jobs de fato.

Essa separação é importante porque seus jobs podem rodar dentro da sua própria infraestrutura, com acesso à sua rede, serviços internos e ferramentas já instaladas. Você também pode usar agentes hospedados pelo Buildkite, caso prefira computação gerenciada.

Para testes de API, isso é útil porque os testes podem ser executados exatamente onde seu ambiente de staging, QA ou produção controlada já é acessível.

O agente Buildkite é open source, escrito em Go e distribuído sob a licença MIT. A plataforma SaaS e o painel de controle ao redor dele são comerciais.

Para que o Buildkite é usado

Equipes usam Buildkite para automatizar tarefas acionadas por mudanças no código, como:

  • build de artefatos;
  • testes unitários;
  • testes de integração;
  • testes end-to-end;
  • validações de API;
  • deploys;
  • tarefas que exigem hardware, rede ou permissões específicas.

Em um fluxo de API, o Buildkite pode:

  1. receber um push ou pull request;
  2. executar testes contra um ambiente real;
  3. gerar relatórios;
  4. bloquear o deploy se um contrato de API quebrar.

Se você estiver comparando ferramentas de CI, veja também o resumo das melhores ferramentas de integração contínua para equipes de API.

Como os pipelines do Buildkite são definidos

Um pipeline do Buildkite normalmente fica em:

.buildkite/pipeline.yml
Enter fullscreen mode Exit fullscreen mode

Quando um build começa, o Buildkite procura esse arquivo no repositório. Também é possível usar um diretório buildkite/ não oculto na raiz.

A estrutura básica é:

steps:
  - label: "Nome da etapa"
    command: "comando"
Enter fullscreen mode Exit fullscreen mode

Para testes de API, os tipos de etapa mais comuns são:

  • command steps: executam comandos shell em um agente;
  • wait steps: aguardam etapas anteriores terminarem;
  • block steps: criam uma aprovação manual antes de continuar.

Exemplo:

steps:
  - label: ":test_tube: Testes"
    command: "npm test"

  - wait

  - block: ":rocket: Aprovar deploy?"

  - label: ":rocket: Deploy"
    command: "scripts/deploy.sh"
Enter fullscreen mode Exit fullscreen mode

Algumas chaves úteis em command steps:

Chave Uso
label Nome exibido no build
key Identificador da etapa
command / commands Script executado
env Variáveis não sensíveis
agents Seleção de agentes por tags
secrets Injeção segura de credenciais
artifact_paths Arquivos preservados
parallelism Execuções paralelas idênticas
matrix Execuções paralelas com valores diferentes

A chave agents roteia jobs para agentes específicos:

agents:
  queue: "tests"
Enter fullscreen mode Exit fullscreen mode

Use isso quando os testes precisarem de acesso a uma rede, dependência ou ambiente específico.

Pipeline mínimo para executar testes de API com Apidog

Abaixo está um .buildkite/pipeline.yml mínimo para:

  1. instalar a CLI do Apidog;
  2. executar um cenário de teste;
  3. gerar relatório no terminal e em HTML;
  4. publicar o relatório como artefato do Buildkite. 
steps:
  - label: ":test_tube: Testes de API (Apidog)"
    key: "api-tests"
    command: |
      npm install -g apidog-cli
      apidog run \
        --access-token "$APIDOG_ACCESS_TOKEN" \
        -t 637132 \
        -e 358171 \
        -r html,cli
      buildkite-agent artifact upload "apidog-reports/**/*"
    agents:
      queue: "default"
    secrets:
      - APIDOG_ACCESS_TOKEN
Enter fullscreen mode Exit fullscreen mode

Substitua os IDs pelos valores do seu projeto:

  • -t 637132: ID do cenário de teste ou diretório de cenários;
  • -e 358171: ID do ambiente de execução;
  • -r html,cli: gera relatório HTML e saída no terminal;
  • --access-token: token usado pela CLI para acessar o projeto Apidog.

O binário buildkite-agent já está disponível no agente, porque é ele que executa o job. Você só precisa instalar a CLI do Apidog.

Para ver todas as flags disponíveis, consulte o guia completo da CLI do Apidog.

Se quiser testar primeiro fora da CI, veja o tutorial de teste de linha de comando da CLI do Apidog.

Passando o token do Apidog com secrets do Buildkite

O token de acesso do Apidog é uma credencial. Não coloque esse valor diretamente em:

  • pipeline.yml;
  • logs;
  • variáveis env: simples;
  • scripts versionados.

Use secrets.

Opção 1: usar secrets: diretamente na etapa

Se o nome do secret no Buildkite for igual ao nome da variável de ambiente desejada:

steps:
  - command: |
      apidog run \
        --access-token "$APIDOG_ACCESS_TOKEN" \
        -t 637132 \
        -e 358171 \
        -r html,cli
    secrets:
      - APIDOG_ACCESS_TOKEN
Enter fullscreen mode Exit fullscreen mode

Nesse caso, a variável APIDOG_ACCESS_TOKEN fica disponível apenas durante a execução do job.

Opção 2: mapear secret para outro nome de variável

Se o secret estiver salvo como apidog_token, mas você quiser expô-lo como APIDOG_ACCESS_TOKEN:

steps:
  - command: |
      apidog run \
        --access-token "$APIDOG_ACCESS_TOKEN" \
        -t 637132 \
        -e 358171 \
        -r html,cli
    secrets:
      APIDOG_ACCESS_TOKEN: apidog_token
Enter fullscreen mode Exit fullscreen mode

Opção 3: buscar o secret dentro do script

Você também pode buscar o valor manualmente com a CLI do agente:

APIDOG_ACCESS_TOKEN="$(buildkite-agent secret get apidog_token)"

apidog run \
  --access-token "$APIDOG_ACCESS_TOKEN" \
  -t 637132 \
  -e 358171 \
  -r html,cli
Enter fullscreen mode Exit fullscreen mode

Isso é útil quando você quer controlar exatamente em que ponto o segredo é lido.

Outras opções para agentes self-hosted

Em agentes auto-hospedados, você também pode carregar segredos usando:

  • hook environment do agente;
  • AWS Secrets Manager;
  • HashiCorp Vault;
  • GCP Secret Manager;
  • plugins do Buildkite.

Nesse modelo, você pode usar variáveis como:

$BUILDKITE_PIPELINE_SLUG
$BUILDKITE_STEP_KEY
Enter fullscreen mode Exit fullscreen mode

para decidir quais secrets carregar para cada job.

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

Publicando o relatório HTML como artefato

Quando você usa:

-r html
Enter fullscreen mode Exit fullscreen mode

a CLI gera um relatório HTML no workspace do agente. Esse arquivo desaparece ao fim do job, a menos que você faça upload como artefato.

Use:

buildkite-agent artifact upload "apidog-reports/**/*"
Enter fullscreen mode Exit fullscreen mode

Mantenha o glob entre aspas. Assim, quem interpreta o padrão é o buildkite-agent, não o shell.

Por padrão, os artefatos enviados vão para o armazenamento gerenciado pelo Buildkite, com retenção de 6 meses e limite de 5 GB por artefato.

Depois do build, abra a aba Artifacts para baixar o relatório HTML e revisar as asserções que passaram ou falharam.

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

Executando testes em paralelo em múltiplos ambientes

Se o mesmo conjunto de testes precisa rodar em mais de um ambiente, use matrix.

Exemplo:

steps:
  - label: ":test_tube: Testes de API {{matrix.env}}"
    command: |
      npm install -g apidog-cli
      apidog run \
        --access-token "$APIDOG_ACCESS_TOKEN" \
        -t 637132 \
        -e "{{matrix.env}}" \
        -r html,cli
      buildkite-agent artifact upload "apidog-reports/**/*"
    secrets:
      - APIDOG_ACCESS_TOKEN
    matrix:
      setup:
        env:
          - "358171"   # ID do ambiente de staging
          - "358172"   # ID do ambiente de produção
Enter fullscreen mode Exit fullscreen mode

O Buildkite substitui {{matrix.env}} em cada execução. Assim, cada job usa um ambiente diferente do Apidog.

Se você quer apenas várias cópias idênticas do mesmo job, use parallelism:

steps:
  - label: ":test_tube: Testes de API"
    command: |
      npm install -g apidog-cli
      apidog run \
        --access-token "$APIDOG_ACCESS_TOKEN" \
        -t 637132 \
        -e 358171 \
        -r html,cli
    secrets:
      - APIDOG_ACCESS_TOKEN
    parallelism: 5
Enter fullscreen mode Exit fullscreen mode

Para testes orientados a dados com CSV ou JSON, use a flag -d da CLI do Apidog em vez de matrix. Veja o guia de testes orientados a dados da CLI do Apidog.

Bloqueando deploys com testes de API

Um padrão comum de pipeline é:

  1. executar testes;
  2. aguardar conclusão;
  3. pedir aprovação manual;
  4. executar deploy.

No Buildkite, isso pode ser modelado com wait e block:

steps:
  - label: ":test_tube: Testes de API"
    command: |
      npm install -g apidog-cli
      apidog run \
        --access-token "$APIDOG_ACCESS_TOKEN" \
        -t 637132 \
        -e 358171 \
        -r html,cli
    secrets:
      - APIDOG_ACCESS_TOKEN

  - wait

  - block: ":rocket: Implantar?"
    branches: "main"

  - label: ":rocket: Implantar"
    command: "scripts/deploy.sh"
Enter fullscreen mode Exit fullscreen mode

A etapa wait garante que o pipeline só continue depois dos testes. A etapa block exige aprovação manual e, com branches: "main", só aparece na branch principal.

Esse fluxo impede que uma implantação prossiga automaticamente quando os testes de API falham.

Para padrões mais amplos, veja as melhores práticas de CI/CD para testes de API.

Adicionando uma anotação de resumo no Buildkite

Logs de build podem ficar longos. Para destacar o resultado dos testes, use uma anotação:

cat << 'EOF' | buildkite-agent annotate --style "success" --context "apidog"
### Resultados do teste de API

Todos os cenários Apidog foram aprovados.

[Baixe o relatório HTML completo](artifact://apidog-reports/index.html)
EOF
Enter fullscreen mode Exit fullscreen mode

A flag --style controla o visual da anotação:

  • info;
  • warning;
  • error;
  • success.

A flag --context define um identificador único. Se outra etapa usar o mesmo contexto, ela atualiza a anotação existente em vez de criar uma nova.

O link artifact:// aponta diretamente para um artefato enviado no build.

Onde o Apidog se encaixa

O pipeline fica curto porque a manutenção dos testes acontece no Apidog, não no YAML.

Apidog é uma plataforma de API para projetar, depurar, testar, simular e documentar APIs. Você cria cenários em um editor visual, encadeia requisições, reutiliza dados entre etapas e adiciona asserções sem precisar manter scripts customizados.

A CLI do Apidog é a ponte com a CI.

O fluxo é:

  1. crie o cenário no Apidog;
  2. copie o ID do cenário;
  3. copie o ID do ambiente;
  4. execute apidog run no Buildkite.

Exemplo local:

apidog run \
  --access-token "$APIDOG_ACCESS_TOKEN" \
  -t 637132 \
  -e 358171 \
  -r cli,html
Enter fullscreen mode Exit fullscreen mode

Quando você atualiza o cenário no Apidog, o próximo build do Buildkite executa a versão atualizada sem exigir mudanças no YAML.

O mesmo comando também pode ser usado em outras plataformas de CI. Veja o guia de pipeline CI/CD da CLI do Apidog e o passo a passo da CLI do Apidog com GitHub Actions.

Para começar, crie um cenário de teste no Apidog e adicione uma etapa apidog run ao seu pipeline do Buildkite.

Perguntas frequentes

O que é Buildkite?

Buildkite é uma plataforma de CI/CD com arquitetura híbrida. O painel hospedado orquestra os builds, enquanto os agentes executam os jobs. Os agentes podem rodar na sua infraestrutura ou em computação hospedada pelo Buildkite.

Ele não tem relação com o Docker BuildKit.

Para que o Buildkite é usado?

Buildkite é usado para automatizar tarefas como builds, testes, validações e deploys. Para equipes de API, ele pode executar testes automatizados contra staging ou produção controlada e bloquear deploys quando os testes falham.

O Buildkite é open source?

O agente Buildkite é open source, escrito em Go e licenciado sob MIT. A plataforma SaaS e o painel de controle são comerciais.

O Buildkite é gratuito?

Sim. O Buildkite possui um plano gratuito chamado Personal, com US$ 0, sem cartão de crédito e sem prazo de validade. Ele inclui 3 jobs simultâneos, 1 usuário, 90 dias de retenção, 500 minutos mensais de agente Linux hospedado e 50.000 execuções de teste por mês. Também há um teste All Access de 30 dias para recursos pagos.

Como carregar artefatos no Buildkite?

Execute:

buildkite-agent artifact upload "<pattern>"
Enter fullscreen mode Exit fullscreen mode

Exemplo:

buildkite-agent artifact upload "apidog-reports/**/*"
Enter fullscreen mode Exit fullscreen mode

Use aspas no glob para que o agente faça a correspondência dos arquivos. Os artefatos aparecem na aba Artifacts do build.

Como executar testes de API em um pipeline do Buildkite?

Crie uma etapa de comando em .buildkite/pipeline.yml que:

  1. instale a CLI do Apidog;
  2. execute apidog run;
  3. passe o token via secret;
  4. gere relatório com -r html,cli;
  5. publique o relatório com buildkite-agent artifact upload.

Exemplo:


yaml
steps:
  - label: ":test_tube: Testes de API"
    command: |
      npm install -g apidog-cli
      apidog run \
        --access-token "$APIDOG_ACCESS_TOKEN" \
        -t 637132 \
        -e 358171 \
        -r html,cli
      buildkite-agent artifact upload "apidog-reports/**/*"
    secrets:
      - APIDOG_ACCESS_TOKEN
Enter fullscreen mode Exit fullscreen mode

Top comments (0)