Como Executar Testes de API Automatizados no Bamboo CI (Passo a Passo)

Sua build está verde. Testes de unidade passam, o JAR é empacotado, o artefato é implantado. Então a primeira requisição real atinge a API de staging e um serviço downstream retorna um 500 porque alguém mudou um campo de resposta há dois commits. A build disse que estava tudo bem. Não estava. Ela simplesmente nunca verificou a API.

Essa é a lacuna que a maioria dos pipelines de CI do Bamboo tem. O Atlassian Bamboo é bom em compilar código, executar suítes JUnit e enviar artefatos. O que ele não faz por si só é verificar se seus endpoints HTTP ainda se comportam como seu contrato promete. Se você quer essa rede de segurança, precisa adicionar testes de API automatizados como uma etapa no pipeline. Este guia explica exatamente como fazer isso, usando o Apidog para construir os testes e o CLI do Apidog para executá-los dentro de um job do Bamboo.

No final, você terá um plano do Bamboo que, a cada push, atinge seus endpoints, verifica códigos de status, valida corpos de resposta contra seu esquema e falha a build no momento em que um contrato é quebrado. Nenhuma licença Postman por assento, nenhum script de asserção escrito à mão para manter, e um relatório de teste HTML real anexado a cada build. Baixe o Apidog se quiser acompanhar; a parte do CLI é gratuita e aberta.

Por que testes de API pertencem ao Bamboo, e não depois dele

Muitas equipes testam suas APIs manualmente, ou pior, em produção. Alguém clica em uma coleção de requisições salvas antes de um lançamento e inspeciona as respostas. Isso funciona até que não funciona mais. As pessoas esquecem. Lançamentos acontecem em uma sexta-feira. O único endpoint que ninguém pensou em verificar novamente é o que quebra.

O CI existe para remover essa variável humana. O objetivo principal de um servidor de build é que as mesmas verificações sejam executadas da mesma forma, sempre, automaticamente, sem que ninguém precise se lembrar de executá-las. Seus testes de unidade já vivem lá. Seus testes de integração provavelmente também. Testes de API merecem o mesmo tratamento, e por algumas razões concretas:

• Contratos quebram silenciosamente. Um desenvolvedor de backend renomeia um campo JSON de userId para user_id. Os testes de unidade ainda passam porque testam a função, não o formato de comunicação. A equipe mobile descobre três dias depois. Um teste de API que faz asserções no corpo da resposta o detecta na mesma build que o introduziu.
• Códigos de status mentem quando ninguém está olhando. Um endpoint que deveria retornar 201 Created começa a retornar 200 OK após uma refatoração. Funcionalmente próximo, tecnicamente errado, e um cliente estrito o rejeitará. Uma asserção de pipeline sinaliza isso em segundos.
• Regressões de autenticação são caras. Um fluxo de token-refresh mal configurado que retorna 401 para credenciais válidas é o tipo de bug que derruba uma tela de login. Executar uma requisição autenticada em cada build significa que você o encontra antes que seus usuários o façam.
• Ambientes divergem. O ambiente de staging recebe uma mudança de configuração, uma feature flag é alterada, uma dependência é atualizada. Executar a mesma suíte de API contra o staging após cada implantação informa imediatamente se o ambiente ainda está saudável.

O contexto mais profundo é a mesma razão pela qual as equipes adotam CI/CD em primeiro lugar: detectar problemas cedo, quando são baratos de corrigir, em vez de tarde, quando são caros e embaraçosos. O teste de API é apenas a camada dessa estratégia que a maioria dos pipelines pula.

Como o teste de API se encaixa em um plano do Bamboo

Antes do passo a passo, ajuda entender onde isso se encaixa no modelo do Bamboo. O Bamboo organiza o trabalho em planos, e cada plano contém um ou mais estágios que são executados em ordem. Cada estágio contém jobs, e cada job é uma sequência de tarefas. Tarefas são os comandos reais: checkout, compilar, executar um script.

Seus testes de API se tornam uma tarefa dentro de um job dentro de um estágio. A colocação natural é um estágio dedicado que é executado após a aplicação ser construída e implantada em um ambiente de teste, porque você precisa de algo em execução para enviar requisições. Um plano típico acaba se parecendo com isso:

Plano: servico-pagamentos
├── Estágio: Build
│   └── Job: Compilar & Teste de Unidade
│       ├── Tarefa: Checkout de Código Fonte
│       └── Tarefa: Maven, clean package
├── Estágio: Implantar no Staging
│   └── Job: Implantação
│       └── Tarefa: Implantar artefato no staging
└── Estágio: Testes de API          <- isso é o que você está adicionando
    └── Job: Executar Suíte de API
        ├── Tarefa: Checkout de Código Fonte
        ├── Tarefa: Script, instalar & executar Apidog CLI
        └── Tarefa: Final, publicar relatório de teste

Se uma tarefa no estágio de Testes de API sair com um código diferente de zero, o Bamboo sinaliza o estágio como falho e toda a build fica vermelha. Esse é exatamente o comportamento que você deseja; um contrato quebrado deve parar a linha, não passar despercebido.

A ferramenta que faz o trabalho real nessa tarefa de script é o CLI do Apidog, um executor de linha de comando que executa cenários de teste que você projeta visualmente no Apidog. Você constrói o teste uma vez, em uma GUI, sem código, e o mesmo teste é executado inalterado em seu terminal e no Bamboo. Este é o mesmo padrão que as equipes usam para automatizar testes de API em qualquer sistema CI/CD; o Bamboo é um alvo entre muitos.

Passo 1: Construa seus testes de API no Apidog

Você não pode executar testes no CI até ter testes. O Apidog é onde você os projeta, e o design é visual, então um engenheiro de QA que não escreve código pode construir a mesma suíte que um desenvolvedor de backend construiria.

Abra o Apidog e crie um cenário de teste. Um cenário é uma sequência ordenada de requisições de API, executadas de cima para baixo, onde cada etapa pode reutilizar dados das etapas anteriores. Um cenário realista para um serviço de pagamentos pode ser:

1. POST /auth/login com credenciais válidas, então extrair o token de portador da resposta.
2. POST /orders usando esse token, criando um novo pedido, então salvar o orderId retornado.
3. GET /orders/{orderId} e confirmar que o pedido aparece com o status correto.
4. DELETE /orders/{orderId} para limpar.

Para cada requisição, adicione asserções. Essa é a parte que transforma uma requisição em um teste. O Apidog permite que você faça asserções visualmente, sem a necessidade de script:

• O código de status é igual a 200 (ou 201, o que o contrato disser).
• Um campo JSON existe e corresponde: $.data.status é igual a "pending".
• A resposta valida contra o esquema OpenAPI do endpoint, então qualquer tipo de campo inesperado ou propriedade obrigatória ausente falha na etapa.
• O tempo de resposta permanece abaixo de um limite, digamos 800ms, então uma regressão lenta também aparece.

As asserções baseadas em esquema merecem destaque. Como o Apidog é schema-first, ele já conhece o formato que seu endpoint prometeu em sua definição de API. Você pode afirmar "esta resposta corresponde ao seu esquema" com um clique, e essa única verificação protege contra uma categoria inteira de divergência de contrato, campos renomeados, tipos errados, propriedades descartadas, sem que você precise escrever uma única linha. Se você vem de uma ferramenta que usa muitos scripts, isso por si só já remove muita manutenção. É o mesmo modelo de asserção visual que torna o Apidog uma alternativa comum ao Postman para testes de API.

Agrupe cenários relacionados em uma suíte de testes se você tiver muitos. Uma suíte é apenas uma coleção de cenários que você pode executar juntos, o que mantém seu comando CI simples; você aponta o executor para uma suíte em vez de listar vinte cenários.

Use variáveis de ambiente para qualquer coisa que mude entre local, staging e produção: URLs base, credenciais, chaves de API. Defina um ambiente de staging no Apidog com baseUrl configurado para o seu host de staging. Você informará ao CLI qual ambiente usar no momento da execução, para que o mesmo cenário seja executado contra o staging no Bamboo e contra o localhost em seu laptop.

Passo 2: Gerar um token de acesso do Apidog e obter os IDs

O Bamboo é executado sem interface gráfica em um agente de build. Ele não consegue fazer login na sua conta Apidog através de um navegador, então o CLI se autentica com um token de acesso.

Dentro do seu cenário de teste, abra a aba CI/CD. Clique em "Adicionar token de acesso" e depois em "Gerar token". Copie o valor para um local seguro por um momento; você o armazenará como uma variável do Bamboo em breve, e não o colará em um script. O token é o que permite que um agente de build puxe e execute os testes do seu projeto privado.

Enquanto você está nessa aba CI/CD, o Apidog gera o comando de execução completo para você. Selecione "Linha de comando" como provedor e ele imprimirá algo que você pode copiar diretamente, com seu ID de cenário de teste e ID de projeto já preenchidos. Esse comando copiado é a base da sua tarefa do Bamboo. As partes que importam:

• Token de acesso: autenticação, passado como --access-token.
• ID do cenário de teste: o ID numérico após -t, identificando qual cenário executar.
• ID do ambiente: o ID numérico após -e, instruindo o CLI a executar contra o staging.

Mantenha esse comando gerado à mão. Os próximos passos o adaptarão para o Bamboo.

Passo 3: Armazenar o token como uma variável de plano do Bamboo

Nunca codifique um token diretamente em uma tarefa de script. Qualquer pessoa com acesso de leitura ao plano, e qualquer pessoa lendo os logs de build, o veria.

No Bamboo, vá para o seu plano, abra "Configuração do Plano" e encontre a aba "Variáveis". Adicione uma nova variável. Nomeie-a de forma clara, como APIDOG_ACCESS_TOKEN, e cole o token como valor. O Bamboo mascara variáveis cujos nomes contêm password, secret ou token, então nomeie-a de acordo e o valor ficará oculto nos logs e na interface do usuário.

No momento da execução, o Bamboo expõe as variáveis do plano para os scripts como variáveis de ambiente, prefixadas e em maiúsculas, com pontos se tornando underscores. Uma variável chamada APIDOG_ACCESS_TOKEN está disponível para sua tarefa de shell como $bamboo_APIDOG_ACCESS_TOKEN. Você a referenciará, nunca o token bruto, no script de build.

Essa mesma higiene se aplica a qualquer outro segredo que seus testes precisem; senhas de banco de dados, chaves de API de terceiros, segredos de assinatura. Defina-os como variáveis mascaradas do Bamboo e leia-os através do prefixo de ambiente bamboo_.

Passo 4: Adicionar o estágio de teste de API e uma tarefa de script

Agora, conecte-o ao plano. Na Configuração do Plano, adicione um novo estágio e chame-o de "Testes de API". Adicione um job a ele, e então adicione tarefas ao job nesta ordem.

Tarefa 1, Checkout de Código Fonte. Mesmo que os testes vivam na nuvem do Apidog, fazer o checkout do seu repositório dá ao agente um diretório de trabalho limpo e permite que você comite quaisquer arquivos de dados locais (dados de iteração CSV, por exemplo) junto com seu código.

Tarefa 2, Script. Este é o coração da questão. Escolha uma tarefa de Script, defina o interpretador como Shell (ou /bin/sh) e use um corpo de script inline. O script instala o CLI do Apidog no agente e executa seu cenário.

O CLI do Apidog é um pacote npm, então o agente precisa do Node.js v16 ou posterior. Se seus agentes já têm Node, você pode pular a linha de instalação; caso contrário, provisione-o através das capacidades do Bamboo ou de um agente baseado em Docker. Aqui está um corpo de script completo:

#!/bin/sh
set -e

# Instala o CLI do Apidog globalmente no agente
npm install -g apidog-cli

# Executa o cenário de teste contra o staging, gera relatório HTML + CLI
apidog run \
  --access-token "$bamboo_APIDOG_ACCESS_TOKEN" \
  -t 637132 \
  -e 358171 \
  -r cli,html \
  --out-dir ./apidog-reports

Troque 637132 pelo seu ID real de cenário de teste e 358171 pelo ID do seu ambiente de staging, os valores que o Apidog gerou no passo 2. Algumas notas sobre o que cada flag faz:

• --access-token lê a variável mascarada do Bamboo, então o segredo nunca aparece no script.
• -t (abreviação de --test-scenario) seleciona o cenário a ser executado. Para executar uma suíte inteira, use --test-suite <id>; para executar uma pasta inteira de cenários, use -f <folderId>.
• -e (--environment) seleciona o ambiente de staging que você definiu no Apidog, para que as requisições sejam enviadas para o host correto com as variáveis corretas.
• -r cli,html (--reporters) produz tanto um relatório de console que você verá no log de build do Bamboo quanto um relatório HTML que você pode publicar como um artefato. O CLI também suporta os formatos json e junit aqui.
• --out-dir controla onde os relatórios são salvos. O padrão é ./apidog-reports; defini-lo explicitamente torna o caminho do artefato previsível.

O set -e no topo é importante. Ele faz o shell sair no primeiro comando que falha. O CLI do Apidog já retorna um código de saída diferente de zero quando qualquer asserção falha, e esse código diferente de zero é o que informa ao Bamboo para falhar a build. Juntos, eles garantem que um contrato de API quebrado torne a build vermelha em vez de ser enterrado nos logs.

Se você já integrou testes de API com GitHub Actions antes, isso parecerá familiar; o executor e as flags são idênticos, apenas a camada de interface (YAML versus Bamboo UI) difere.

Passo 5: Publicar o relatório de teste como um artefato do Bamboo

Uma build vermelha informa que algo quebrou. O relatório HTML informa *o que* quebrou. Configure-o para que cada build mantenha o relatório.

No mesmo job, vá para a aba Artefatos e defina um novo artefato compartilhado:

• Nome: Relatório de Teste Apidog
• Localização: apidog-reports
• Padrão de cópia: **/*

Após cada build, o Bamboo coleta tudo no diretório apidog-reports e o anexa ao resultado da build. Abra qualquer build, vá para a aba Artefatos e você pode baixar ou visualizar o relatório HTML; resultados de requisição por requisição, as asserções que foram executadas e o corpo exato da resposta para qualquer coisa que falhou. Essa última parte economiza um tempo real de depuração. Em vez de reexecutar a requisição falha manualmente, você lê a resposta capturada diretamente da build.

Para uma exibição mais rica dentro do Bamboo, o reporter junit também é útil. Adicione junit à lista -r e, em seguida, adicione uma tarefa de JUnit Parser apontando para o arquivo XML do JUnit. O Bamboo então renderiza contagens de testes, detalhamentos de aprovação/reprovação e tendências de falhas nativamente no resumo da build, da mesma forma que exibe os resultados dos seus testes de unidade.

Passo 6: Executá-lo e ler o resultado

Acione o plano manualmente para a primeira execução; no Bamboo, "Executar plano" na página do plano. Observe o log da build para o estágio de "Testes de API". Você verá o npm instalando o CLI, então a saída da execução do Apidog fluindo, nome do cenário, cada requisição, cada asserção e uma linha de resumo final com os totais.

Dois resultados:

Todas as asserções passam. O CLI sai com código 0, o estágio fica verde, a build é bem-sucedida e o relatório HTML é anexado como um artefato de qualquer forma, para que você tenha um registro. Ótimo. Agora, torne-o automático; configure o plano para ser acionado a cada commit para sua branch principal (Configuração do Plano, Gatilhos, Polling de Repositório ou um webhook). Daqui em diante, cada push executará sua suíte de API sem nenhuma intervenção humana.

Uma asserção falha. O CLI sai com código diferente de zero, set -e interrompe o script, o estágio fica vermelho e a build falha. Abra o artefato, encontre a requisição falha e leia a resposta capturada. Talvez um campo tenha mudado. Talvez o ambiente de staging tenha retornado um 502 porque uma dependência está inativa. De qualquer forma, você sabe em um ou dois minutos após o commit que a introduziu, o que é o benefício completo.

Um resumo realista do console se parece com isto:

┌──────────────┬──────────┬──────────┐
│              │ executado│   falhou │
├──────────────┼──────────┼──────────┤
│   iterações  │        1 │        0 │
├──────────────┼──────────┼──────────┤
│   requisições│        4 │        0 │
├──────────────┼──────────┼──────────┤
│   asserções  │       11 │        1 │
└──────────────┴──────────┴──────────┘

  1 asserção falhou:
    GET /orders/{orderId}
      esperado $.data.status ser "pending" mas obteve "failed"

Essa única asserção falha é a razão de ser do estágio. Ela detectou uma regressão de contrato que compilou sem problemas e passou em todos os testes de unidade.

Tornando a suíte confiável no CI

Um teste de API instável é pior do que não ter teste, porque ele treina a equipe a ignorar builds vermelhas. Alguns hábitos mantêm a suíte confiável.

Isole os dados de teste. Cada execução deve criar o que precisa e limpar-se depois, como o fluxo de criar-depois-deletar pedido acima. Testes que dependem de um registro que alguém criou na terça-feira passada quebrarão no momento em que esse registro mudar. Execute contra um ambiente dedicado de staging ou teste, nunca produção.

Use execuções orientadas por dados para cobertura sem duplicação. Se você precisar testar o mesmo endpoint com vinte entradas diferentes, não construa vinte cenários. Use um único cenário com --iteration-data path/to/data.csv (ou -d), e o CLI o executará uma vez por linha. Comite o CSV para o seu repositório para que ele seja verificado com o código. Este é o mesmo padrão de teste orientado por dados que você usaria localmente, apenas orientado por um arquivo no CI.

Fixe a versão do CLI. npm install -g apidog-cli busca a versão mais recente. Para builds reproduzíveis, fixe uma versão conhecida, npm install -g apidog-cli@<versão>, para que uma atualização do CLI não altere silenciosamente o comportamento entre duas builds do mesmo commit.

Defina timeouts sensatos. Adicione --timeout-request 10000 para falhar rapidamente em um endpoint travado, em vez de deixar a build travada até que o próprio timeout do Bamboo a finalize. Um claro "requisição expirou" é melhor do que uma build vagamente travada.

Barre implantações no estágio da API. Como o estágio de Testes de API é executado antes de qualquer estágio de implantação em produção, e um estágio com falha interrompe o plano, um contrato quebrado não pode chegar à produção. Essa ordem é seu portão de lançamento. É a versão prática de construir um pipeline de CI/CD real em vez de uma build que apenas compila.

Mantenha os cenários rápidos e focados. Uma suíte de CI que leva vinte minutos não será executada a cada commit; as pessoas a moverão para execuções noturnas e perderão o feedback rápido. Mantenha a suíte por commit para seus caminhos críticos, autenticação, CRUD principal, fluxo de pagamento, e execute a suíte exaustiva de casos de borda em um cronograma.

Conclusão

O Bamboo já o protege de código que não compila e de testes de unidade que não passam. Adicionar um estágio de teste de API estende essa proteção aos contratos que seus serviços realmente expõem, a camada onde a maioria dos incidentes "mas funcionava localmente" realmente acontece.

A configuração é rápida: construa testes visuais e conscientes de esquema no Apidog, gere um token de acesso, armazene-o como uma variável mascarada do Bamboo e adicione uma tarefa de script que execute apidog run com seus IDs de cenário e ambiente. Publique o relatório como um artefato, gateie seu estágio de implantação atrás dele e acione o plano a cada commit. Depois disso, é automático. Cada push verifica sua API, e um contrato quebrado torna a build vermelha antes que possa se transformar em uma interrupção.

Baixe o Apidog e construa seu primeiro cenário de teste, depois insira o comando CLI gerado em uma tarefa de script do Bamboo. Na primeira vez que ele detectar uma regressão que compilou sem problemas, o estágio terá compensado os dez minutos que levou para ser configurado.