DEV Community

Cover image for Como Executar Testes Automatizados de API no TeamCity
Lucas
Lucas

Posted on • Originally published at apidog.com

Como Executar Testes Automatizados de API no TeamCity

Sua API pode passar em todos os testes no seu laptop e ainda quebrar em produção quando alguém renomeia um campo, altera um contrato ou muda um fluxo de autenticação. O problema não é só o bug: é depender de alguém lembrar de executar a suíte manualmente. A integração contínua existe para remover esse fator humano, e o TeamCity é uma boa opção para executar testes de API automaticamente a cada alteração.

Experimente o Apidog hoje

O TeamCity, servidor de CI/CD da JetBrains, executa pipelines de build quando o código é integrado. Ele pode compilar, testar, empacotar e implantar sem cliques manuais. Para APIs, o ponto crítico é incluir testes reais de contrato e comportamento no pipeline, não apenas testes unitários ou uma verificação de build.

Neste guia, você vai configurar testes de API automatizados no TeamCity usando o Apidog para projetar os cenários e o Apidog CLI para executá-los sem interface gráfica como uma etapa de build. O objetivo é simples: se a API quebrar, o build falha antes da mesclagem.

O que você vai construir

Ao final, você terá:

  • Um projeto TeamCity conectado ao seu repositório Git.
  • Uma configuração de build com gatilho VCS acionado a cada push.
  • Uma etapa de build executando sua suíte de testes de API via Apidog CLI.
  • Resultados de teste visíveis na aba Tests do TeamCity.
  • Um build que fica vermelho quando um endpoint quebra.
  • Um bloqueio de mesclagem baseado no status do TeamCity.

O mesmo padrão funciona para um serviço interno pequeno ou uma API pública com muitos endpoints. Você escala adicionando cenários no Apidog, não reescrevendo o pipeline.

Imagem do pipeline de testes de API

Por que executar testes de API no TeamCity

Teste local depende de disciplina individual. CI depende de configuração.

Com o TeamCity, cada commit executa a mesma suíte, no mesmo ambiente, com as mesmas asserções. Isso elimina o clássico “funciona na minha máquina” porque o comportamento esperado fica codificado no pipeline.

TeamCity executando testes de API

O TeamCity ajuda especialmente em pipelines de API por estes motivos:

  • Cadeias de build: você pode fazer os testes dependerem de uma implantação em staging.
  • Histórico de testes: o TeamCity rastreia quais testes falharam em builds anteriores.
  • Investigação e silenciamento: testes instáveis podem ser atribuídos e tratados sem bloquear todo mundo indefinidamente.
  • Pools de agentes: suítes pesadas podem rodar em agentes dedicados.

O TeamCity executa comandos. Então o trabalho principal é chegar a um comando confiável que:

  1. execute toda a suíte de API;
  2. retorne 0 quando tudo passar;
  3. retorne código diferente de zero quando alguma asserção falhar;
  4. gere um relatório em formato JUnit para o TeamCity processar.

É isso que o Apidog CLI fornece.

Passo 1: Projete os testes de API no Apidog

Antes de configurar o TeamCity, crie testes que possam rodar sem intervenção humana.

Um teste de CI não pode depender de alguém olhando um JSON manualmente. Cada validação precisa ser uma asserção objetiva, por exemplo:

  • status HTTP é 200;
  • campo id existe e é numérico;
  • resposta segue um JSON Schema;
  • tempo de resposta é menor que 800 ms;
  • array retornado contém pelo menos um item;
  • campo total corresponde à soma dos itens.

No Apidog, você monta requisições e adiciona asserções de API para validar respostas automaticamente. Também é possível encadear chamadas, por exemplo extraindo um token de login e reutilizando-o nas próximas requisições.

Um fluxo de e-commerce poderia ser:

  1. POST /auth/login

    • assert 200
    • extrair access_token para uma variável

  2. GET /products?category=books

    • enviar o token no header Authorization
    • assert 200
    • assert que a resposta é um array
    • assert que cada item tem price > 0

  3. POST /cart/items

    • enviar um ID de produto
    • assert 201
    • assert que o total do carrinho corresponde ao preço do item

  4. GET /cart

    • assert 200
    • assert que items.length === 1

Depois de validar os cenários, agrupe-os em uma suíte de testes. A suíte será executada com um único comando no TeamCity.

Essa abordagem evita manter dois conjuntos de testes: um na ferramenta visual para depuração manual e outro em código para CI. Os mesmos cenários usados durante desenvolvimento passam a ser a suíte automatizada.

Se você vem de uma abordagem code-first como REST Assured, o ganho prático é reduzir boilerplate de requisição, parsing e asserção para cada endpoint.

Você pode baixar o Apidog para acompanhar a configuração.

Passo 2: Execute o Apidog CLI localmente

Não depure o comando pela primeira vez dentro do TeamCity. Primeiro faça ele funcionar localmente.

Instale o CLI com npm:

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

Verifique a instalação:

apidog --version
Enter fullscreen mode Exit fullscreen mode

Agora execute sua suíte. O CLI pode rodar cenários ou suítes do seu projeto Apidog autenticando com um token de acesso, ou pode rodar a partir de um arquivo exportado.

A abordagem online costuma ser mais simples: os testes que a equipe edita no Apidog são os mesmos que rodam na CI.

Gere um token de acesso nas configurações da sua conta Apidog e execute:

apidog run \
  --access-token "$APIDOG_ACCESS_TOKEN" \
  -e "$APIDOG_ENV_ID" \
  -r cli,html,junit
Enter fullscreen mode Exit fullscreen mode

O que cada opção faz:

  • --access-token: autentica a execução.
  • -e: seleciona o ambiente, como staging ou produção somente leitura.
  • -r: define os relatórios gerados.
    • cli: saída no console.
    • html: relatório navegável.
    • junit: relatório XML que o TeamCity consegue processar.

O comportamento mais importante para CI é o código de saída:

  • 0: todos os testes passaram;
  • diferente de 0: alguma asserção falhou.

Esse código é o que faz o TeamCity marcar o build como falho.

Execução com dados de teste

Para testar muitas entradas sem duplicar cenários, use um arquivo CSV ou JSON:

apidog run \
  --access-token "$APIDOG_ACCESS_TOKEN" \
  -d test-data/checkout-cases.csv \
  -r cli,junit
Enter fullscreen mode Exit fullscreen mode

Isso é útil para validar:

  • vários IDs de produto;
  • payloads inválidos;
  • combinações de parâmetros;
  • casos de borda de autenticação;
  • diferentes perfis de usuário.

Quando o comando estiver verde localmente, copie-o. Ele será a base da etapa no TeamCity.

Passo 3: Conecte o TeamCity ao repositório

Agora configure o TeamCity para observar seu repositório e disparar builds automaticamente.

Para testes locais, você pode subir o servidor TeamCity com Docker:

docker run -d --name teamcity-server \
  -v ~/teamcity/datadir:/data/teamcity_server/datadir \
  -v ~/teamcity/logs:/opt/teamcity/logs \
  -p 8111:8111 \
  jetbrains/teamcity-server
Enter fullscreen mode Exit fullscreen mode

Acesse:

http://localhost:8111
Enter fullscreen mode Exit fullscreen mode

Conclua a configuração inicial e crie um projeto:

  1. Vá em Administration.
  2. Clique em Create project.
  3. Escolha From a repository URL.
  4. Cole a URL do repositório Git.
  5. Adicione credenciais se o repositório for privado.
  6. Crie a configuração de build.

Depois, configure o gatilho:

  1. Abra a build configuration.
  2. Vá em Triggers.
  3. Adicione um VCS Trigger.
  4. Mantenha a regra padrão para disparar a cada alteração na branch monitorada.

A partir daqui, cada push inicia um build. O próximo passo é adicionar a execução dos testes de API.

Passo 4: Adicione o Apidog CLI como etapa de build

Na configuração de build:

  1. Abra Build Steps.
  2. Clique em Add build step.
  3. Escolha Command Line.
  4. Selecione Custom script.
  5. Cole o script abaixo. 
#!/bin/bash
set -e

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

# Executa a suíte de API e gera relatório JUnit para o TeamCity
apidog run \
  --access-token "%env.APIDOG_ACCESS_TOKEN%" \
  -e "%env.APIDOG_ENV_ID%" \
  -r cli,junit \
  --out-dir reports
Enter fullscreen mode Exit fullscreen mode

Diferenças em relação ao comando local:

  • set -e faz o script parar no primeiro erro.
  • %env.APIDOG_ACCESS_TOKEN% e %env.APIDOG_ENV_ID% usam parâmetros do TeamCity.
  • --out-dir reports define onde o relatório será gravado.

Se o agente não tiver Node.js, use uma destas opções:

  • instale Node.js em uma etapa anterior;
  • use um agente que já inclua Node;
  • execute a etapa dentro de uma imagem Docker como node:20.

Exemplo de comando se você quiser validar localmente em um contêiner Node:

docker run --rm -it \
  -e APIDOG_ACCESS_TOKEN="$APIDOG_ACCESS_TOKEN" \
  -e APIDOG_ENV_ID="$APIDOG_ENV_ID" \
  node:20 bash
Enter fullscreen mode Exit fullscreen mode

Dentro do contêiner:

npm install -g apidog-cli

apidog run \
  --access-token "$APIDOG_ACCESS_TOKEN" \
  -e "$APIDOG_ENV_ID" \
  -r cli,junit \
  --out-dir reports
Enter fullscreen mode Exit fullscreen mode

Ordem correta do pipeline

O CLI deve rodar depois que a API estiver disponível.

Um fluxo comum é:

  1. compilar aplicação;
  2. subir serviço em staging;
  3. aguardar health check;
  4. executar testes de API;
  5. publicar resultado.

Se o TeamCity implanta sua API em staging, faça a build de teste depender da build de implantação com Snapshot Dependency ou Build Chain. Assim, os testes rodam contra a versão gerada pelo commit atual, não contra uma versão antiga.

Passo 5: Armazene segredos como parâmetros do TeamCity

O token do Apidog não deve ficar no script, no repositório ou nos logs.

Configure como parâmetro:

  1. Abra a build configuration.
  2. Vá em Parameters.
  3. Adicione env.APIDOG_ACCESS_TOKEN.
  4. Defina o tipo como Password.
  5. Cole o token de acesso.
  6. Adicione também env.APIDOG_ENV_ID.

O APIDOG_ENV_ID não é necessariamente secreto, mas deixá-lo como parâmetro facilita trocar o ambiente sem editar o script.

Se várias configurações usarem o mesmo token, defina os parâmetros no projeto pai. Assim, todas as builds herdam os valores.

Passo 6: Publique os resultados na aba Tests

Um build vermelho diz que algo falhou. Um relatório JUnit mostra exatamente o que falhou.

Resultados de testes no TeamCity

Como o comando usa -r junit, o Apidog CLI gera um XML em formato JUnit. Agora configure o TeamCity para ler esse arquivo:

  1. Abra Build Features.
  2. Clique em Add build feature.
  3. Escolha XML report processing.
  4. Em report type, selecione Ant JUnit.
  5. Em monitoring rules, use: 
reports/*.xml
Enter fullscreen mode Exit fullscreen mode

Execute um build e abra a aba Tests.

Você deve ver cenários e asserções com:

  • status de sucesso ou falha;
  • duração;
  • mensagem de erro;
  • histórico entre builds.

Sem JUnit, você teria apenas logs no console. Com JUnit, o TeamCity consegue mostrar algo como:

A asserção do total do carrinho começou a falhar no commit a3f9c2.

Isso reduz bastante o tempo de diagnóstico.

Passo 7: Faça o build falhar e bloqueie a mesclagem

O bloqueio acontece em duas camadas.

1. Código de saída do CLI

O Apidog CLI retorna código diferente de zero se qualquer asserção falhar.

Como o script usa:

set -e
Enter fullscreen mode Exit fullscreen mode

uma falha nos testes faz a etapa falhar, e a falha da etapa faz o build ficar vermelho.

Você não precisa adicionar lógica extra como:

if [ "$FAILED" = true ]; then exit 1; fi
Enter fullscreen mode Exit fullscreen mode

O CLI já faz isso.

2. Status no pull request

Para bloquear merges, configure o TeamCity para reportar o status ao GitHub, GitLab ou Bitbucket.

No TeamCity:

  1. Abra Build Features.
  2. Adicione Commit Status Publisher.
  3. Escolha seu provedor Git.
  4. Configure o token de acesso.
  5. Salve.

Depois, no provedor Git, configure regras de proteção de branch exigindo que o status do TeamCity passe antes da mesclagem.

Resultado:

  1. alguém abre um PR;
  2. o TeamCity executa a suíte de API;
  3. se um endpoint quebrar, o build falha;
  4. o botão de merge permanece bloqueado.

Exemplo de pipeline completo

Uma configuração realista pode ficar assim:

  • VCS root: repositório da API.
  • Trigger: VCS Trigger para branch principal e branches de PR.
  • Build step 1: compilar a aplicação.
  • Build step 2: implantar em staging ou iniciar serviço em contêiner.
  • Build step 3: aguardar health check.
  • Build step 4: executar apidog run.
  • Build feature: XML report processing lendo reports/*.xml.
  • Build feature: Commit Status Publisher.
  • Parameters:
    • env.APIDOG_ACCESS_TOKEN como senha.
    • env.APIDOG_ENV_ID como parâmetro comum.

Exemplo de health check antes dos testes:

#!/bin/bash
set -e

for i in {1..30}; do
  if curl -fsS https://staging.example.com/health; then
    echo "API disponível"
    exit 0
  fi

  echo "Aguardando API subir..."
  sleep 5
done

echo "API não ficou disponível a tempo"
exit 1
Enter fullscreen mode Exit fullscreen mode

Depois disso, rode:

apidog run \
  --access-token "%env.APIDOG_ACCESS_TOKEN%" \
  -e "%env.APIDOG_ENV_ID%" \
  -r cli,junit \
  --out-dir reports
Enter fullscreen mode Exit fullscreen mode

Pipeline completo no TeamCity

Configuração como código com Kotlin DSL

Se sua equipe versiona a configuração de CI, o TeamCity permite declarar o pipeline em Kotlin DSL dentro de .teamcity/settings.kts.

A etapa continua sendo o mesmo comando:

apidog run \
  --access-token "%env.APIDOG_ACCESS_TOKEN%" \
  -e "%env.APIDOG_ENV_ID%" \
  -r cli,junit \
  --out-dir reports
Enter fullscreen mode Exit fullscreen mode

O DSL apenas move a configuração da UI para código, permitindo revisão via pull request.

Execuções agendadas

Nem toda suíte precisa rodar a cada push.

Uma estratégia comum:

  • suíte de smoke rápida em todo push;
  • regressão completa durante a noite;
  • testes contra produção somente leitura em horário controlado.

No TeamCity, adicione um Schedule Trigger para executar a suíte completa diariamente contra staging.

Isso ajuda a detectar problemas que não vêm diretamente de um commit, como:

  • dependência externa alterada;
  • banco de dados em estado inconsistente;
  • credenciais expiradas;
  • ambiente de staging quebrado;
  • serviço de terceiros indisponível.

Comparação com outras plataformas de CI

O padrão é portável. O comando principal continua o mesmo:

apidog run \
  --access-token "$APIDOG_ACCESS_TOKEN" \
  -e "$APIDOG_ENV_ID" \
  -r cli,junit
Enter fullscreen mode Exit fullscreen mode

O que muda é onde ele é executado:

Se você ainda está escolhendo uma plataforma, esta comparação das melhores ferramentas de CI/CD mostra onde o TeamCity se encaixa.

O TeamCity tende a ser uma boa escolha para equipes que precisam de:

  • cadeias de build;
  • histórico granular de testes;
  • agentes dedicados;
  • configuração via Kotlin DSL;
  • integração forte com o ecossistema JetBrains.

Problemas comuns e como resolver

apidog: command not found

Causa provável:

  • Node.js não está instalado;
  • npm install -g apidog-cli não rodou;
  • o diretório global do npm não está no PATH.

Correções:

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

Ou execute a etapa em uma imagem node:20.

Testes passam localmente, mas falham na CI com erro de conexão

O agente do TeamCity provavelmente não consegue acessar sua API.

Verifique:

  • a URL base do ambiente selecionado com -e;
  • regras de firewall;
  • VPN;
  • allowlist de IPs;
  • DNS acessível a partir do agente;
  • se staging está realmente disponível antes do teste.

Adicione um health check antes do apidog run.

Autenticação falha apenas na CI

Verifique:

  • se o parâmetro se chama exatamente env.APIDOG_ACCESS_TOKEN;
  • se o script usa %env.APIDOG_ACCESS_TOKEN%;
  • se o token não expirou;
  • se ele foi criado para a conta/projeto correto;
  • se o valor não foi colado com espaços extras.

O prefixo env. importa no TeamCity.

A aba Tests está vazia

O TeamCity não encontrou o XML JUnit.

Verifique se o comando usa:

--out-dir reports
Enter fullscreen mode Exit fullscreen mode

E se o XML report processing monitora:

reports/*.xml
Enter fullscreen mode Exit fullscreen mode

Também confira nos logs se o arquivo foi gerado.

Testes instáveis

Causas comuns:

  • dependência de ordem entre cenários;
  • dados compartilhados;
  • endpoints lentos;
  • ambiente de staging instável;
  • tokens expirando durante a execução;
  • testes que dependem de horário.

Boas práticas:

  • cada cenário deve preparar seus próprios dados;
  • cada cenário deve limpar o que criou, quando necessário;
  • evite depender de dados residuais de execuções anteriores;
  • use asserções de tempo de resposta para identificar lentidão;
  • isole testes destrutivos de testes somente leitura.

O TeamCity também permite silenciar e investigar testes instáveis enquanto você corrige a causa raiz.

FAQ

Preciso escrever código para executar testes de API no TeamCity?

Não necessariamente. Você cria os testes no Apidog com asserções e executa tudo no TeamCity com apidog run.

O script do pipeline é basicamente o comando CLI, não um conjunto completo de testes escrito manualmente.

Posso rodar os mesmos testes em ambientes diferentes?

Sim. Defina ambientes no Apidog, como:

  • staging;
  • pré-produção;
  • produção somente leitura.

Depois altere o parâmetro:

-e "%env.APIDOG_ENV_ID%"
Enter fullscreen mode Exit fullscreen mode

Os mesmos cenários passam a usar outra URL base e outras variáveis de ambiente.

Como protejo o token de acesso?

Armazene o token como parâmetro do TeamCity com tipo Password.

Não faça isso:

apidog run --access-token "token-real-aqui"
Enter fullscreen mode Exit fullscreen mode

Faça isso:

apidog run --access-token "%env.APIDOG_ACCESS_TOKEN%"
Enter fullscreen mode Exit fullscreen mode

Um teste de API falho realmente bloqueia o merge?

Sim, se duas coisas estiverem configuradas:

  1. o Apidog CLI falha o build com código diferente de zero;
  2. seu provedor Git exige o status do TeamCity antes da mesclagem.

Com isso, PRs com testes de API falhando não podem ser mesclados.

É melhor rodar online ou com arquivo exportado?

Depende do fluxo da equipe.

Rodar online com token de acesso mantém o Apidog como fonte única da suíte. O que a equipe edita no Apidog é o que roda na CI.

Rodar com arquivo exportado versiona os testes junto com o código. Isso pode ser útil quando você quer que cada branch carregue uma versão específica da suíte.

Muitas equipes começam com execução online por ser mais simples de manter sincronizada.

Posso rodar uma suíte rápida a cada push e uma completa à noite?

Sim. Crie duas configurações ou dois gatilhos:

  • smoke tests com VCS Trigger;
  • regressão completa com Schedule Trigger.

Isso mantém feedback rápido nos PRs sem abrir mão de cobertura profunda.

Conclusão

Executar testes de API no TeamCity muda onde os bugs são encontrados. Em vez de um cliente descobrir que um campo foi renomeado ou que um fluxo quebrou, o build falha na branch, antes da mesclagem, com a asserção exata e o histórico no TeamCity.

A configuração principal tem três partes:

  1. testes com asserções reais criados no Apidog;
  2. um comando apidog run executável sem interface gráfica;
  3. uma build do TeamCity que roda o comando, processa JUnit e publica status no Git.

Depois de configurado, você aumenta a cobertura adicionando cenários no Apidog, não reescrevendo o pipeline. Prove o comando localmente, coloque-o no TeamCity e deixe a CI validar sua API em cada commit.

Top comments (0)