Você executa testes de API automatizados no Buildkite definindo uma etapa de comando em .buildkite/pipeline.yml que instala a CLI do Apidog, executa apidog run em um ambiente e carrega o relatório HTML como um artefato de build. Este guia detalha o pipeline completo, incluindo como o Buildkite lida com segredos para que seu token de acesso Apidog nunca vaze para os logs. Assumimos que seus testes Apidog já existem; você os constrói visualmente uma vez e depois os executa a partir de um único comando na CI.
Uma rápida clarificação antes de começarmos. Buildkite é uma plataforma de CI/CD. Não é o mesmo que Docker BuildKit, o backend de construção de imagens dentro do Docker. Os nomes são parecidos, mas são produtos não relacionados. Este artigo é inteiramente sobre a plataforma de CI/CD Buildkite.
O que é Buildkite
Buildkite é uma plataforma de CI/CD construída em torno de um modelo híbrido. Possui um painel de controle hospedado, o dashboard e a orquestração de builds que você vê no seu navegador, e agentes que realmente executam seus trabalhos.
A divisão importa. O painel de controle agenda o trabalho, mas o trabalho é executado nos agentes. Você pode hospedar agentes em sua própria infraestrutura ou nuvem, ou pode usar agentes hospedados pelo Buildkite, que são recursos computacionais gerenciados que o Buildkite executa para você.
Esta é a principal característica que diferencia o Buildkite de sistemas de CI totalmente hospedados. Seu código e segredos podem permanecer em suas próprias máquinas enquanto o Buildkite coordena os builds. Para testes de API, isso significa que seus testes são executados onde seus serviços e acesso à rede já existem.O próprio agente Buildkite é de código aberto. Ele é escrito em Go e lançado sob a Licença MIT, com o código-fonte no GitHub. A plataforma e o painel de controle em torno dele são um produto SaaS comercial.
Para que o Buildkite é usado
As equipes usam o Buildkite para executar qualquer tipo de trabalho automatizado acionado por alterações no código: construir artefatos, executar testes de unidade e integração, implantar serviços e executar verificações ponta a ponta. Como os agentes podem ser executados em seu próprio hardware, é comum em equipes que precisam de controle sobre computação, limites de rede ou hardware como GPUs.
O teste de API se encaixa bem nisso. Você quer que seus testes atinjam um ambiente de staging ou de teste, verifiquem respostas reais e bloqueiem uma implantação quando um contrato for quebrado. O Buildkite oferece os tipos de etapas para modelar exatamente esse fluxo, que usaremos abaixo.
Se você está comparando o Buildkite com outras opções, nosso resumo das melhores ferramentas de integração contínua para equipes de API aborda como várias plataformas se comparam para este caso de uso.
Como os pipelines do Buildkite são definidos
Um pipeline do Buildkite é uma lista de etapas. O local padrão para defini-los é um arquivo em .buildkite/pipeline.yml em seu repositório. Quando um build começa, o Buildkite procura por um diretório chamado .buildkite contendo um arquivo chamado pipeline.yml. Um diretório não oculto buildkite/ na raiz do repositório também funciona.
A chave de nível superior é steps:, e ela contém uma lista. Os tipos de etapas que você usará com mais frequência para testes de API são estes:
- Etapas de comando executam comandos shell em um agente. É aqui que seus testes são executados.
- Etapas de espera pausam o pipeline até que todas as etapas anteriores terminem. Você as escreve como um item de lista
- waitsimples. - Etapas de bloqueio criam um portão de aprovação manual, escrito como
- block: "Label". Um humano clica para continuar, o que é útil antes de uma implantação em produção.
As etapas de comando suportam um conjunto de chaves que você usará frequentemente: label e key para nomear e referenciar, command ou commands para o script, env para variáveis de ambiente, agents para direcionamento, secrets para injetar valores secretos, artifact_paths para arquivos a serem mantidos, parallelism para fan-out e matrix para executar a mesma etapa em um conjunto de valores.
A chave agents é um hash de pares de tags. Você a usa para rotear uma etapa para o agente certo, por exemplo queue: "tests". As tags permitem que você mantenha trabalhos de teste em agentes que possuem o acesso de rede ou as ferramentas corretas.
Um pipeline para copiar e colar que executa testes de API
Aqui está um .buildkite/pipeline.yml mínimo que instala a CLI do Apidog, executa um cenário de teste em um ambiente e carrega o relatório HTML. A CLI do Apidog é uma ferramenta Node.js que executa seus cenários de teste Apidog a partir da linha de comando.
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
Algumas notas sobre as flags. -t é o ID do cenário de teste ou diretório de cenário que você deseja executar. -e é o ID do ambiente de execução, que seleciona a URL base e as variáveis que seus testes usam. -r html,cli solicita tanto um resumo de terminal legível por humanos quanto um arquivo de relatório HTML. --access-token passa seu token Apidog para que a CLI possa acessar seu projeto.
O host do agente Buildkite já tem o binário buildkite-agent disponível, pois é isso que executa o trabalho. Você só instala o apidog-cli você mesmo. Para um tour mais aprofundado de cada flag, consulte o guia completo da CLI do Apidog.
Se você deseja um passo a passo da execução de uma única API a partir do terminal primeiro, o tutorial de teste de linha de comando da CLI do Apidog é um bom aquecimento antes de conectá-lo à CI.
Passando o token de acesso Apidog com segredos do Buildkite
Seu token de acesso Apidog é uma credencial. Ele nunca deve estar em seu pipeline.yml ou ser impresso no log de build. O Buildkite oferece um recurso nativo para isso, chamado Buildkite secrets.
Buildkite secrets é um armazenamento de chave-valor criptografado. Os valores são criptografados em repouso e em trânsito via TLS, descriptografados nos servidores Buildkite e com escopo por cluster, onde cada cluster tem sua própria chave de criptografia. Funciona tanto com agentes hospedados pelo Buildkite quanto com agentes auto-hospedados. Qualquer valor secreto que aparece em seus logs é automaticamente ocultado.
Existem duas maneiras de usar um segredo armazenado. A primeira é a chave secrets: em uma etapa de comando. Em sua forma de lista mais simples, o nome da variável de ambiente corresponde à chave secreta:
steps:
- command: |
apidog run --access-token "$APIDOG_ACCESS_TOKEN" -t 637132 -e 358171 -r html,cli
secrets:
- APIDOG_ACCESS_TOKEN
Se o seu segredo armazenado tem um nome diferente da variável de ambiente que você deseja, use a forma de hash. A chave é o nome da variável de ambiente e o valor é a chave do segredo:
steps:
- command: |
apidog run --access-token "$APIDOG_ACCESS_TOKEN" -t 637132 -e 358171 -r html,cli
secrets:
APIDOG_ACCESS_TOKEN: apidog_token # env var name : Buildkite secret key
A segunda maneira é buscar o segredo imperativamente dentro do seu script com a CLI do agente. Isso é útil quando você deseja controlar exatamente quando o valor é lido:
APIDOG_ACCESS_TOKEN="$(buildkite-agent secret get apidog_token)"
apidog run --access-token "$APIDOG_ACCESS_TOKEN" -t 637132 -e 358171 -r html,cli
Buildkite secrets não é sua única opção. Em agentes auto-hospedados, você pode usar um hook de agente environment, um script que é executado no início de cada trabalho e exporta valores para o ambiente. Você pode controlá-lo por variáveis como $BUILDKITE_PIPELINE_SLUG ou $BUILDKITE_STEP_KEY para que um segredo seja carregado apenas para os trabalhos certos. Você também pode puxar de armazenamentos externos, como AWS Secrets Manager, HashiCorp Vault ou GCP, através de plugins Buildkite, caso em que o segredo nunca é armazenado ou enviado para o Buildkite.
Os valores simples de env: são bons para configurações não sensíveis, mas não coloque tokens lá. Para mais detalhes sobre como o token flui do seu armazenamento de segredos para a CLI, consulte o guia sobre autenticação da CLI do Apidog.
Carregando o relatório HTML como um artefato
O reportador -r html escreve um relatório HTML em um caminho local no espaço de trabalho do agente. Esse arquivo desaparece quando o trabalho termina, a menos que você o salve. O comando buildkite-agent artifact upload o mantém.
buildkite-agent artifact upload "apidog-reports/**/*"
As aspas em torno do padrão glob são importantes. Elas impedem que seu shell expanda o padrão antes que o agente o veja, então o agente faz a correspondência por conta própria. Os artefatos carregados vão para o armazenamento gerenciado pelo Buildkite por padrão, com uma janela de retenção de 6 meses e um limite de 5 GB por artefato. Você pode passar um destino como um segundo argumento se quiser enviá-los para outro lugar.
Após a execução de um build, o relatório aparece na aba Artifacts do build. Qualquer pessoa que revise o build pode fazer o download e ver quais asserções passaram ou falharam. Se você quiser entender os formatos de relatório primeiro, o guia de relatórios de teste da CLI do Apidog abrange saídas CLI, HTML e JSON.
Executando testes em paralelo em diferentes ambientes
Quando você deseja que o mesmo conjunto de testes seja executado em vários ambientes ao mesmo tempo, use uma matrix. O Buildkite expande uma definição de etapa em um trabalho por valor de matriz, e eles são executados em paralelo.
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
Aqui, {{matrix.env}} é substituído tanto no rótulo quanto na flag -e, de modo que cada trabalho visa um ambiente Apidog diferente. Se você deseja apenas expandir cópias idênticas de um único trabalho, defina parallelism: 5 na etapa em vez de uma matriz.
Para execuções baseadas em dados, onde um cenário itera sobre linhas de um arquivo CSV ou JSON, a CLI do Apidog lida com isso com sua própria flag -d em vez da matriz do Buildkite. O guia de testes orientados a dados da CLI do Apidog mostra como alimentar um arquivo de dados em um cenário.
Protegendo uma implantação por trás de testes
Uma forma comum é: executar testes, esperar que terminem, pedir aprovação a um humano e, em seguida, implantar. O Buildkite modela isso com as etapas 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"
A etapa wait segura o pipeline até que os testes sejam concluídos. A etapa block pausa para um clique manual e é restrita à branch main com branches:. Somente após a aprovação de alguém, a etapa de implantação é executada. Isso impede que um conjunto de testes com falha chegue à produção. Para padrões mais amplos sobre isso, consulte nossas melhores práticas de CI/CD para testes de API.
Adicionando uma anotação de resumo
Os logs de build são longos. Uma anotação coloca um resumo curto e formatado no topo da página de build. Você cria uma canalizando markdown para buildkite-agent annotate.
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
A flag --style controla a cor e o ícone, com os valores info, warning, error e success. A flag --context dá à anotação um ID único, de modo que uma etapa posterior com o mesmo contexto atualiza a mesma anotação em vez de adicionar uma nova. O link artifact:// direciona os revisores diretamente para o relatório HTML carregado.
Onde o Apidog se encaixa
O pipeline acima é curto de propósito. O trabalho pesado de escrever e manter testes acontece no Apidog, não no YAML.
Apidog é uma plataforma de API tudo-em-um para projetar, depurar, testar, simular e documentar APIs. Você constrói cenários de teste em um editor visual: encadeia requisições, passa dados entre etapas e adiciona asserções sem escrever scripts. Como os cenários vivem em seu projeto Apidog, sua equipe os edita em um só lugar e os controla por versão com suporte a branches.
A CLI é a ponte para a CI. Você constrói um cenário uma vez, pega seu ID de cenário e ambiente, e toda a integração de CI é um único comando apidog run. Quando você atualiza um teste no Apidog, o próximo build do Buildkite detecta a mudança sem edições no YAML. Essa propriedade de comando único é o que faz o Apidog se encaixar perfeitamente no Buildkite, GitHub Actions ou qualquer outro sistema. Cobrimos o mesmo comando em outras plataformas no guia de pipeline CI/CD da CLI do Apidog e no passo a passo CLI do Apidog com GitHub Actions.
Para experimentá-lo primeiro em sua própria máquina, antes de conectar qualquer coisa à CI, execute o mesmo comando localmente com seu token:
apidog run --access-token "$APIDOG_ACCESS_TOKEN" -t 637132 -e 358171 -r cli,html
Baixe o Apidog gratuitamente, crie um cenário de teste e adicione o comando apidog run de uma linha ao seu pipeline do Buildkite.
Perguntas Frequentes
O que é Buildkite?
Buildkite é uma plataforma de CI/CD com um design híbrido. Um painel de controle hospedado executa o dashboard e orquestra os builds, enquanto os agentes executam os trabalhos reais. Os agentes podem ser executados em sua própria infraestrutura ou em computação hospedada pelo Buildkite. Não está relacionado ao Docker BuildKit, que é uma ferramenta separada de construção de imagens que por acaso tem um nome similar.
Para que o Buildkite é usado?
As equipes usam o Buildkite para automatizar trabalhos acionados por alterações no código: construir artefatos, executar testes e implantar. É comum em equipes onde desejam que seus builds sejam executados em seu próprio hardware ou dentro de sua própria rede. Para equipes de API, ele executa testes automatizados contra ambientes de staging e produção e pode bloquear uma implantação quando os testes falham.
O Buildkite é de código aberto?
O agente Buildkite é de código aberto. Ele é escrito em Go e lançado sob a Licença MIT, com seu código-fonte no GitHub. A plataforma e o painel de controle em torno do agente são um produto SaaS comercial, portanto, apenas o agente em si é de código aberto.
O Buildkite é gratuito?
Sim, o Buildkite possui um plano gratuito chamado Personal. Ele custa US$ 0, sem necessidade de cartão de crédito e sem prazo de validade. Inclui 3 jobs simultâneos, 1 usuário, 90 dias de retenção, 500 minutos de agente hospedado Linux por mês e 50.000 execuções de teste por mês. Há também um teste All Access de 30 dias para avaliar os recursos pagos.
Como você carrega artefatos no Buildkite?
Você executa buildkite-agent artifact upload "<pattern>" dentro de uma etapa de comando. Coloque o padrão glob entre aspas para que o agente o corresponda em vez do shell. Os arquivos vão para o armazenamento gerenciado pelo Buildkite por padrão, com retenção de 6 meses e um limite de 5 GB por artefato. Para testes de API, você carrega o relatório HTML para que os revisores possam abri-lo na aba Artifacts do build.
Como você executa testes de API em um pipeline do Buildkite?
Adicione uma etapa de comando a .buildkite/pipeline.yml que instala a CLI do Apidog com npm install -g apidog-cli, em seguida executa apidog run com um ID de cenário de teste, um ID de ambiente via -e e -r html,cli para relatórios. Passe seu token de acesso através de um segredo do Buildkite e carregue o relatório HTML com buildkite-agent artifact upload para que os resultados persistam após o build.