Testes de Regressão de API: Como Identificar Erros Críticos Antecipadamente

Você envia uma pequena alteração para um endpoint. O código compila, o novo recurso funciona e você implanta. Dois dias depois, um cliente móvel começa a travar porque um campo que você renomeou costumava ser uma string e agora é um objeto. Ninguém pretendia quebrá-lo. A mudança parecia local. Não era.

O teste de regressão de API existe para detectar essa classe de falha antes que ela atinja qualquer pessoa. Você salva um conjunto de testes que descrevem como sua API se comporta hoje e, em seguida, executa esse conjunto em cada alteração. Quando um formato de resposta, código de status ou valor de chave difere do que você registrou, o conjunto falha e informa exatamente onde. Este guia abrange o que é o baseline, como construir um conjunto reutilizável e como executá-lo automaticamente na CI para que um renomear nunca se torne um incidente.

botão

O que é teste de regressão de API (e por que as APIs regridem)

Teste de regressão significa reexecutar testes que já passaram para confirmar que o comportamento existente ainda se mantém após uma alteração. Para APIs, o "comportamento existente" é o contrato do qual seus consumidores dependem: as rotas, os códigos de status, o esquema de resposta e os valores nos campos-chave.

As APIs regridem por razões comuns. Alguém renomeia um campo JSON. Uma refatoração muda um 200 para um 204. Uma nova regra de validação rejeita uma entrada que antes era aceita. Uma atualização de ORM muda silenciosamente a formatação de datas. Uma atualização de dependência altera uma mensagem de erro que um cliente interpreta. Nenhuma dessas alterações aparece como erros de compilação. Elas aparecem como integrações quebradas, e muitas vezes apenas para um subconjunto de chamadores.

A distinção importante aqui: o teste de regressão de API é mais restrito do que o teste de regressão de software geral. Você não está reverificando a lógica de negócios em todo o aplicativo. Você está verificando se a superfície HTTP, a parte à qual outros sistemas se acoplam, não mudou. Esse foco é o que o torna barato para ser executado em cada commit.

O que definir como baseline

Um conjunto de regressão é tão bom quanto o que ele afirma. Afirmar pouco e as quebras reais passam. Afirmar demais e toda mudança intencional torna o conjunto vermelho. Procure os campos que um consumidor realmente notaria.

Defina o baseline para estas quatro camadas:

Códigos de status. Cada endpoint deve retornar um status conhecido para entradas conhecidas. Um 200 que se torna um 500, ou um 201 que se torna um 200, é uma regressão, mesmo que o corpo pareça bom.
Esquema de resposta. A estrutura e os tipos da resposta. Nomes de campos, aninhamento e se um valor é uma string, número, array ou objeto. A deriva de esquema é a quebra silenciosa mais comum.
Valores de campos-chave. Não todos os valores, mas aqueles com significado contratual: um id que deve estar presente, um enum de status que deve permanecer dentro de um conjunto conhecido, um total que deve ser um número.
Contratos. A relação entre sua especificação OpenAPI e a resposta ao vivo. Se a especificação diz que o email é obrigatório e a API para de retorná-lo, isso é uma violação de contrato. Veja teste de contrato de API para saber como tornar a especificação a fonte da verdade.

Uma regra útil: afirme o que um cliente quebraria, não o que por acaso está no payload hoje. Um timestamp createdAt muda a cada requisição, então fixe seu tipo e formato, não seu valor.

Aqui está um conjunto mínimo de afirmações para um único endpoint, escrito como verificações simples que você executaria em uma resposta:

GET /v1/users/42  ->  200
  body.id            está presente, tipo número
  body.email         está presente, tipo string, corresponde ao formato de e-mail
  body.status        é um de ["active", "pending", "suspended"]
  body.roles         tipo array
  response time      < 800 ms

Essas cinco linhas descrevem o contrato. Se alguma delas falhar após uma alteração, você tem uma regressão. Para um tratamento mais aprofundado sobre como escrever verificações contra corpos de resposta, veja asserções de API.

Teste de regressão manual vs. automatizado

Você pode fazer o teste de regressão manualmente. Após uma alteração, você abre seu cliente de API, reproduz algumas requisições salvas e inspeciona as respostas. Isso funciona para um endpoint e desmorona em dez. Os humanos pulam os casos chatos, e os casos chatos são onde as regressões se escondem. As verificações manuais também não podem ser executadas às 2 da manhã, quando um trabalho agendado mescla uma atualização de dependência.

O teste de regressão automatizado remove o humano do ciclo. Você registra o conjunto uma vez, e então uma máquina o reexecuta a cada push, a cada pull request e a cada deploy. O valor não é a velocidade em uma única execução. É que o conjunto é executado sempre, sem que ninguém decida que vale a pena o esforço.

A contrapartida é o trabalho inicial. Você precisa construir o conjunto e mantê-lo atualizado. Esse custo de manutenção é real, mas é menor do que o custo de um incidente de produção que um teste de cinco segundos teria detectado.

	Manual	Automatizado
Executa em cada alteração	Não, depende da disciplina	Sim, por padrão
Cobertura	Alguns endpoints	O conjunto completo
Custo por execução	Minutos de tempo humano	Segundos de computação
Detecta quebras às 2 da manhã	Não	Sim
Esforço inicial	Baixo	Moderado

Para qualquer coisa além de um projeto de brinquedo, automatize.

Construindo um conjunto de regressão reutilizável

Um conjunto de regressão é um grupo de requisições salvas, cada uma com asserções, agrupadas para que você possa executá-las juntas. O objetivo é a reutilização: construa-o uma vez, execute-o para sempre, estenda-o quando adicionar endpoints.

Estruture o conjunto para que ele sobreviva a mudanças:

Agrupe por recurso, não por funcionalidade. Coloque todos os testes de /users juntos, todos os testes de /orders juntos. Quando você mexe no serviço de usuários, sabe qual grupo observar.

Use variáveis de ambiente para tudo o que se move. A URL base, tokens de autenticação e IDs de tenant pertencem a um ambiente, não codificados em cada requisição. Isso permite que o mesmo conjunto seja executado contra ambientes local, de staging e de produção, trocando apenas uma configuração.

Encadeie requisições que dependem umas das outras. Um fluxo realista cria um recurso, o lê de volta, o atualiza e o exclui. Extraia o id da resposta de criação e passe-o para a próxima requisição. Isso detecta regressões que aparecem apenas em uma sequência, não isoladamente. É aqui que o teste de regressão se sobrepõe ao teste de integração de API.

Conduza casos de borda com dados. Em vez de dez requisições quase idênticas, escreva uma requisição e alimente-a com uma tabela de entradas: valores válidos, valores vazios, valores de limite e valores conhecidamente inválidos. Cada linha se torna um caso de teste. Testes orientados a dados mantêm o conjunto pequeno, enquanto ampliam a cobertura.

Aqui está como uma tabela de dados para um único teste de validação pode parecer em CSV:

email,expectedStatus
alice@example.com,201
bob@test.co,201
not-an-email,422
,422
a@b,422

Uma requisição, cinco casos, cinco asserções no código de status. Adicione uma linha quando encontrar um novo caso de borda, e o conjunto cresce sem novo código.

Mantenha o conjunto rápido. Um conjunto de regressão que leva vinte minutos será ignorado. Simule dependências de terceiros lentas, execute requisições independentes em paralelo onde sua ferramenta permitir, e reserve os fluxos completos de ponta a ponta para uma execução noturna menor e mais lenta.

Executando o conjunto em cada alteração na CI

Um conjunto de regressão que vive no seu laptop protege apenas o seu laptop. O objetivo é executá-lo na integração contínua, nos mesmos eventos que podem introduzir uma regressão: pull requests e merges para seu branch principal.

O padrão é o mesmo em todos os sistemas de CI. Instale um runner headless, aponte-o para o seu conjunto salvo e faça a build falhar se alguma asserção falhar. O Apidog fornece um runner de linha de comando exatamente para isso. Instale-o com Node:

npm install -g apidog-cli

Em seguida, execute um cenário de teste ou conjunto salvo pelo seu ID, contra um ambiente escolhido, e emita relatórios:

apidog run \
  --access-token "$APIDOG_ACCESS_TOKEN" \
  -t 123456 \
  -e 789012 \
  -r cli,html,junit

Detalhamento:

--access-token autentica a execução. Armazene o token como um segredo de CI, nunca no repositório.
-t é o ID do cenário, pasta ou conjunto a ser executado.
-e é o ID do ambiente, para que o mesmo conjunto possa mirar staging ou produção alterando um valor.
-r lista os formatos de relatório. cli imprime no console, html produz um relatório legível e junit emite XML que sua CI pode analisar para mostrar aprovação/falha por teste.

O runner é headless. Ele se encaixa em qualquer etapa de CI que possa executar Node, então o mesmo comando funciona no GitHub Actions, GitLab CI, Jenkins ou CircleCI. Aqui está um job do GitHub Actions que executa o conjunto em cada pull request:

name: API Regression
on: [pull_request]
jobs:
  regression:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v6
      - uses: actions/setup-node@v6
        with:
          node-version: '22'
      - run: npm install -g apidog-cli
      - run: |
          apidog run \
            --access-token "$APIDOG_ACCESS_TOKEN" \
            -t 123456 \
            -e 789012 \
            -r cli,junit
        env:
          APIDOG_ACCESS_TOKEN: ${{ secrets.APIDOG_ACCESS_TOKEN }}

Quando um cenário falha, o runner sai com código diferente de zero e o job fica vermelho. O pull request é bloqueado até que alguém o examine. Para um pipeline completo de copiar e colar e mais padrões de CI, veja Apidog CLI para CI/CD e como automatizar testes de API no GitHub Actions.

Se você alimentar o conjunto com um arquivo de dados, passe-o com -d:

apidog run \
  --access-token "$APIDOG_ACCESS_TOKEN" \
  -t 123456 \
  -e 789012 \
  -d ./test-data/emails.csv \
  -r cli,junit

Testando um branch de funcionalidade que tem sua própria versão de API? Adicione --branch para executar contra o conjunto salvo desse branch em vez do padrão. Para manter um histórico de execuções na nuvem, adicione o flag simples --upload-report.

Diferenciação de esquema e contrato

As asserções detectam regressões no comportamento. A diferenciação de esquema as detecta na definição, muitas vezes antes mesmo de você implantar.

A ideia: sua especificação OpenAPI é um arquivo versionado em seu repositório. Quando alguém a edita, você compara a nova especificação com a anterior e classifica a mudança. Adicionar um campo opcional é seguro. Remover um campo, renomear um, restringir um tipo ou tornar um campo opcional obrigatório é uma mudança que quebra a compatibilidade. Uma ferramenta de diferenciação pode sinalizar as quebras no pull request, para que o revisor veja "isso remove user.phone" em vez de uma parede de YAML.

Combine isso com testes de contrato contra a API ao vivo. Em cada execução, valide as respostas reais contra o esquema atual. Se a especificação promete um campo que a API não retorna mais, ou se a API retorna um tipo que a especificação proíbe, a verificação falha. Esta é a guarda dupla: a diferenciação da especificação detecta edições intencionais no contrato, e o teste de contrato detecta o código se afastando do contrato.

Mudanças que quebram a compatibilidade nem sempre são bugs. Às vezes, você pretende remover um campo. O objetivo da diferenciação é tornar essa decisão explícita e roteá-la através do seu processo de versionamento e descontinuação, em vez de surpreender um cliente. Veja como versionar e descontinuar APIs em escala para lidar com as mudanças que você faz de propósito.

Como o Apidog executa conjuntos de regressão

O Apidog abrange as peças descritas acima em um só lugar, o que mantém o conjunto e a especificação próximos um do outro.

Você constrói cenários de teste visualmente: encadeia requisições, extrai valores de uma resposta para a próxima e anexa asserções de status, esquema e valores de campo. Como o design da API e os testes vivem no mesmo projeto, você pode validar respostas contra o esquema salvo do endpoint sem escrever o esquema duas vezes. Quando o design muda, o esquema que os testes verificam muda junto.

Para casos orientados a dados, anexe um conjunto de dados CSV ou JSON a um cenário e o Apidog executa um caso por linha. Salve cenários relacionados em um conjunto de testes para que uma única execução exercite um recurso ou fluxo inteiro.

O runner apidog-cli leva esses conjuntos salvos de forma headless para a CI, conforme mostrado acima. Ele executa cenários e conjuntos salvos. Não é um enviador de requisições interativo nem um gerador de carga. Ele faz um trabalho: reproduzir seu conjunto de regressão e relatar o que passou. Esse escopo restrito é o que permite que ele se encaixe em qualquer etapa de CI compatível com Node. Para o CLI mais um fluxo de trabalho scriptado, veja o guia de pipeline de CI/CD do Apidog CLI.

Um fluxo de trabalho inicial

Aqui está uma sequência que você pode adotar esta semana sem reconstruir sua estratégia de teste:

Escolha seus cinco endpoints mais chamados. O risco de regressão se concentra onde o tráfego está. Comece por aí.
Salve uma requisição por endpoint com asserções. Código de status, esquema de resposta e dois ou três campos-chave cada. Esta é a sua linha de base.
Adicione um fluxo encadeado. Criar, ler, atualizar, excluir em seu recurso principal. Isso detecta regressões entre requisições que os testes isolados perdem.
Adicione uma tabela de dados a um endpoint com muitas validações. Alguns valores válidos, vazios e inválidos.
Conecte-o à CI em pull requests. Instale apidog-cli, execute o conjunto com -r junit e bloqueie merges em caso de falha.
Aumente o conjunto quando um bug escapar. Toda regressão de produção que passa se torna um novo caso de teste. O conjunto fica mais forte com suas próprias falhas.

Os passos um a quatro levam uma tarde. O passo cinco é um único arquivo de CI. Depois disso, o conjunto se executa sozinho e você o estende apenas quando a realidade te ensina um novo modo de falha. Esse ciclo de feedback é o objetivo principal: um renomear que teria sido um incidente se torna uma verificação vermelha em um pull request.

FAQ

Como o teste de regressão de API é diferente do teste de regressão geral? O teste de regressão geral reverifica o comportamento do aplicativo em todo o sistema, incluindo a interface do usuário e a lógica de negócios. O teste de regressão de API restringe isso à superfície HTTP: rotas, códigos de status, esquema de resposta e valores de campos-chave. O foco restrito o mantém rápido o suficiente para ser executado em cada commit, e ele mira exatamente o que outros sistemas se acoplam.

Com que frequência devo executar o conjunto de regressão? Em cada alteração que pode afetar a API. Na prática, isso significa a cada pull request e a cada merge para seu branch principal, executado automaticamente na CI. Mantenha um conjunto principal rápido para pull requests e uma execução de ponta a ponta maior para builds noturnas, para que a verificação por commit permaneça rápida.

O que devo afirmar para evitar um conjunto frágil? Afirme o que um consumidor quebraria. Fixe códigos de status, estrutura e tipos de resposta, e os valores de campos com significado contratual, como IDs e enums de status. Para valores que mudam a cada requisição, como timestamps, afirme o tipo e o formato, não o valor literal. Exagerar nas afirmações sobre dados voláteis é a principal causa de falsas falhas.

Posso executar testes de regressão de API sem escrever código? Sim. Ferramentas como o Apidog permitem que você construa cenários e asserções visualmente e, em seguida, os execute de forma headless na CI com apidog-cli. Você salva o conjunto uma vez através da interface e o runner de linha de comando o reproduz em seu pipeline, para que os testes sejam executados automaticamente sem um harness de teste escrito à mão.

Como lido com mudanças intencionais que quebram a compatibilidade? Direcione-as através do seu processo de versionamento e descontinuação, em vez de deixá-las aparecer como falhas de teste surpreendentes. Use a diferenciação de esquema para sinalizar a mudança na revisão, versione o endpoint ou adicione o campo como opcional primeiro, e atualize a linha de base de regressão deliberadamente uma vez que a mudança seja intencional e comunicada aos consumidores.