Mini-projeto guiado: suíte completa de testes para API pública ou mockada com documentação e execução

Objetivo do mini-projeto e escopo da suíte

Neste mini-projeto, você vai montar uma suíte completa de testes no Postman para uma API pública ou mockada, com documentação mínima, execução repetível e evidências de resultados. A ideia é sair de “requests soltos” e chegar a um pacote organizado: coleção com pastas, variáveis de ambiente, scripts de pré-requisição e testes, dados para execução em lote, e uma forma de rodar tudo de maneira consistente (manual e automatizada via Newman).

Para manter o projeto guiado e reproduzível, vamos usar um cenário simples de “Catálogo de Produtos” com endpoints típicos: autenticação, listagem, criação, consulta por ID, atualização e exclusão. Se você preferir uma API pública, adapte os endpoints e os campos, mantendo a mesma estrutura de testes. Se você preferir mock, use o Postman Mock Server para simular respostas e garantir previsibilidade.

Escolha da API: pública vs mockada (quando usar cada uma)

API pública é útil para treinar com dados reais e latência real, mas pode ter instabilidade, limites de rate limit e mudanças inesperadas. API mockada é ideal para uma suíte determinística: você controla payloads, status codes e casos de erro. Para um mini-projeto didático, o mock costuma ser a melhor opção porque permite cobrir cenários positivos e negativos sem depender de terceiros.

No Postman, você pode criar um Mock Server a partir de uma coleção e exemplos. O fluxo é: criar requests, salvar exemplos de resposta (Examples) para diferentes status codes, e publicar o mock. Depois, você aponta a variável {{baseUrl}} para a URL do mock e executa a suíte como se fosse uma API real.

Estrutura do projeto no Postman (coleção, pastas e convenções)

Crie uma coleção chamada MiniProjeto - Suite API Catalogo. Dentro dela, organize pastas por domínio e por fluxo. Uma estrutura prática para este mini-projeto:

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

• 00 - Setup (healthcheck, obter token, preparar dados)
• 10 - Produtos (CRUD e validações)
• 20 - Contratos (validações de schema e headers)
• 30 - Negativos (erros esperados: 400, 401, 404, 409)

Mesmo que você não tenha todos os endpoints, a estrutura ajuda a pensar em cobertura. O importante é que cada request tenha: nome claro, URL com {{baseUrl}}, headers padronizados, e testes que validem status code, tempo de resposta (quando fizer sentido), e conteúdo do body.

Ambientes e variáveis: tornando a execução repetível

Crie um Environment chamado Catalogo - Local/Mock (ou outro nome que represente seu alvo). Defina variáveis essenciais:

• baseUrl: URL da API real ou do mock
• token: token de autenticação (se aplicável)
• productId: ID do produto criado no fluxo
• runId: identificador único da execução (para rastrear dados)

Crie também variáveis em nível de Collection (Collection Variables) para valores padrão que não mudam entre ambientes, como defaultTimeoutMs ou nomes de campos. Use Environment para o que muda por alvo (URLs, credenciais, tokens).

Gerando um identificador único por execução

Em uma request de setup (ou no Pre-request Script da coleção), gere um runId para evitar colisões de dados, especialmente em mocks que simulam persistência ou em APIs reais com validação de unicidade.

// Pre-request Script (Collection ou request 00 - Setup / Init RunId) const runId = pm.variables.replaceIn('{{$timestamp}}'); pm.environment.set('runId', runId);

Depois, use esse runId para compor nomes como Produto {{runId}}.

Documentação mínima dentro da coleção (descrições e exemplos)

Uma suíte “com documentação” no Postman não precisa virar um manual extenso. O essencial é: descrição da coleção com objetivo, pré-requisitos, como executar, e o que a suíte valida. Em cada pasta, descreva o propósito. Em cada request, descreva entradas (headers, query params, body) e saídas esperadas (status e campos principais).

Além disso, salve Examples para respostas típicas. Isso ajuda tanto na documentação quanto na criação de mock. Para cada request importante, salve pelo menos um exemplo de sucesso e um de erro (quando aplicável), com status code correto.

Passo a passo prático: construindo o fluxo principal (CRUD)

Passo 1: Healthcheck (ou endpoint simples de leitura)

Crie uma request GET {{baseUrl}}/health (ou equivalente). Se a API não tiver health, use um endpoint de leitura como GET {{baseUrl}}/products. Testes recomendados: status 200 e formato básico do retorno.

pm.test('Status 200', function () {   pm.response.to.have.status(200); }); pm.test('Resposta em JSON', function () {   pm.response.to.have.header('Content-Type');   pm.expect(pm.response.headers.get('Content-Type')).to.include('application/json'); });

Passo 2: Autenticação (quando existir)

Se a API exigir token, crie POST {{baseUrl}}/auth/login com body contendo credenciais (em variáveis). No teste, extraia o token e salve no environment. Se a API pública não tiver auth, você pode simular um header fixo ou pular este passo.

// Tests pm.test('Status 200', function () {   pm.response.to.have.status(200); }); const json = pm.response.json(); pm.test('Token presente', function () {   pm.expect(json).to.have.property('token');   pm.expect(json.token).to.be.a('string'); }); pm.environment.set('token', json.token);

Nos demais endpoints, configure o header Authorization como Bearer {{token}} (ou o formato exigido).

Passo 3: Criar produto (POST)

Crie a request POST {{baseUrl}}/products. Body exemplo:

{   "name": "Produto {{runId}}",   "price": 19.9,   "category": "books",   "inStock": true }

Nos testes, valide status (geralmente 201), valide campos retornados e capture o ID para uso nas próximas requests.

pm.test('Status 201', function () {   pm.response.to.have.status(201); }); const json = pm.response.json(); pm.test('Retorna id e name', function () {   pm.expect(json).to.have.property('id');   pm.expect(json).to.have.property('name');   pm.expect(json.name).to.include(pm.environment.get('runId')); }); pm.environment.set('productId', json.id);

Passo 4: Consultar produto por ID (GET)

Crie GET {{baseUrl}}/products/{{productId}}. Testes: status 200, id igual ao armazenado, e consistência do nome.

pm.test('Status 200', function () {   pm.response.to.have.status(200); }); const json = pm.response.json(); pm.test('ID corresponde ao criado', function () {   pm.expect(String(json.id)).to.eql(String(pm.environment.get('productId'))); }); pm.test('Nome contém runId', function () {   pm.expect(json.name).to.include(pm.environment.get('runId')); });

Passo 5: Atualizar produto (PUT ou PATCH)

Crie PUT {{baseUrl}}/products/{{productId}} (ou PATCH). Body exemplo:

{   "name": "Produto {{runId}} - Atualizado",   "price": 29.9,   "category": "books",   "inStock": false }

Teste status (200), e valide que os campos foram atualizados. Se a API retornar o recurso atualizado, valide diretamente; se retornar apenas um ack, faça um GET em seguida para confirmar.

pm.test('Status 200', function () {   pm.response.to.have.status(200); }); const json = pm.response.json(); pm.test('Nome atualizado', function () {   pm.expect(json.name).to.include('Atualizado'); });

Passo 6: Excluir produto (DELETE)

Crie DELETE {{baseUrl}}/products/{{productId}}. Teste status (200/204). Em seguida, execute um GET do mesmo ID esperando 404 (ou equivalente), para provar que o recurso não existe mais.

pm.test('Status 200 ou 204', function () {   pm.expect([200, 204]).to.include(pm.response.code); });

Para o GET pós-delete (request separada), valide 404:

pm.test('Status 404 após delete', function () {   pm.response.to.have.status(404); });

Validações de contrato: schema e campos obrigatórios

Além de validar valores pontuais, inclua uma camada de “contrato” para garantir que a estrutura do JSON não mudou. No Postman, você pode usar JSON Schema com pm.response.to.have.jsonSchema. Exemplo para o retorno de produto:

const productSchema = {   type: 'object',   required: ['id', 'name', 'price'],   properties: {     id: { type: ['string', 'number'] },     name: { type: 'string' },     price: { type: 'number' },     category: { type: 'string' },     inStock: { type: 'boolean' }   },   additionalProperties: true }; pm.test('Contrato do produto (schema)', function () {   pm.response.to.have.jsonSchema(productSchema); });

Se a API retornar listas, valide que é um array e que cada item segue o schema mínimo. Para listas grandes, valide apenas alguns itens para manter performance, ou valide a estrutura do primeiro item quando fizer sentido.

Cenários negativos essenciais (erros esperados)

Uma suíte completa precisa provar que a API falha corretamente. Crie uma pasta 30 - Negativos com requests dedicadas a erros comuns. O objetivo é validar status code e mensagem/estrutura do erro, não “forçar” o sistema a aceitar dados inválidos.

401 Não autorizado (token ausente ou inválido)

Duplique uma request protegida e remova o header Authorization (ou use Bearer invalid). Teste status 401 e um campo de erro (ex.: message).

pm.test('Status 401', function () {   pm.response.to.have.status(401); }); const json = pm.response.json(); pm.test('Erro contém mensagem', function () {   pm.expect(json).to.have.property('message'); });

400 Validação de payload

Crie um POST de produto sem campo obrigatório (ex.: sem name ou com price string). Teste 400 e valide que o erro aponta o campo.

pm.test('Status 400', function () {   pm.response.to.have.status(400); }); const json = pm.response.json(); pm.test('Erro aponta campo inválido', function () {   pm.expect(JSON.stringify(json)).to.match(/price|name/i); });

404 Recurso inexistente

Faça GET {{baseUrl}}/products/nao-existe-{{runId}} e valide 404.

pm.test('Status 404', function () {   pm.response.to.have.status(404); });

Encadeamento e controle de fluxo: garantindo ordem e dependências

Para um fluxo CRUD, a ordem importa: criar antes de consultar, consultar antes de atualizar, e assim por diante. No Collection Runner, a ordem de requests já define o fluxo. Em casos em que você precise pular etapas quando algo falhar, você pode usar postman.setNextRequest para controlar a execução.

Exemplo: se o POST de criação falhar e não houver productId, você pode pular as etapas dependentes para evitar cascata de falhas sem sentido.

// Tests do POST /products if (pm.response.code !== 201) {   postman.setNextRequest(null); }

Outra abordagem é, nas requests dependentes, validar a existência de {{productId}} no Pre-request Script e abortar com um teste explícito.

// Pre-request Script de GET/PUT/DELETE const pid = pm.environment.get('productId'); pm.test('productId definido para o fluxo', function () {   pm.expect(pid, 'productId não definido').to.be.ok; });

Execução em lote com dados (data-driven) para ampliar cobertura

Para simular múltiplos produtos, use o Collection Runner com um arquivo CSV/JSON. Crie uma request POST /products que use variáveis vindas do dataset, como {{name}}, {{price}}, {{category}}. Exemplo de body:

{   "name": "{{name}} - {{runId}}",   "price": {{price}},   "category": "{{category}}",   "inStock": {{inStock}} }

Exemplo de CSV (colunas): name,price,category,inStock. Ao rodar, cada iteração cria um produto diferente. Nos testes, valide que o retorno reflete os dados enviados. Se a API não permitir criar muitos itens, reduza o dataset e foque na mecânica.

Automação com Newman: rodando a suíte fora do Postman

Para execução automatizada, exporte a coleção e o environment (ou use o Postman API para puxar). Com Newman instalado, rode:

newman run "MiniProjeto-Suite-API-Catalogo.postman_collection.json" -e "Catalogo-Local-Mock.postman_environment.json" --reporters cli,json,html --reporter-json-export "reports/report.json" --reporter-html-export "reports/report.html"

Isso gera evidências em JSON e HTML. Em pipelines, você pode falhar o job quando houver testes quebrados (o Newman retorna código de saída diferente de zero). Se quiser separar por estágios, crie diferentes environments (ex.: Mock, Staging) e rode a mesma coleção apontando para URLs diferentes.

Documentando a execução: como deixar claro o “como rodar”

Na descrição da coleção, inclua um bloco “Como executar” com itens objetivos: selecionar environment, rodar no Collection Runner com N iterações (se houver dataset), e comando Newman. Também inclua “Variáveis necessárias” com baseUrl, token (se aplicável) e qualquer segredo (indicando que não deve ser commitado em texto puro).

Dentro da pasta 00 - Setup, descreva a ordem recomendada e o que cada request prepara. Isso reduz dúvidas e evita que alguém rode apenas metade do fluxo e interprete falhas como bugs.

Montando um mock no Postman (opcional, mas recomendado para o mini-projeto)

Se você optar por mock, o passo a passo é: criar as requests com URLs e bodies, executar ou salvar exemplos manualmente, e em cada request criar Examples para diferentes respostas. Por exemplo, no GET /products/{{productId}}, crie um Example 200 com um produto válido e um Example 404 com payload de erro. Depois, crie o Mock Server a partir da coleção e selecione “Use examples”.

Ao usar o mock, lembre-se de que ele responde com base em exemplos e pode não “persistir” dados como uma API real. Para manter o fluxo, você pode: (1) usar exemplos estáticos e testar contrato/status, ou (2) simular persistência com uma lógica de testes focada em validação de respostas esperadas por cenário, não em estado real do servidor.

Checklist operacional do mini-projeto (o que deve existir ao final)

• Coleção com pastas 00, 10, 20, 30 (ou equivalente) e requests nomeadas
• Environment com baseUrl, token (se necessário), productId e runId
• Scripts de teste para status, headers e contrato (schema) nos endpoints principais
• Captura de variáveis (ex.: productId) para encadear o fluxo
• Requests negativas validando 400/401/404 (e outras que façam sentido)
• Documentação na descrição da coleção e das pastas, com instruções de execução
• Comando Newman e geração de relatórios (HTML/JSON) para evidências