O que significa “boas práticas de QA para APIs” no contexto do Postman
Boas práticas de QA para APIs são um conjunto de decisões de padronização e organização que tornam sua suíte de testes mais legível, previsível e fácil de manter ao longo do tempo. No Postman, isso se traduz em como você estrutura coleções e pastas, como nomeia requests e variáveis, como escreve scripts de teste, como registra evidências e como reduz acoplamentos entre testes. O objetivo não é “deixar bonito”, e sim reduzir custo de manutenção, evitar falsos positivos e facilitar a colaboração entre pessoas diferentes (QA, dev, SRE) que vão ler e evoluir a mesma suíte.
Uma suíte bem padronizada permite que você responda rapidamente a perguntas comuns do dia a dia: “qual request cria o recurso?”, “onde está o teste de contrato desse endpoint?”, “por que esse teste falhou?”, “isso depende de qual ambiente?”, “quais dados foram gerados e precisam ser limpos?”. Quando essas respostas estão embutidas na estrutura e no estilo do código, o time ganha velocidade e confiabilidade.
Padronização: como definir um “jeito único” de escrever e organizar
Padronização é a base para legibilidade e manutenção. Sem um padrão, cada pessoa cria pastas, nomes e testes de um jeito, e a suíte vira uma colcha de retalhos. O padrão deve ser simples o suficiente para ser seguido e rígido o suficiente para evitar ambiguidade. Na prática, você padroniza: nomenclatura, estrutura de pastas, convenções de variáveis, estilo de testes, e forma de registrar pré-condições e pós-condições.
Convenção de nomes para coleções, pastas e requests
Uma convenção útil é combinar “ação + recurso + contexto”, evitando nomes genéricos como “Test 1” ou “Endpoint X”. Exemplo de padrão para requests: [MÉTODO] Recurso - Cenário. Isso ajuda a identificar rapidamente o que é CRUD, o que é validação, e o que é fluxo. Exemplos: “GET Users - lista paginada”, “POST Orders - cria com cupom”, “PUT Users/{id} - atualiza email inválido”.
Para pastas, prefira agrupar por domínio ou recurso (Users, Orders, Payments) e, dentro, separar por tipo de suíte quando fizer sentido: “Smoke”, “Contrato”, “Negativos”, “Fluxos”. Evite misturar tudo em uma única lista longa. Um padrão comum é: Coleção por produto ou API; pasta por recurso; subpastas por categoria de teste.
Continue em nosso aplicativo
Você poderá ouvir o audiobook com a tela desligada, ganhar gratuitamente o certificado deste curso e ainda ter acesso a outros 5.000 cursos online gratuitos.
ou continue lendo abaixo...
Baixar o aplicativo
Padrão de tags no nome para facilitar filtros
Quando a suíte cresce, filtrar vira necessidade. Uma prática simples é usar tags no nome do request ou da pasta, por exemplo: “[SMOKE] GET Healthcheck”, “[CONTRATO] GET Users schema”, “[NEG] POST Login sem senha”. Isso permite localizar rapidamente o que roda em pipelines rápidos versus o que roda em regressão completa. O importante é manter um vocabulário pequeno e consistente (por exemplo: SMOKE, CONTRATO, NEG, FLUXO, PERF) e documentar o significado.
Padronização de variáveis e chaves de ambiente
Variáveis mal nomeadas são uma fonte comum de confusão e bugs. Defina um padrão que diferencie claramente: base URL, credenciais, tokens, IDs gerados e dados de teste. Exemplos de convenção: baseUrl para URL base; authToken para token; userId, orderId para IDs; testData_userEmail para dados fixos de teste. Evite nomes ambíguos como “id” ou “token” sem contexto.
Outra boa prática é padronizar o “escopo” de cada variável: o que é do ambiente (muda por ambiente), o que é da coleção (padrão para a suíte) e o que é temporário (gerado durante a execução). Mesmo sem repetir conceitos já vistos, a regra prática é: se muda entre ambientes, deve estar no ambiente; se é constante da suíte, fica na coleção; se é resultado de execução, fica em variável temporária ou de coleção com nome explícito (ex.: currentUserId).
Legibilidade: escrevendo testes que outras pessoas entendem
Legibilidade é a capacidade de alguém abrir um request e entender rapidamente: o que está sendo testado, quais são as pré-condições, quais validações são feitas e quais dados são produzidos para os próximos passos. No Postman, isso depende tanto da estrutura quanto do texto e do estilo do script.
Descrição e documentação dentro do request
Use o campo de descrição do request e/ou da pasta para registrar: objetivo do teste, dependências (se houver), e o que deve ser verificado. Isso evita que o conhecimento fique “na cabeça” de quem criou. Um formato simples e repetível ajuda, por exemplo:
- Objetivo: validar que o endpoint retorna lista paginada de usuários.
- Pré-condições: usuário admin autenticado; baseUrl configurada.
- Validações: status 200; tempo de resposta aceitável; contrato mínimo; paginação coerente.
- Saídas: salva currentFirstUserId para requests seguintes (se aplicável).
Mesmo quando o teste é simples, uma linha de objetivo já reduz dúvidas. Em requests complexos, essa descrição vira um “mapa” para manutenção.
Estrutura de testes: organize por blocos e intenção
Um script de teste legível não é apenas “vários pm.test soltos”. Ele deve ser organizado por intenção: validações de status e headers, validações de contrato (estrutura), validações de regras de negócio (campos e valores), e validações de performance básica (tempo). Além disso, mensagens de falha devem ser informativas.
Exemplo de estrutura recomendada no Postman (aba Tests), com mensagens claras:
// 1) Status e headers essenciais
pm.test('Status deve ser 200', function () {
pm.response.to.have.status(200);
});
pm.test('Content-Type deve ser JSON', function () {
pm.response.to.have.header('Content-Type');
pm.expect(pm.response.headers.get('Content-Type')).to.include('application/json');
});
// 2) Corpo: parse seguro
let json;
pm.test('Resposta deve ser JSON válido', function () {
json = pm.response.json();
pm.expect(json).to.be.an('object');
});
// 3) Contrato mínimo (sem engessar demais)
pm.test('Deve conter campos mínimos de paginação', function () {
pm.expect(json).to.have.property('items');
pm.expect(json).to.have.property('page');
pm.expect(json).to.have.property('pageSize');
});
// 4) Regras de negócio básicas
pm.test('items deve ser um array', function () {
pm.expect(json.items).to.be.an('array');
});Repare em dois pontos: primeiro, o parse do JSON é validado antes de usar o objeto; segundo, o “contrato mínimo” evita testes frágeis que quebram por mudanças irrelevantes (por exemplo, um campo novo que não impacta o consumidor).
Evite testes frágeis: assertivas resilientes
Um erro comum é escrever testes que falham por detalhes que não importam para o objetivo do cenário. Isso gera ruído e reduz confiança na suíte. Prefira validar o que é essencial para o comportamento esperado. Exemplos de fragilidade: comparar mensagens de erro inteiras quando o importante é o código; validar ordem exata de itens quando a API não garante ordenação; exigir todos os campos quando apenas alguns são obrigatórios.
Boas práticas para reduzir fragilidade:
- Valide códigos e estruturas, não textos completos (a menos que seja requisito).
- Quando houver listas, valide presença de itens e propriedades, e use ordenação apenas se for contrato.
- Use tolerância para campos de data/hora quando aplicável (por exemplo, validar formato e não valor exato).
- Evite dependência de dados “fixos” do ambiente (IDs que mudam, usuários que podem ser removidos).
Padrão de mensagens de erro e logs úteis
Quando um teste falha, você quer entender o motivo em segundos. Para isso, padronize mensagens e registre informações úteis com parcimônia. Em vez de “deve funcionar”, prefira “Status deve ser 201 ao criar pedido”. Quando precisar, use logs para imprimir valores-chave (por exemplo, o id criado), mas evite logar dados sensíveis (tokens, senhas, PII).
Exemplo de log controlado:
pm.test('Deve retornar id do recurso criado', function () {
const json = pm.response.json();
pm.expect(json).to.have.property('id');
console.log('Recurso criado com id:', json.id);
});Manutenção: como reduzir custo de mudança e evitar efeito dominó
Manutenção é o que separa uma suíte “que roda hoje” de uma suíte que continua útil por meses. APIs mudam: endpoints evoluem, campos são adicionados, autenticação muda, ambientes variam. Uma suíte sustentável é aquela em que mudanças são localizadas e previsíveis.
Centralize o que muda: URLs, caminhos e headers comuns
Evite repetir base URL e headers comuns em cada request. Mesmo que você já use variáveis, a boa prática é garantir que exista um único ponto de alteração para itens recorrentes: baseUrl, versões de API, headers padrão (Accept, Content-Type), e chaves de feature flag quando aplicável. Isso reduz o risco de “metade da suíte” apontar para um lugar e a outra metade para outro.
Uma forma prática é padronizar o uso de variáveis no próprio request: “{{baseUrl}}/v1/users”. Para headers, use variáveis como “{{authHeader}}” ou “Bearer {{authToken}}” de forma consistente, evitando variações como “Token {{token}}” em alguns requests e “Bearer {{auth}}” em outros.
Minimize dependências entre requests (ou torne-as explícitas)
Dependência excessiva cria cascatas de falha: um request quebra e derruba todos os seguintes. Quando um fluxo é realmente necessário (por exemplo, criar um recurso para depois consultar), torne a dependência explícita e controlada: salve apenas o que precisa (IDs), valide a criação antes de prosseguir e, se possível, isole fluxos em pastas próprias.
Uma prática útil é: requests de “setup” (criação de dados) e “teardown” (limpeza) ficam claramente identificados e não se misturam com testes de leitura simples. Isso facilita rodar apenas leituras (smoke) sem precisar criar massa toda vez.
Dados de teste: previsibilidade, unicidade e limpeza
Manutenção também depende de dados de teste. Se você cria usuários com emails fixos, uma segunda execução pode falhar por conflito. Se você não limpa dados, o ambiente fica poluído e os testes começam a falhar por efeitos colaterais. Portanto, padronize como gerar dados únicos e como limpar o que foi criado.
Exemplo prático de geração de dado único no Pre-request Script:
// Gera um sufixo único simples baseado em timestamp
const suffix = Date.now();
pm.collectionVariables.set('uniqueSuffix', suffix);
// Exemplo de email único para cadastro
pm.collectionVariables.set('newUserEmail', `qa.user.${suffix}@example.com`);Para limpeza, quando a API permitir, crie requests de remoção e padronize o salvamento de IDs criados. Se a limpeza não for possível (por restrição do ambiente), ao menos garanta unicidade para evitar colisões e registre claramente essa limitação na descrição da pasta.
Versionamento e compatibilidade: testes por versão de API
Quando existem versões (v1, v2) ou mudanças graduais, evite “editar por cima” e quebrar compatibilidade sem perceber. Uma prática de manutenção é separar pastas por versão ou usar tags: “[v1]”, “[v2]”. Assim, você consegue manter testes de regressão para versões antigas enquanto valida a nova. Também ajuda a planejar descontinuação: quando v1 for removida, você sabe exatamente o que apagar.
Passo a passo prático: refatorando uma coleção para ficar padronizada e sustentável
A seguir, um passo a passo aplicável quando você já tem uma coleção “crescida” e precisa colocar ordem sem reescrever tudo do zero. A ideia é refatorar incrementalmente, mantendo a suíte rodando.
Passo 1: defina um guia de nomenclatura e aplique nos itens mais usados
Escolha um padrão simples e aplique primeiro nos requests mais executados (smoke e fluxos críticos). Por exemplo: “GET Users - lista”, “POST Users - cria”, “GET Users/{id} - detalhe”. Renomear não muda comportamento, mas melhora muito a navegação. Se você usa tags, aplique também: “[SMOKE] GET Healthcheck”.
Passo 2: reorganize pastas por domínio e tipo de teste
Crie pastas por recurso (Users, Orders, Auth). Dentro, crie subpastas para “Smoke”, “Contrato”, “Negativos”, “Fluxos” apenas se isso fizer sentido para o tamanho atual. Se a coleção for pequena, uma pasta por recurso pode bastar. O objetivo é reduzir a busca manual e evitar duplicação de requests semelhantes em lugares diferentes.
Passo 3: normalize variáveis e elimine duplicações
Faça um inventário rápido das variáveis existentes e padronize nomes. Troque “url”, “base_url”, “host” por um único “baseUrl”. Troque “token”, “access_token”, “jwt” por “authToken” (ou outro padrão escolhido). Em seguida, atualize os requests para usar as variáveis padronizadas.
Uma dica prática é escolher um prefixo para variáveis de dados de teste (por exemplo, “testData_”) e outro para variáveis geradas em runtime (por exemplo, “current”). Isso evita confusão entre “email fixo de teste” e “email recém-criado”.
Passo 4: padronize o esqueleto de testes em requests críticos
Escolha um “template” de testes e aplique nos endpoints principais. O template pode ter: status, header, JSON válido, contrato mínimo e uma regra de negócio. Não tente cobrir tudo de uma vez. O ganho vem da consistência: qualquer pessoa abre um request e encontra os mesmos blocos.
Exemplo de template enxuto para endpoints JSON:
// Status
pm.test('Status deve ser 2xx', function () {
pm.expect(pm.response.code).to.be.within(200, 299);
});
// JSON válido
pm.test('Resposta deve ser JSON válido', function () {
pm.response.to.be.json;
});
// Contrato mínimo (ajuste conforme endpoint)
const body = pm.response.json();
pm.test('Deve conter campo obrigatório "id"', function () {
pm.expect(body).to.have.property('id');
});Note que “2xx” pode ser útil em endpoints que retornam 200 ou 204 dependendo do caso. Quando o contrato exigir um status específico, prefira validar exatamente (por exemplo, 201 em criação).
Passo 5: torne dependências explícitas e salve saídas com nomes claros
Quando um request cria um recurso e o próximo precisa do ID, salve com nome explícito: “currentUserId”, “currentOrderId”. Evite “id”. Também valide a presença do ID antes de salvar, para não propagar erro silencioso.
const json = pm.response.json();
pm.test('Deve retornar id para encadear fluxo', function () {
pm.expect(json).to.have.property('id');
});
pm.collectionVariables.set('currentUserId', json.id);Passo 6: crie requests de limpeza (quando aplicável) e marque-os
Se a API permitir deletar o que foi criado, crie requests de teardown e marque com tag “[TEARDOWN]” ou mantenha em uma pasta “Teardown”. Isso facilita rodar uma bateria de testes sem poluir o ambiente. Se não for possível deletar, registre na descrição e use dados únicos para reduzir colisões.
Passo 7: revise negativos e mensagens de erro com foco em estabilidade
Testes negativos costumam ser os mais frágeis, porque mensagens mudam. Padronize para validar o que é contrato: status (por exemplo, 400/401/403/422), presença de um código de erro (se existir) e estrutura do payload de erro. Evite validar texto completo, a menos que seja requisito formal.
Exemplo de negativo estável:
pm.test('Deve retornar 401 sem token', function () {
pm.response.to.have.status(401);
});
const err = pm.response.json();
pm.test('Erro deve ter estrutura mínima', function () {
pm.expect(err).to.have.property('code');
pm.expect(err).to.have.property('message');
});Checklist de revisão rápida para manter o padrão no dia a dia
Para evitar que a suíte volte a ficar inconsistente, use um checklist simples sempre que adicionar ou alterar requests. A ideia é tornar a revisão rápida e objetiva.
- Nome do request segue o padrão e descreve método, recurso e cenário.
- Request usa variáveis padronizadas (baseUrl, authToken, IDs com contexto).
- Descrição do request/pasta explica objetivo, pré-condições e saídas.
- Testes estão organizados por blocos (status/headers/JSON/contrato/regras).
- Assertivas validam o essencial e evitam fragilidade desnecessária.
- Dados criados são únicos e, quando possível, existe teardown.
- Logs não expõem dados sensíveis e ajudam a diagnosticar falhas.
- Dependências entre requests são explícitas e minimizadas.
Padrões recomendados para equipes: consistência sem burocracia
Em equipe, o maior risco é cada pessoa “inventar um padrão”. Para evitar isso sem criar burocracia, defina um guia curto (uma página) com exemplos reais da própria suíte. Inclua: convenção de nomes, lista de tags permitidas, nomes oficiais de variáveis, template de testes e regras para negativos. Mantenha esse guia evolutivo: se um novo padrão surgir por necessidade real, atualize o guia e aplique gradualmente.
Outra prática é criar uma pasta “Templates” dentro da coleção com 2 ou 3 requests-modelo (GET padrão, POST criação, Negativo 401/403). Assim, quem for criar novos testes copia um modelo já alinhado. Isso reduz variação e acelera onboarding de novas pessoas no projeto.
