DEV Community

Cover image for Como Executar Testes de API Automatizados no Bamboo CI (Passo a Passo)
Lucas
Lucas

Posted on • Originally published at apidog.com

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

Sua build está verde: testes unitários passam, o JAR é empacotado e o artefato é implantado. Então a primeira requisição real chega à API de staging e um serviço downstream retorna 500, porque alguém mudou um campo da resposta há dois commits. A build não mentiu; ela só nunca verificou a API.

Experimente o Apidog hoje

Essa é uma lacuna comum em pipelines do Atlassian Bamboo. O Bamboo compila código, executa suítes JUnit e publica artefatos, mas não valida sozinho se seus endpoints HTTP continuam cumprindo o contrato. Para isso, adicione testes de API automatizados como uma etapa do pipeline. Neste guia, você vai usar o Apidog para criar os testes e o CLI do Apidog para executá-los dentro de um job do Bamboo.

Ao final, seu plano do Bamboo vai executar endpoints a cada push, validar códigos de status, checar corpos de resposta contra o schema e falhar a build quando um contrato quebrar. Você também terá um relatório HTML anexado a cada build. Se quiser acompanhar, baixe o Apidog; a parte do CLI é gratuita e aberta.

Por que colocar testes de API no Bamboo

Testes manuais de API funcionam até alguém esquecer de executá-los. O objetivo do CI é remover essa variável: as mesmas verificações devem rodar da mesma forma, sempre, sem depender de memória humana.


Bamboo CI

Testes de API no pipeline ajudam a capturar problemas que testes unitários normalmente não veem:

  • Quebras de contrato: um campo JSON muda de userId para user_id.
  • Códigos de status incorretos: um endpoint que deveria retornar 201 Created passa a retornar 200 OK.
  • Regressões de autenticação: um fluxo de refresh token começa a retornar 401 para credenciais válidas.
  • Divergência entre ambientes: staging recebe uma configuração diferente e uma dependência deixa de responder.

A lógica é a mesma de adotar CI/CD: detectar falhas cedo, enquanto ainda são baratas de corrigir.

Como os testes de API entram em um plano do Bamboo

No Bamboo, um plano contém estágios, cada estágio contém jobs e cada job contém tarefas. Os testes de API entram como uma tarefa de script dentro de um job, normalmente após o build e a implantação em staging.

Tarefa do Bamboo

Um plano típico fica assim:

Plano: servico-pagamentos
├── Estágio: Build
│   └── Job: Compilar e testar
│       ├── Tarefa: Checkout de código
│       └── Tarefa: Maven clean package
├── Estágio: Implantar no Staging
│   └── Job: Deploy
│       └── Tarefa: Implantar artefato no staging
└── Estágio: Testes de API
    └── Job: Executar suíte de API
        ├── Tarefa: Checkout de código
        ├── Tarefa: Instalar e executar Apidog CLI
        └── Artefato: Publicar relatório HTML
Enter fullscreen mode Exit fullscreen mode

Se o CLI retornar código diferente de zero, o Bamboo marca o estágio como falho e a build fica vermelha. Esse é o comportamento desejado: contrato quebrado deve bloquear o pipeline.

O CLI do Apidog executa os cenários que você cria visualmente no Apidog. Você modela a suíte uma vez e roda o mesmo teste localmente ou no Bamboo, seguindo o mesmo padrão usado para automatizar testes de API em CI/CD.

Passo 1: Crie os testes de API no Apidog

Abra o Apidog e crie um cenário de teste. Um cenário é uma sequência de requisições executadas em ordem, com possibilidade de reutilizar dados de etapas anteriores.

Exemplo de cenário para um serviço de pagamentos:

  1. POST /auth/login com credenciais válidas.
  2. Extrair o bearer token da resposta.
  3. POST /orders usando o token.
  4. Salvar o orderId retornado.
  5. GET /orders/{orderId} para validar o status do pedido.
  6. DELETE /orders/{orderId} para limpar os dados criados.

Para cada requisição, adicione asserções:

  • Status code igual a 200, 201 ou outro valor esperado.
  • Campo JSON existente, por exemplo $.data.status.
  • Valor específico, como $.data.status == "pending".
  • Corpo da resposta compatível com o schema OpenAPI.
  • Tempo de resposta abaixo de um limite, por exemplo 800ms.

Asserções baseadas em schema são especialmente úteis. Se o endpoint prometeu um formato no contrato, a resposta deve seguir esse formato. Isso captura campos renomeados, tipos incorretos e propriedades obrigatórias ausentes sem exigir scripts manuais.

Se tiver muitos cenários, agrupe-os em uma suíte. Assim, o comando no CI aponta para uma suíte em vez de listar vários cenários individualmente.

Também configure variáveis de ambiente para valores que mudam entre local, staging e produção:

  • baseUrl
  • credenciais
  • chaves de API
  • tokens
  • IDs de dados de teste

Crie um ambiente de staging no Apidog com baseUrl apontando para o host de staging. No Bamboo, você informará ao CLI qual ambiente usar.

Passo 2: Gere um token de acesso e obtenha os IDs

O agente do Bamboo roda sem interface gráfica, então ele precisa autenticar no Apidog via token.

No cenário de teste:

  1. Abra a aba CI/CD.
  2. Clique em Adicionar token de acesso.
  3. Clique em Gerar token.
  4. Copie o token temporariamente para um local seguro.

Ainda na aba CI/CD, selecione Linha de comando como provedor. O Apidog gera um comando com os IDs necessários.

Você vai precisar de três valores:

  • --access-token: token usado pelo agente do Bamboo.
  • -t: ID do cenário de teste.
  • -e: ID do ambiente, por exemplo staging.

Exemplo de estrutura do comando:

apidog run \
  --access-token "<token>" \
  -t 637132 \
  -e 358171
Enter fullscreen mode Exit fullscreen mode

Não cole o token diretamente no script do Bamboo. No próximo passo, ele será salvo como variável mascarada.

Passo 3: Salve o token como variável do Bamboo

Nunca coloque tokens diretamente em scripts versionados ou tarefas visíveis no plano.

No Bamboo:

  1. Abra o plano.
  2. Vá em Configuração do Plano.
  3. Acesse Variáveis.
  4. Crie uma variável chamada APIDOG_ACCESS_TOKEN.
  5. Cole o token como valor.

O Bamboo mascara variáveis cujos nomes contêm termos como password, secret ou token. Por isso, usar APIDOG_ACCESS_TOKEN ajuda a evitar exposição nos logs e na UI.

Em scripts, variáveis de plano ficam disponíveis com o prefixo bamboo_. Portanto:

$bamboo_APIDOG_ACCESS_TOKEN
Enter fullscreen mode Exit fullscreen mode

Use o mesmo padrão para outros segredos usados pelos testes, como senhas, API keys ou tokens de serviços externos.

Passo 4: Adicione o estágio de teste de API

Na configuração do plano do Bamboo:

  1. Adicione um estágio chamado Testes de API.
  2. Adicione um job, por exemplo Executar suíte de API.
  3. Dentro do job, adicione as tarefas abaixo.

Tarefa 1: Checkout de código

Mesmo que os testes estejam no Apidog, o checkout cria um diretório de trabalho limpo. Ele também permite versionar arquivos auxiliares, como CSVs de massa de teste.

Tarefa 2: Script

Adicione uma tarefa do tipo Script e use Shell, por exemplo /bin/sh.

O CLI do Apidog é um pacote npm, então o agente precisa de Node.js v16 ou superior. Se seus agentes já têm Node.js instalado, o script abaixo funciona diretamente.

#!/bin/sh
set -e

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

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

Substitua:

  • 637132 pelo ID real do cenário.
  • 358171 pelo ID real do ambiente de staging.

Flags usadas:

  • --access-token: lê o token mascarado do Bamboo.
  • -t: seleciona o cenário de teste.
  • -e: seleciona o ambiente.
  • -r cli,html: gera saída no console e relatório HTML.
  • --out-dir: define onde os relatórios serão salvos.

Para executar uma suíte inteira, use:

apidog run \
  --access-token "$bamboo_APIDOG_ACCESS_TOKEN" \
  --test-suite 123456 \
  -e 358171 \
  -r cli,html \
  --out-dir ./apidog-reports
Enter fullscreen mode Exit fullscreen mode

Para executar uma pasta de cenários:

apidog run \
  --access-token "$bamboo_APIDOG_ACCESS_TOKEN" \
  -f 123456 \
  -e 358171 \
  -r cli,html \
  --out-dir ./apidog-reports
Enter fullscreen mode Exit fullscreen mode

O set -e faz o shell parar no primeiro erro. Como o CLI retorna código diferente de zero quando uma asserção falha, o Bamboo também falha a build.

Se você já integrou testes de API com GitHub Actions, o fluxo é parecido. A diferença é que no Bamboo você configura as etapas pela UI em vez de YAML.

Passo 5: Publique o relatório como artefato

Uma build vermelha diz que algo falhou. O relatório HTML mostra o que falhou.

No mesmo job, vá até Artefatos e crie um artefato compartilhado:

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

Depois de cada build, o Bamboo coleta os arquivos de apidog-reports e os anexa ao resultado da build.

No relatório, você consegue verificar:

  • requisições executadas;
  • asserções aprovadas e reprovadas;
  • status code retornado;
  • tempo de resposta;
  • corpo da resposta em caso de falha.

Se quiser visualização nativa no Bamboo, gere também relatório JUnit:

apidog run \
  --access-token "$bamboo_APIDOG_ACCESS_TOKEN" \
  -t 637132 \
  -e 358171 \
  -r cli,html,junit \
  --out-dir ./apidog-reports
Enter fullscreen mode Exit fullscreen mode

Depois, adicione uma tarefa JUnit Parser apontando para o XML gerado. Assim, o Bamboo mostra contagens de testes, falhas e tendências no resumo da build.

Passo 6: Execute o plano e valide o resultado

Execute o plano manualmente na primeira vez.

No log do estágio Testes de API, você deve ver:

  1. instalação do apidog-cli;
  2. execução do cenário;
  3. lista de requisições;
  4. resultado das asserções;
  5. resumo final.

Caso 1: tudo passa

O CLI retorna 0, o estágio fica verde e o relatório HTML é publicado.

Depois disso, configure o plano para rodar automaticamente a cada commit:

  1. Vá em Configuração do Plano.
  2. Abra Gatilhos.
  3. Use polling de repositório ou webhook.
  4. Aplique o gatilho à branch principal ou às branches desejadas.

Caso 2: uma asserção falha

O CLI retorna código diferente de zero, o script para e o Bamboo marca a build como falha.

Exemplo de saída:

┌──────────────┬──────────┬──────────┐
│              │ 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"
Enter fullscreen mode Exit fullscreen mode

Abra o artefato HTML, encontre a requisição falha e inspecione a resposta capturada. Isso evita repetir manualmente a chamada só para entender o erro.

Boas práticas para evitar testes instáveis

Isole dados de teste

Cada execução deve criar os dados necessários e removê-los ao final. Evite depender de registros criados manualmente.

Bom padrão:

criar recurso -> validar recurso -> remover recurso
Enter fullscreen mode Exit fullscreen mode

Evite rodar testes automatizados contra produção. Use staging ou um ambiente dedicado de teste.

Use massa de dados para ampliar cobertura

Se o mesmo endpoint precisa ser testado com várias entradas, use execução orientada por dados em vez de duplicar cenários.

Exemplo:

apidog run \
  --access-token "$bamboo_APIDOG_ACCESS_TOKEN" \
  -t 637132 \
  -e 358171 \
  --iteration-data ./test-data/orders.csv \
  -r cli,html \
  --out-dir ./apidog-reports
Enter fullscreen mode Exit fullscreen mode

Versione o CSV no repositório para que a massa de teste acompanhe o código.

Esse é o mesmo padrão de teste orientado por dados usado localmente, aplicado no CI.

Fixe a versão do CLI

Para builds reproduzíveis, evite instalar sempre a versão mais recente:

npm install -g apidog-cli@<versão>
Enter fullscreen mode Exit fullscreen mode

Isso reduz o risco de uma atualização do CLI alterar o comportamento entre duas builds do mesmo commit.

Defina timeouts explícitos

Use timeout de requisição para falhar rápido quando um endpoint travar:

apidog run \
  --access-token "$bamboo_APIDOG_ACCESS_TOKEN" \
  -t 637132 \
  -e 358171 \
  --timeout-request 10000 \
  -r cli,html \
  --out-dir ./apidog-reports
Enter fullscreen mode Exit fullscreen mode

Uma falha clara por timeout é melhor do que uma build presa até o timeout global do Bamboo.

Use o estágio como gate de produção

Coloque Testes de API antes da implantação em produção. Se o estágio falhar, o Bamboo interrompe o plano e impede que um contrato quebrado siga adiante.

Essa é a versão prática de construir um pipeline de CI/CD real: não basta compilar; o pipeline precisa validar o comportamento exposto pela API.

Separe suítes rápidas e completas

Mantenha a suíte por commit focada nos caminhos críticos:

  • autenticação;
  • CRUD principal;
  • fluxo de pagamento;
  • endpoints consumidos por clientes externos;
  • contratos mais sensíveis.

Deixe casos extensivos e combinações de borda para execuções agendadas.

Conclusão

O Bamboo já protege seu projeto contra código que não compila e testes unitários que falham. Adicionar um estágio de teste de API estende essa proteção aos contratos HTTP que seus serviços expõem.

A configuração é direta:

  1. Crie cenários visuais no Apidog.
  2. Gere um token de acesso.
  3. Salve o token como variável mascarada no Bamboo.
  4. Adicione uma tarefa de script com apidog run.
  5. Publique o relatório HTML como artefato.
  6. Use o estágio como gate antes da produção.

Depois disso, cada push valida a API automaticamente. Se um campo mudar, um status code quebrar ou um fluxo autenticado falhar, a build fica vermelha antes que a regressão chegue aos usuários.

Baixe o Apidog, crie seu primeiro cenário e cole o comando CLI gerado em uma tarefa de script do Bamboo. A primeira regressão capturada já paga o tempo de configuração.

Top comments (0)