Parte um: para que serve, de verdade, teste e desenvolvimento de API com Postman
Uma collection é um registro de requisições que você pode compartilhar e executar. Isso a torna excelente em três tarefas: explorar uma API desconhecida, documentar uma API com exemplos que realmente rodam e entregar a alguém uma reprodução que a pessoa mesma pode executar. Essas três coisas merecem ser bem feitas e costumam ser subestimadas.
O erro dos times não está em usar collections. Está em supor que a collection pode virar a suíte de regressão sem que mais nada mude.
Parte dois: os quatro problemas
Toda suíte de API, em qualquer ferramenta, acaba esbarrando nos mesmos quatro. Conhecê-los de antemão já é a maior parte da habilidade.
Sessões expiram
Tokens expiram no meio da execução e as falhas parecem bugs do produto.
Tire as credenciais das requisições individuais e leve-as para o environment.
Valores transitam entre chamadas
Uma criação retorna um identificador que a próxima chamada precisa usar.
Capture esse valor, nunca o fixe no código, ou a suíte vai funcionar exatamente uma vez.
A ordem importa
A cobertura é um grafo; uma collection é uma lista.
Uma falha logo no início se propaga em cascata e vira uma tela inteira de vermelho sem relação com ela.
O quarto é a limpeza. Os registros se acumulam, as restrições de unicidade começam a disparar e as asserções de paginação começam a divergir. Apagar por padrão de nome é seguro até que duas execuções se sobreponham.
Parte três: asserções que valem a pena escrever
Faça asserções sobre o corpo da resposta, não apenas sobre o status. Um 200 com uma lista vazia onde deveria haver um registro é um bug que uma verificação de status considera aprovado.
Faça asserções de que as falhas falham corretamente. Peça algo que não existe e verifique o código e o formato do erro. Serviços que retornam 200 com um erro dentro são comuns.
Faça asserções entre endpoints. Se um registro referencia outro, busque esse outro. Os bugs interessantes moram entre duas chamadas.
Parte quatro: quando a collection não basta
O sinal é que seus scripts de pre-request viraram um pequeno framework que só uma pessoa entende. Nesse ponto, os quatro problemas passam a ser da sua infraestrutura, e não da sua ferramenta, e é a hora de mover a cobertura de regressão para um lugar que trate isso como parte do produto. O TestSprite cuida deles como Auto-Authentication, Dynamic Variables, Dependency Chains e Auto-Cleanup, descritos na documentação de testes de API.
Mantenha a collection. Ela continua sendo a melhor coisa que você tem para explorar e documentar.
Parte quatro e meio: os scripts que ninguém revisa
Os scripts de pre-request e de teste dentro de uma collection merecem um momento de atenção, porque é neles que moram as falhas interessantes e quase nunca são revisados.
São JavaScript, rodam em uma ordem específica, alteram variáveis de environment compartilhadas e ficam guardados dentro de um export em JSON cujo diff não diz nada de útil. Uma mudança no script de renovação de token pode quebrar quarenta requisições, e o pull request mostra uma linha de JSON alterada. Os times descobrem isso na primeira vez em que duas pessoas editam a mesma collection na mesma semana.
Se seus scripts chegaram ao ponto em que esse parágrafo soa familiar, a collection virou software. Software pede revisão, controle de versão e testes próprios — um lugar estranho de se chegar quando o objetivo era testar outra coisa.
Parte cinco: faça isso rodar sem você
Conecte o repositório pelo dashboard e as execuções partem do deploy que você já gera; ou, no lugar disso, adicione um passo ao seu próprio workflow.
Terminal
npm install -g @testsprite/testsprite-cli
testsprite setup
A mesma configuração está disponível no dashboard do TestSprite, caso você prefira não instalar nada localmente. O restante dos recursos do CLI está no repositório do CLI.
Parte seis: o que o TestSprite faz com os quatro problemas
Cada um dos quatro tem um nome e é tratado como produto, e não como script que você mesmo escreve. O Auto-Authentication configura o fluxo de login uma vez e busca um token novo antes de cada execução. As Dynamic Variables capturam um valor de uma resposta e o injetam na requisição seguinte. As Dependency Chains derivam uma ordem segura a partir do que cada caso precisa e do que ele produz. O Auto-Cleanup apaga exatamente os registros que a execução criou.
A cobertura começa pelo API Discovery sobre o serviço em execução, somado à especificação que você tiver, e o plano gerado inclui as categorias de autorização, tratamento de erros e limites — justamente as que as pessoas pulam.
O ganho para quem aprendeu o assunto por meio de collections: você mantém a collection para explorar e documentar, que é o que ela faz de melhor, e a suíte de regressão deixa de ser um amontoado de JavaScript mantido por uma única pessoa.
Existe um PDF oficial e gratuito?
Isso quem define são as editoras, e muda com o tempo. Esta página é o conhecimento prático, não uma cópia de um livro.
Devo aprender Postman primeiro?
Sim. É o jeito mais rápido de construir um modelo mental preciso de uma API, e esse entendimento se transfere para qualquer outra ferramenta.
Preciso aprender a parte de scripts?
O suficiente para conseguir ler. Quando você já está escrevendo muito script, esse é o sinal de que a collection ficou pequena como suíte de regressão.
Em que ordem devo aprender isso?
Envie requisições, depois faça asserções sobre os corpos das respostas, depois trate a autenticação, depois encadeie chamadas e, por fim, faça a limpeza. Os dois últimos são onde a maioria das pessoas para e onde está o valor.
Newman é suficiente para CI?
Ele roda collections em CI sem problemas. A questão é quem mantém os scripts por baixo, não qual runner os executa.
Aprenda os quatro problemas, não o menu.
Teste e desenvolvimento de API com Postman é, em boa parte, sobre sessões, valores capturados, ordenação e limpeza. As collections são excelentes para explorar e documentar; quando os scripts por baixo viram um framework, leve a cobertura de regressão para um lugar feito para isso.