DEV Community

Cover image for Como Rodar Testes de API Automatizados no Bamboo CI?
Lucas
Lucas

Posted on • Originally published at apidog.com

Como Rodar Testes de API Automatizados no Bamboo CI?

Sua build está verde: testes unitários passaram, o JAR foi empacotado e o artefato foi implantado. Então a primeira requisição real chega à API de staging e um serviço downstream retorna 500, porque alguém alterou um campo da resposta há dois commits. A build disse que estava tudo bem. Não estava. Ela apenas nunca testou a API.

Experimente o Apidog hoje

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

Ao final, seu plano do Bamboo irá, a cada push:

  • chamar endpoints reais em staging;
  • validar códigos de status;
  • comparar corpos de resposta com o schema esperado;
  • falhar a build quando um contrato for quebrado;
  • anexar um relatório HTML da execução.

Se quiser acompanhar, baixe o Apidog. A parte do CLI é gratuita e aberta.

Por que executar testes de API no Bamboo

Testar APIs manualmente antes de um release não escala. Alguém precisa lembrar de abrir uma coleção, executar requisições e verificar respostas. Isso falha justamente quando o time mais precisa de previsibilidade: deploys rápidos, sexta-feira à tarde, hotfixes e mudanças em dependências.

Bamboo CI

O CI existe para remover essa variável humana. Seus testes unitários já rodam automaticamente. Seus testes de API devem seguir o mesmo padrão porque eles detectam problemas que a compilação não vê:

  • Contratos quebrados: um campo JSON muda de userId para user_id. O código compila, mas clientes podem quebrar.
  • Status codes 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 responder 401 para credenciais válidas.
  • Drift de ambiente: staging recebe uma configuração, feature flag ou dependência diferente do esperado.

A lógica é a mesma de adotar CI/CD: encontrar problemas cedo, quando ainda são baratos de corrigir.

Como os testes de API entram em um plano do Bamboo

No Bamboo, o trabalho é organizado assim:

Plan
└── Stage
    └── Job
        └── Task
Enter fullscreen mode Exit fullscreen mode

Os testes de API entram como uma task dentro de um job, normalmente em uma stage executada depois do deploy em staging.

Bamboo task

Um pipeline típico fica assim:

Plan: payments-service
├── Stage: Build
│   └── Job: Compile & Unit Test
│       ├── Task: Source Code Checkout
│       └── Task: Maven clean package
├── Stage: Deploy to Staging
│   └── Job: Deploy
│       └── Task: Deploy artifact to staging
└── Stage: API Tests
    └── Job: Run API Suite
        ├── Task: Source Code Checkout
        ├── Task: Script, install & run Apidog CLI
        └── Task: Publish test report
Enter fullscreen mode Exit fullscreen mode

Se a task de testes de API retornar um código diferente de zero, o Bamboo marca a stage como falha e a build fica vermelha. Esse é o comportamento desejado: contrato quebrado deve bloquear o pipeline.

O Apidog CLI executa, via linha de comando, cenários criados visualmente no Apidog. Você modela o teste uma vez na interface e roda o mesmo cenário localmente, no Bamboo ou em qualquer outro sistema de CI/CD. É o mesmo padrão usado para automatizar testes de API em pipelines CI/CD.

Passo 1: Crie os testes de API no Apidog

Antes de rodar testes no CI, você precisa criar os cenários.

No Apidog, crie um cenário de teste com uma sequência de requisições. Um fluxo realista para um serviço de pagamentos pode ser:

  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 pedido.
  6. DELETE /orders/{orderId} para limpeza.

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

  • status code igual a 200 ou 201;
  • campo JSON existente, por exemplo $.data.status;
  • valor esperado, por exemplo $.data.status == "pending";
  • resposta compatível com o schema OpenAPI;
  • tempo de resposta abaixo de um limite, por exemplo 800ms.

As validações baseadas em schema são especialmente úteis. Como o Apidog trabalha com a definição da API, você pode validar se a resposta segue o contrato esperado sem escrever scripts de asserção. Isso ajuda a detectar:

  • campos renomeados;
  • propriedades obrigatórias ausentes;
  • tipos incorretos;
  • mudanças incompatíveis no payload.

Esse modelo visual é um dos motivos pelos quais o Apidog é usado como alternativa ao Postman para testes de API.

Se tiver muitos cenários, agrupe-os em uma suite. Assim, no Bamboo, você executa uma suite inteira em vez de listar cenários individualmente.

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

  • baseUrl;
  • credenciais;
  • API keys;
  • tokens;
  • IDs de tenant ou workspace.

Crie um ambiente de staging no Apidog com baseUrl apontando para o host de staging. O CLI usará esse ambiente durante a execução no Bamboo.

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

O agente do Bamboo roda sem interface gráfica. Ele não faz login no Apidog via navegador. Por isso, o Apidog CLI usa um token de acesso.

No Apidog:

  1. Abra o cenário ou suite de teste.
  2. Vá para a aba CI/CD.
  3. Clique em Adicionar token de acesso.
  4. Clique em Gerar token.
  5. Copie o token temporariamente.

Você não deve colar esse token diretamente no script. Ele será armazenado como variável mascarada no Bamboo.

Ainda na aba CI/CD, selecione Command line como provedor. O Apidog gera um comando de execução com os IDs necessários.

Você precisa identificar:

  • --access-token: token usado para autenticação;
  • -t: ID do cenário de teste;
  • -e: ID do ambiente, por exemplo staging.

Exemplo conceitual:

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

Guarde os IDs. Eles serão usados na task de script do Bamboo.

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

Não coloque tokens no script do pipeline. Isso expõe o segredo para quem consegue ler a configuração do plano ou os logs da build.

No Bamboo:

  1. Abra o plano.
  2. Vá para Plan Configuration.
  3. Abra a aba Variables.
  4. Crie uma variável chamada: 
APIDOG_ACCESS_TOKEN
Enter fullscreen mode Exit fullscreen mode
  1. Cole o token como valor.

O Bamboo mascara variáveis com nomes que contêm termos como password, secret ou token. Usar APIDOG_ACCESS_TOKEN ajuda a manter o valor oculto nos logs e na interface.

Durante a execução, essa variável fica disponível no shell como:

$bamboo_APIDOG_ACCESS_TOKEN
Enter fullscreen mode Exit fullscreen mode

Use esse valor no script, nunca o token literal.

A mesma prática vale para outros segredos usados pelos testes:

  • senhas;
  • chaves de API;
  • secrets de assinatura;
  • credenciais de banco;
  • tokens de serviços externos.

Passo 4: Adicione a stage de testes de API no Bamboo

Agora conecte o teste ao plano.

No Bamboo:

  1. Abra a configuração do plano.
  2. Crie uma nova stage chamada API Tests.
  3. Adicione um job, por exemplo Run API Suite.
  4. Dentro do job, adicione as tasks abaixo.

Task 1: Source Code Checkout

Mesmo que os testes estejam no Apidog, o checkout mantém um diretório de trabalho limpo no agente. Ele também permite versionar arquivos auxiliares, como CSVs usados em testes orientados a dados.

Task 2: Script

Adicione uma task do tipo Script.

Use:

  • Interpreter: Shell ou /bin/sh;
  • Script body: inline.

O agente precisa ter Node.js v16 ou superior, porque o Apidog CLI é instalado via npm. Se seus agentes já têm Node.js, use o script abaixo. Caso contrário, provisione Node.js nas capabilities do Bamboo ou use um agente baseado em Docker.

#!/bin/sh
set -e

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

# Executa o cenário contra staging e gera relatórios 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 outros escopos:

# Executar uma suite
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 
# Executar uma pasta de cenários
apidog run \
  --access-token "$bamboo_APIDOG_ACCESS_TOKEN" \
  -f 987654 \
  -e 358171 \
  -r cli,html \
  --out-dir ./apidog-reports
Enter fullscreen mode Exit fullscreen mode

O set -e é importante: ele encerra o script no primeiro comando com falha. Como o Apidog CLI retorna código diferente de zero quando uma asserção falha, o Bamboo marca a build como falha automaticamente.

Se você já configurou testes de API no GitHub Actions, o fluxo é parecido. O executor e as flags são os mesmos; muda apenas o formato de configuração do CI.

Passo 5: Publique o relatório como artefato do Bamboo

Uma build vermelha mostra que algo quebrou. O relatório HTML mostra exatamente o que quebrou.

No mesmo job, configure um artefato compartilhado:

  • Name: Relatório de Teste Apidog
  • Location: apidog-reports
  • Copy pattern: **/*

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

No relatório, você consegue inspecionar:

  • requisições executadas;
  • asserções feitas;
  • status codes recebidos;
  • payloads de resposta;
  • mensagens de erro;
  • etapa exata que falhou.

Isso reduz o tempo de debug, porque você não precisa reproduzir manualmente a requisição para descobrir qual resposta a API retornou no CI.

Se quiser integração mais nativa com o Bamboo, gere também 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 task JUnit Parser apontando para o XML gerado. Assim, o Bamboo mostra contagem de testes, falhas e tendências no resumo da build.

Passo 6: Execute o plano e valide o resultado

Rode o plano manualmente na primeira vez.

No Bamboo, clique em Run plan e acompanhe o log da stage API Tests.

Você deve ver:

  1. instalação do Apidog CLI via npm;
  2. início da execução do cenário;
  3. lista de requisições;
  4. resultado das asserções;
  5. resumo final.

Quando tudo passa

Se todas as asserções passam:

  • o CLI retorna 0;
  • a stage fica verde;
  • a build é aprovada;
  • o relatório HTML é publicado como artefato.

Depois disso, automatize a execução por commit:

  1. Abra Plan Configuration.
  2. Vá em Triggers.
  3. Configure polling do repositório ou webhook.
  4. Aplique o trigger na branch principal.

A partir daí, cada push executa os testes de API sem intervenção manual.

Quando uma asserção falha

Se uma asserção falha:

  • o CLI retorna código diferente de zero;
  • set -e encerra o script;
  • a stage fica vermelha;
  • a build falha;
  • o relatório mostra a requisição e a resposta capturada.

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 igual a "pending", mas obteve "failed"
Enter fullscreen mode Exit fullscreen mode

Esse é o objetivo da stage: detectar uma regressão de contrato que compilou sem erro e passou pelos testes unitários.

Boas práticas para uma suite estável no CI

Testes de API instáveis fazem o time ignorar builds vermelhas. Para evitar isso, siga alguns padrões.

Isole dados de teste

Cada execução deve criar os dados de que precisa e limpar tudo no final.

Bom fluxo:

POST /orders
GET /orders/{orderId}
DELETE /orders/{orderId}
Enter fullscreen mode Exit fullscreen mode

Evite depender de registros criados manualmente ou de dados antigos em staging.

Use ambiente dedicado

Rode contra staging ou um ambiente de testes. Evite produção.

Isso reduz risco e permite limpar dados com segurança.

Use testes orientados a dados

Se você precisa testar o mesmo endpoint com várias entradas, evite duplicar cenários.

Use um CSV versionado no repositório:

email,expectedStatus
valid-user@example.com,200
invalid-user@example.com,401
blocked-user@example.com,403
Enter fullscreen mode Exit fullscreen mode

Execute com:

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

Esse é o mesmo padrão de testes de API orientados a dados, só que executado no CI.

Fixe a versão do CLI

Este comando instala sempre a versão mais recente:

npm install -g apidog-cli
Enter fullscreen mode Exit fullscreen mode

Para builds reproduzíveis, fixe uma versão conhecida:

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

Assim, uma atualização do CLI não muda o comportamento da build sem controle.

Configure timeouts

Evite builds presas por endpoints travados.

Exemplo:

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

Um erro claro de timeout é melhor do que uma build parada até o limite global do Bamboo.

Bloqueie deploys de produção

A stage de API Tests deve rodar antes do deploy em produção. Se ela falhar, o plano deve parar.

Esse é o uso prático de um pipeline real de CI/CD: não basta compilar; o pipeline precisa validar se o serviço entregue ainda cumpre o contrato.

Mantenha a suite rápida

A suite executada a cada commit deve cobrir os fluxos críticos:

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

Deixe casos de borda extensos para execuções agendadas, como nightly builds.

Conclusão

O Bamboo já protege seu projeto contra código que não compila e testes unitários quebrados. Ao adicionar uma stage de testes de API, você também protege os contratos HTTP que seus clientes realmente consomem.

O fluxo é direto:

  1. crie cenários visuais no Apidog;
  2. adicione asserções de status, payload e schema;
  3. gere um token de acesso;
  4. salve o token como variável mascarada no Bamboo;
  5. adicione uma task de script com apidog run;
  6. publique o relatório como artefato;
  7. bloqueie deploys quando a stage falhar.

Depois disso, cada push valida sua API automaticamente. Se um contrato quebrar, a build fica vermelha antes que o problema chegue aos usuários.

Baixe o Apidog, crie seu primeiro cenário de teste e cole o comando do CLI em uma task do Bamboo. A primeira regressão detectada antes do deploy já compensa a configuração.

Top comments (0)