Blog

Como Executar Testes Automatizados de API no TeamCity

Executar testes de API automatizados no TeamCity de ponta a ponta: projetar testes no Apidog, executá-los em modo headless com a CLI do Apidog, analisar resultados JUnit e bloquear mesclagens indesejadas.

Ashley Innocent

Ashley Innocent

15 junho 2026

Como Executar Testes Automatizados de API no TeamCity

Apidog para empresas

Implantação local

SSO & RBAC

Conforme SOC 2

Explorar Apidog Enterprise

Sua API passa em todos os testes no seu laptop. Então, um colega de equipe mescla uma branch que renomeia um campo, e ninguém percebe até que um cliente mobile comece a falhar em produção. O teste manual não detectou isso porque ninguém reexecutou a suíte. Essa é a lacuna exata que a integração contínua foi construída para fechar, e o TeamCity é uma das ferramentas mais fortes para isso.

O TeamCity, servidor de CI/CD da JetBrains, executa seu pipeline de build toda vez que o código é integrado. Ele pode compilar, testar, empacotar e implantar sem que ninguém precise clicar em um botão. A parte que as equipes frequentemente pulam é a integração de testes de API reais nesse pipeline. Eles testam unidades, verificam se o build compila e entregam a API na base da fé. Um campo renomeado, um erro 500 em um caso de borda, um fluxo de autenticação quebrado; nada disso aparece até que um humano acesse o endpoint.

Este guia mostra como executar testes de API automatizados no TeamCity, do início ao fim. Você projetará e validará seus testes no Apidog, e então os executará sem interface gráfica através do Apidog CLI como uma etapa de build do TeamCity. O resultado é um pipeline que falha o build no momento em que sua API para de se comportar, antes que uma resposta ruim chegue a um usuário.

botão

O que você vai construir

Ao final, você terá:

O mesmo padrão funciona para um pequeno serviço interno ou uma API pública com centenas de endpoints. Você o escala adicionando cenários de teste no Apidog, e não editando o código do pipeline.

Por que os testes de API devem estar no TeamCity, e não apenas na sua máquina

O teste local tem uma falha fatal: ele depende de alguém se lembrar de executá-lo. A CI remove o humano do processo. Cada commit aciona a mesma suíte, no mesmo ambiente, com as mesmas asserções. Não existe "funciona na minha máquina" porque não há máquina; há um agente de build que executa os passos exatos que você definiu.

O TeamCity é uma boa opção para isso por algumas razões concretas:

O problema é que o TeamCity não sabe como chamar sua API ou verificar a resposta. Ele executa qualquer comando que você lhe dê. Portanto, o verdadeiro trabalho é produzir um único comando que execute toda a sua suíte de API e saia com um código diferente de zero quando algo falhar. É aí que o design do teste importa.

Passo 1: Projete e valide seus testes de API no Apidog

Antes que qualquer coisa toque o TeamCity, você precisa de testes que realmente funcionem sem supervisão. Um teste que exige que você inspecione visualmente uma resposta JSON é inútil na CI. Cada verificação precisa ser uma asserção que a máquina possa avaliar: o código de status é 200, o campo id é um número, a resposta veio em menos de 800 ms.

O Apidog foi construído exatamente para isso. Você projeta a requisição e, em seguida, anexa asserções de API que validam a resposta automaticamente; códigos de status, conformidade com JSON Schema, valores de campo específicos, tempo de resposta. Você pode encadear requisições em um cenário para que a saída de uma chamada de login alimente o token na próxima requisição. Nenhum script é necessário para os casos comuns, e scripting completo está disponível quando você precisar.

Um cenário realista para uma API de e-commerce pode parecer com isto:

  1. POST /auth/login com credenciais de teste, asserir 200, extrair o token bearer para uma variável.
  2. GET /products?category=books com esse token, asserir 200, asserir que a resposta é um array, asserir que cada item tem um price maior que 0.
  3. POST /cart/items com um ID de produto, asserir 201, asserir que o total do carrinho retornado corresponde ao preço do item.
  4. GET /cart, asserir que a contagem de itens é 1.

Cada etapa possui asserções que passam ou falham por si só. Execute o cenário dentro do Apidog primeiro e confirme que ele está verde contra seu ambiente de staging. Se não conseguir passar quando você o executa manualmente, nunca passará na CI. Agrupe cenários relacionados em uma suíte de testes para que você possa executar tudo com um único comando, em vez de cenário por cenário.

A vantagem de construir testes dessa forma é que os mesmos cenários que você usa para depuração manual se tornam sua suíte de CI. Você não mantém dois conjuntos paralelos de testes; um em uma GUI para exploração, outro em código para automação. É uma única fonte de verdade. Se você vem de um framework code-first como o REST Assured, esta é a parte que economiza mais tempo: você para de escrever e reescrever código boilerplate de requisição/asserção para cada endpoint.

Baixe o Apidog se quiser acompanhar. É gratuito para começar, e o CLI faz parte da mesma ferramenta.

Passo 2: Faça o Apidog CLI funcionar localmente primeiro

Nunca depure um novo comando pela primeira vez dentro da CI. O ciclo de feedback em um servidor de CI é brutal; você faz um push, espera por um agente, lê um log, corrige um caractere, faz push novamente. Prove que o comando funciona na sua máquina, e então copie a versão funcional para o TeamCity.

O Apidog CLI roda em Node.js, então instale-o globalmente com npm:

npm install -g apidog-cli

Confirme se está lá:

apidog --version

Agora, execute seu cenário de teste. O CLI pode executar um cenário ou suíte diretamente do seu projeto Apidog, referenciando seu ID, autenticado com um token de acesso, ou de um arquivo local exportado. A abordagem online mantém seus testes como a única fonte de verdade; o que sua equipe edita no Apidog é o que roda na CI, sem nenhuma etapa de exportação para esquecer.

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

Algumas coisas a serem observadas aqui:

Quando a execução termina, o CLI sai com 0 se tudo passou e diferente de zero se alguma asserção falhou. Esse código de saída é tudo na CI: uma saída diferente de zero é o que diz ao TeamCity para marcar o build como falho.

Para testes que precisam ser executados com muitas entradas, o CLI suporta execuções baseadas em dados. Aponte-o para um arquivo CSV ou JSON e ele iterará o cenário uma vez por linha:

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

É assim que você testa cem IDs de produto ou uma tabela de payloads inválidos sem escrever cem cenários. Cada linha se torna sua própria iteração com seu próprio resultado de sucesso/falha.

Assim que você vir a saída verde localmente, você terá um comando em que confia. Copie-o. Esse comando exato é o que vai para o TeamCity.

Passo 3: Conecte o TeamCity ao seu repositório

Agora, mude para o TeamCity. O objetivo desta etapa é dar ao TeamCity um projeto, apontá-lo para o seu código e permitir que ele acione builds a cada push.

Se você está executando o TeamCity pela primeira vez, o caminho mais simples é a imagem oficial do Docker. Ela te dá um servidor funcional em alguns minutos:

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

Abra http://localhost:8111, complete a configuração inicial (escolha do banco de dados, conta de administrador), e você chegará ao painel. Configurações de produção usam um banco de dados externo adequado e agentes de build dedicados, mas para seguir este guia o agente embutido é suficiente.

Crie o projeto:

  1. Vá para Administração e escolha Criar projeto.
  2. Selecione De um URL de repositório e cole seu repositório Git remoto (HTTPS ou SSH).
  3. Adicione credenciais se o repositório for privado; uma chave de implantação ou um token de acesso pessoal.
  4. O TeamCity escaneia o repositório e deve detectar automaticamente as etapas de build. Você pode deixar que ele faça isso, mas para testes de API é mais limpo configurar a etapa você mesmo na próxima seção.

O TeamCity cria um VCS root (sua conexão com o seu repositório) e uma configuração de build (o conjunto de etapas que são executadas). Com o VCS root configurado, configure o gatilho para que os builds sejam acionados automaticamente:

  1. Abra sua configuração de build e vá para Gatilhos (Triggers).
  2. Adicione um Gatilho VCS (VCS Trigger).
  3. Deixe a regra padrão para que cada alteração na branch observada enfileire um build.

A partir daqui, cada push para o seu repositório iniciará um build. No momento, esse build não faz nada útil; a próxima etapa lhe dará o comando de teste de API.

Passo 4: Adicione o Apidog CLI como uma etapa de build

Este é o cerne da configuração. Você está adicionando uma etapa de build que instala o CLI no agente e executa sua suíte.

Na sua configuração de build, abra Etapas de Build (Build Steps) e adicione uma nova etapa do tipo Linha de Comando (Command Line). Escolha script personalizado (Custom script) e cole:

#!/bin/bash
set -e

# Install the Apidog CLI on the build agent
npm install -g apidog-cli

# Run the API test suite and emit a JUnit report for TeamCity
apidog run \
 --access-token "%env.APIDOG_ACCESS_TOKEN%" \
 -e "%env.APIDOG_ENV_ID%" \
 -r cli,junit \
 --out-dir reports

Esse é o mesmo comando que você provou localmente, com duas alterações para a CI. Primeiro, set -e faz com que o script seja abortado em caso de erro. Segundo, os segredos são referenciados como parâmetros do TeamCity (%env.APIDOG_ACCESS_TOKEN%) em vez de estarem codificados; você os definirá a seguir.

Se o seu agente de build ainda não tiver o Node.js, instale-o antes na cadeia ou use uma imagem de agente que o inclua. As imagens Docker oficiais do agente TeamCity e a maioria dos pools de agentes em nuvem vêm com o Node disponível. Você também pode executar a etapa inteira dentro de um contêiner Node, configurando a etapa para ser executada em uma imagem Docker como node:20.

Um detalhe importante: o CLI deve ser executado depois que sua API for implantada e estiver acessível. Se o TeamCity estiver testando um serviço que acabou de implantar em staging, faça o build de teste depender do build de implantação usando uma Dependência de Snapshot ou uma Cadeia de Build. Isso garante que os testes sempre atinjam a versão da API produzida por este commit, e nunca a anterior.

Passo 5: Armazene segredos como parâmetros do TeamCity

Seu token de acesso é uma credencial. Ele não deve estar no script de build, no seu repositório ou no log de build. O TeamCity tem um lugar de primeira classe para isso.

  1. Na sua configuração de build (ou no projeto pai, para compartilhar entre configurações), abra Parâmetros (Parameters).
  2. Adicione um novo parâmetro chamado env.APIDOG_ACCESS_TOKEN.
  3. Defina seu Tipo (Spec) como Senha (Password). Isso mascara o valor na UI e o remove dos logs de build.
  4. Cole seu token de acesso Apidog como o valor.
  5. Adicione env.APIDOG_ENV_ID da mesma forma com seu ID de ambiente (este não é secreto, mas mantê-lo como um parâmetro permite alterar ambientes sem editar o script).

Defini-los no nível do projeto, em vez do nível da configuração de build, significa que cada build de teste de API sob esse projeto os herda. Gire o token uma vez, e cada pipeline pegará o novo valor.

Um parâmetro de senha é a diferença entre um token que vive com segurança no TeamCity e um que vaza para um arquivo de log que toda a equipe pode ler. Trate-o da mesma forma que você trataria uma senha de banco de dados.

Passo 6: Mostre os resultados dos testes na aba Testes do TeamCity

Um build que fica vermelho apenas informa que algo quebrou. Um build que mostra qual teste quebrou diz onde procurar. Isso é o que o relatório JUnit lhe dá.

O relator -r junit escreve um arquivo XML no formato JUnit, o formato padrão de resultados de teste de CI que o TeamCity lê nativamente. Você aponta o TeamCity para esse arquivo com um recurso de build de Processamento de Relatório XML.

  1. Abra Recursos de Build (Build Features) na sua configuração de build.
  2. Adicione Processamento de relatório XML (XML report processing).
  3. Defina o tipo de relatório para Ant JUnit.
  4. Defina o caminho de monitoramento para corresponder à sua saída, por exemplo reports/*.xml.

Execute um build. Abra-o e clique na aba Testes (Tests). Você verá cada cenário e asserção como um teste individual com status de sucesso/falha e tempo. Quando um teste falha, o TeamCity mostra a mensagem de falha em linha, o vincula ao commit que a introduziu e o rastreia em builds futuros. Se o mesmo teste falhar duas vezes seguidas, o TeamCity pode marcá-lo como uma nova falha, em vez de uma falha intermitente.

Esta é a recompensa por escolher a saída JUnit anteriormente. Sem ela, uma falha é um build vermelho e uma parede de texto no console. Com ela, você obtém um histórico de testes estruturado e pesquisável que transforma "o build da API está quebrado" em "a asserção do total do carrinho começou a falhar no commit a3f9c2."

Passo 7: Falhe o build e bloqueie a mesclagem

O objetivo de tudo isso é impedir que código ruim seja mesclado. Duas coisas fazem isso acontecer.

Primeiro, o código de saída. Como o Apidog CLI sai com um código diferente de zero em qualquer asserção falha e seu script usa set -e, um teste falho faz a etapa de build falhar, o que faz o build falhar. Você não precisa configurar nada extra; um teste de API vermelho é um build vermelho por padrão.

Segundo, o portão de mesclagem. Se sua equipe trabalha com pull requests ou merge requests, configure seu host Git (GitHub, GitLab, Bitbucket) para exigir que a verificação do TeamCity passe antes da mesclagem. O TeamCity reporta o status do seu build de volta ao commit através de um recurso de build Editor de Status de Commit (Commit Status Publisher):

  1. Adicione o recurso de build Editor de Status de Commit (Commit Status Publisher).
  2. Selecione seu provedor de hospedagem VCS.
  3. Adicione um token de acesso para que o TeamCity possa postar status.

Agora um colaborador abre um PR, o TeamCity executa a suíte de API contra sua branch, e o botão de mesclagem permanece desabilitado até que a suíte esteja verde. O cenário de campo renomeado do início deste guia é detectado aqui, na branch, antes mesmo de chegar à main.

Um pipeline completo realista

Juntando as peças, uma configuração de build funcional para um pipeline de testes de API se parece com isto:

Para equipes que mantêm toda a sua configuração de CI no controle de versão, o TeamCity suporta a definição de tudo isso em um DSL Kotlin (.teamcity/settings.kts) commitado no repositório, em vez de clicar na UI. A etapa de build é o mesmo comando apidog run de qualquer forma; o DSL apenas descreve a configuração como código para que seja revisada e versionada junto com todo o resto.

Você pode executar a suíte em mais do que apenas a cada push. Adicione um Gatilho de Agendamento (Schedule Trigger) para executar a suíte de regressão completa todas as noites contra o ambiente de staging, para que você detecte desvios que acontecem entre commits; uma dependência de terceiros que mudou, um banco de dados que entrou em um estado estranho. As execuções noturnas da API são um seguro barato e impedem que o primeiro commit da manhã herde o ambiente quebrado do dia anterior.

Como isso se compara a outras plataformas de CI

O padrão aqui é portátil. O comando que executa seus testes (apidog run com um token de acesso e um relator JUnit) é idêntico, não importa qual servidor de CI o invoque. Apenas o invólucro muda:

Se você ainda está escolhendo um servidor de CI, nossa comparação das melhores ferramentas de CI/CD detalha onde o TeamCity se encaixa em relação às alternativas. Os pontos fortes do TeamCity são suas cadeias de build, histórico de testes granular e o DSL Kotlin; é uma excelente escolha para equipes já no ecossistema JetBrains ou que executam pipelines complexos de múltiplas etapas.

Problemas comuns e como resolvê-los

FAQ

Conclusão

Um pipeline do TeamCity que executa seus testes de API a cada commit muda a economia de um endpoint quebrado. Em vez de um cliente encontrar o bug, o build o encontra; na branch, antes da mesclagem, com a asserção exata falha e o commit que a causou, tudo detalhado na aba Testes.

A configuração se resume a três partes principais: testes com asserções reais que você constrói no Apidog, um único comando apidog run que os executa sem interface gráfica e sai com um código diferente de zero em caso de falha, e uma configuração de build do TeamCity que executa esse comando, analisa os resultados do JUnit e reporta o status de volta ao seu host Git. Uma vez implementado, você mantém a cobertura adicionando cenários no Apidog, e não mexendo no código do pipeline.

Baixe o Apidog para projetar sua primeira suíte de testes, prove o comando CLI localmente e, em seguida, insira-o no TeamCity. A partir desse ponto, sua API será testada da mesma forma em cada commit, independentemente de alguém se lembrar de executá-la ou não.

botão

Pratique o design de API no Apidog

Descubra uma forma mais fácil de construir e usar APIs

Cadastre-se gratuitamenteBaixar