🏆 Testes de API com Postman e Newman

📋 Índice

Sobre o Projeto
Funcionalidades
Tecnologias e Ferramentas
Estrutura do Projeto
Cobertura de Testes
Cobertura de Testes Resumo
Cobertura de Testes Detalhada
Roadmap
Pipeline CI/CD
Pré-requisitos
Instalação
Como Executar
Relatórios
Contribuindo
Agradecimentos
Contato
Links Úteis

🎓 Sobre o Projeto

Este repositório demonstra a implementação completa de testes automatizados de API utilizando Postman e Newman, com integração contínua via GitHub Actions e deploy no Github Pages.

📝 Objetivo

O projeto foi desenvolvido como parte do curso "Dominando Postman: Do Teste Manual a Performance APIs" na Udemy e no Qualiters Club, ministrado pela Priscila Caimi, e tem como objetivo:

✅ Demonstrar proficiência em testes funcionais, automatizados e de performance de APIs REST
✅ Automatizar a execução de testes utilizando Newman CLI
✅ Gerar relatórios profissionais com múltiplos formatos (HTML, HTML-EXTRA, CSV, JSON)
✅ Implementar pipeline CI/CD com GitHub Actions
✅ Publicar relatórios automaticamente no GitHub Pages
✅ Aplicar boas práticas de QA e DevOps

🧠 API ServeRest

Este projeto utiliza a ServeRest API, uma API REST gratuita que simula uma loja virtual, desenvolvida por Paulo Gonçalves especificamente para servir como material de estudos em testes de API.

Endpoints testados:

🔐 /login - Autenticação e autorização de usuários
👤 /usuarios e /usuarios/{_id} - Gerenciamento de usuários (CRUD)
📦 /produtos e /produtos/{_id} - Gerenciamento de produtos (CRUD)
🛒 /carrinhos, /carrinhos/{_id}, /carrinhos/concluir-compra e /carrinhos/cancelar-compra - Operações de carrinho de compras

✨ Funcionalidades

Tipos de Testes Implementados

Testes Funcionais: Validação de endpoints, status codes, headers e payloads
Testes de Contrato: Validação de JSON schema com a biblioteca Ajv
Testes Negativos: Validação de cenários de erro e edge cases
Testes de Segurança: Validação de autenticação e autorização (Admin vs User)
Testes de Integração: Fluxos completos entre múltiplos endpoints
Testes de Performance: Medição e validação de tempo de resposta

Recursos Técnicos

🔄 Automação Completa: Execução via CLI e CI/CD
📊 Múltiplos Formatos de Relatório: HTML, HTML Extra, CSV, JSON
🌐 Deploy Automático: Publicação de relatórios no GitHub Pages
🔍 Variáveis de Ambiente: Gestão de configurações por ambiente
📝 Documentação Viva: Collections como documentação executável
🔒 Testes de Permissão: Validação de rotas exclusivas para administradores

🛠️ Tecnologias e Ferramentas

Principais

Ferramenta	Versão	Propósito
Node.js	≥14.0.0	Ambiente de execução e gerenciamento de dependências para Newman.
Newman	Latest	Executor de linha de comando para as coleções do Postman, incluindo a geração de relatorios.
Postman	Latest	Criação e organização das coleções de requisições, variáveis de ambiente e scripts de teste (com JavaScript).
GitHub Actions	-	Pipelines de CI/CD

Reports / Relatórios

Ferramenta	Versão	Propósito
newman-reporter-htmlextra	Latest	Geração de relatórios HTML detalhados e amigáveis.
newman-reporter-html	Latest	Geração de relatórios HTML padrão.
newman-reporter-csv	Latest	Geração de relatórios em formato CSV

Collections do Postman

Acesse o workspace público com todas as coleções: Postman Workspace

📁 Estrutura do Projeto

O projeto está organizado para facilitar a navegação e execução:

testes-api-postman-newman/
│
├── .github/
│   └── workflows/
│       └── main.yml                              # Configuração do pipeline CI/CD (GitHub Actions).
│   └── templates/
│       └── index.html                              # Template da página index para GitHub Pages
│
├── collections/                                  # Coleções do Postman - Arquivos de collection*.json 
│   ├── serve_rest_adm.postman_collection.json    # Coleção de testes - Perfil Admin
│   └── serve_rest_user.postman_collection.json   # Coleção de testes - Perfil Usuário
│
├── environment/                                  # Arquivos .json com variáveis de ambiente (URLs)
│   └── serve_rest.postman_environment.json       # Configurações de ambiente
│
├── docs/                                        # Cobertura de Testes - Relatórios completos
│   └── test-coverage.md                         # Cobertura Detalhada de Testes
│   └── test-coverage-summary.md                 # Resumo Executivo da Cobertura
│
└── README.md                                     # Este arquivo

📊 Cobertura de Testes

🎯 Resumo

📈 Métrica	📊 Valor	✅ Status
Requisições Executadas	38	✅ 100%
Testes Validados	196	✅ 100%
Assertions	240	✅ 100%
Endpoints Cobertos	16/16	✅ 100%
Tempo de Execução	3.5s	⚡ Excelente

🗂️ Cobertura por Módulo

Módulo	Endpoints	Testes	Status
🔐 Autenticação	1/1	12	✅ 100%
👤 Usuários	5/5	56	✅ 100%
📦 Produtos	5/5	74	✅ 100%
🛒 Carrinhos	5/5	96	✅ 100%

⚡ Performance

Collection	Requisições	Tempo Total	Tempo Médio
Admin	20	1.856s	56ms
User	18	1.617s	50ms
Total	38	3.473s	53ms

95% das requisições abaixo de 100ms ⚡

👤 Coleção API ServeRest User

📈 Total: 18 requisições | 92 testes executados | 113 assertions

👩‍💻 Coleção API ServeRest ADM

📈 Total: 20 requisições | 104 testes executados | 127 assertions

🚦 Tipos de Validações

✅ Status codes: 200, 201, 400, 401, 403, 404, etc.
✅ Headers: Authorization, Content-Type, Accept, etc.
✅ Estrutura do corpo de resposta: Validação de campos obrigatórios
✅ Validação de JSON Schema: Conformidade com contratos definidos
✅ Validação de lógica de negócios: Regras específicas da aplicação
✅ Dados retornados: Precisão dos valores nas respostas
✅ Mensagens de sucesso: Feedback correto em operações bem-sucedidas
✅ Mensagens de erro: Validação de mensagens em cenários de falha
✅ Tempo de resposta: Performance dos endpoints

🚩 Destaques da Cobertura

Métricas Consolidadas:

📊 38 requisições totais (20 Admin + 18 User)
✅ 196 testes executados (104 Admin + 92 User)
✅ 240 assertions totais (127 Admin + 113 User)
🎯 100% de taxa de sucesso em ambas as collections

Diferenças entre Perfis:

✅ Admin: Autorizado para POST, PUT, DELETE em /produtos (Status 200/201)
❌ User: Bloqueado para POST, PUT, DELETE em /produtos (Status 403 - "Rota exclusiva para administradores")
🔒 6 cenários de autorização validados com sucesso

📖 Para documentação completa, consulte: Cobertura de testes detalhada ou Cobertura de testes resumo executivo

🗺️ Roadmap

✅ Concluído

Cobertura completa de endpoints nas Collections do Postman
Múltiplos formatos de relatório com o Newman
Pipeline CI/CD com GitHub Actions
Deploy automático no GitHub Pages

🚧 Em Desenvolvimento

Desenvolvimento de testes automatizados de API com o Robot Framework
Cobertura completa dos testes cenários positivos, negativos e alternativos com o Robot Framework
Testes de contrato com validação de JSON Schema no Robot Framework

📅 Planejado

Testes de carga e stress com K6
Integração com ferramentas de monitoramento
Dashboard de métricas em tempo real
Testes de segurança com OWASP ZAP
Testes de contrato com Pact ou Python

☁️ Pipeline CI/CD

O arquivo .github/workflows/main.yml contém toda a configuração do pipeline. O pipeline é executado automaticamente em cada push ou pull request para a branch main.

🔄 Etapas do Pipeline

Setup: Configuração do ambiente Node.js
Install: Instalação do Newman e reports necessários
Test: Execução sequencial das coleções de teste
- Coleção ADM (perfil administrador)
- Coleção User (perfil usuário padrão)
Report: Geração de múltiplos formatos de relatório (HTML-EXTRA, HTML, CSV, JSON)
Upload: Armazenamento como artefatos do GitHub Actions (sempre executado)
Deploy: Publicação automática no GitHub Pages (apenas quando testes passam)

Fluxo de Execução dos Testes

graph LR
    A[Postman Collections] --> B[Newman CLI]
    B --> C[Execução dos Testes]
    C --> D[Geração de Relatórios]
    D --> E[HTML Extra]
    D --> F[HTML Padrão]
    D --> G[CSV]
    D --> H[JSON]
    E --> I[GitHub Pages]
    F --> I
    G --> I
    H --> I

Fluxo de Execução do Pipeline de CI/CD

graph LR
    A[Push/PR on branch Main] --> B[Pipeline - GitHub Actions]
    B --> C[Install Node.js]
    C --> D[Install Newman]
    D --> E[Run Tests ADM]
    E --> F[Run Tests User]
    F --> G[Generate Reports]
    G --> H{Tests Passed?}
    H -->|Yes| I[Deploy to GitHub Pages]
    H -->|No| J[Upload Artifacts]

📦 Pré-requisitos

Requisitos de Sistema

Sistema Operacional: Windows, macOS ou Linux
Node.js: v14.0.0 ou superior (Download Node.js)
npm: v6.0.0 ou superior (incluído com Node.js)
Git: Para clonar o repositório (Download Git)

Verificar Instalações:

# Verificar Node.js
node --version

# Verificar npm
npm --version

# Verificar Git
git --version

Saídas esperadas:

node v14.x.x (ou superior)
npm v6.x.x (ou superior)
git version 2.x.x (ou superior)

🔧 Instalação

1️⃣ Clone o Repositório

# Clonar via HTTPS
git clone https://github.com/sthefanyricardo/testes-api-postman-newman.git

# OU clonar via SSH
git clone [email protected]:sthefanyricardo/testes-api-postman-newman.git

# Entrar no diretório
cd testes-api-postman-newman

2️⃣ Instale o Node.js

Baixe e instale a versão LTS mais recente do Node.js em nodejs.org.

Verifique a instalação:

node --version
npm --version

3️⃣ Instale o Newman e Reports

Opção A: Instalação Global

# Instalar Newman
npm install -g newman

# Instalar Reports
npm install -g newman-reporter-htmlextra
npm install -g newman-reporter-html
npm install -g newman-reporter-csv

Opção B: Instalação Local

# Inicializar projeto
npm init -y

# Instalar Newman e Reports
npm install newman newman-reporter-htmlextra newman-reporter-html newman-reporter-csv --save-dev

4️⃣ Verifique a Instalação

newman --version

Saída esperada: newman/6.x.x ou superior

▶️ Como Executar

🖥️ Execução Local

Executar coleção individual

Coleção ADM (Administrador):

newman run collections/serve_rest_adm.postman_collection.json \
  -e environment/serve_rest.postman_environment.json \
  -r cli,htmlextra

Coleção User (Usuário):

newman run collections/serve_rest_user.postman_collection.json \
  -e environment/serve_rest.postman_environment.json \
  -r cli,htmlextra

Executar com geração de múltiplos relatórios

# Criar diretório para relatórios
mkdir -p newman_reports

# Executar coleção ADM com todos os reports
newman run collections/serve_rest_adm.postman_collection.json \
  -e environment/serve_rest.postman_environment.json \
  -r cli,htmlextra,html,csv,json \
  --reporter-htmlextra-export newman_reports/report-adm-htmlextra.html \
  --reporter-html-export newman_reports/report-adm-html.html \
  --reporter-csv-export newman_reports/report-adm.csv \
  --reporter-json-export newman_reports/report-adm.json

# Executar coleção User com todos os reports
newman run collections/serve_rest_user.postman_collection.json \
  -e environment/serve_rest.postman_environment.json \
  -r cli,htmlextra,html,csv,json \
  --reporter-htmlextra-export newman_reports/report-user-htmlextra.html \
  --reporter-html-export newman_reports/report-user-html.html \
  --reporter-csv-export newman_reports/report-user.csv \
  --reporter-json-export newman_reports/report-user.json

Executar com opções avançadas

# Com múltiplas iterações (executar 3 vezes)
newman run collections/serve_rest_adm.postman_collection.json \
  -e environment/serve_rest.postman_environment.json \
  -n 3 \
  -r cli,htmlextra

# Com delay entre requisições (útil para rate limiting)
newman run collections/serve_rest_user.postman_collection.json \
  -e environment/serve_rest.postman_environment.json \
  --delay-request 1000 \
  -r cli,htmlextra

# Com timeout customizado (10 segundos)
newman run collections/serve_rest_adm.postman_collection.json \
  -e environment/serve_rest.postman_environment.json \
  --timeout-request 10000 \
  -r cli,htmlextra

# Modo verbose (debug detalhado)
newman run collections/serve_rest_adm.postman_collection.json \
  -e environment/serve_rest.postman_environment.json \
  --verbose

☁️ Execução via GitHub Actions

🤖 Execução automática

Os testes são executados automaticamente em cada:

Push para a branch main
Pull Request para a branch main

🔧 Execução manual

Acesse a aba Actions no repositório do GitHub
Selecione o workflow "Run the test collection of the Serve REST API with newman"
Clique em "Run workflow"
Selecione a branch desejada (padrão: main)
Clique em "Run workflow" novamente para confirmar

📊 Relatórios

📋 Tipos de Relatórios

Formato	Descrição	Uso Recomendado
HTML Extra	Relatório detalhado e interativo com gráficos	Análise visual completa e apresentações
HTML	Relatório padrão em HTML	Documentação e arquivamento simples
CSV	Dados tabulares exportáveis	Análise quantitativa em Excel/Sheets
JSON	Dados estruturados em formato JSON	Integração com outras ferramentas

🔍 Visualizar Relatórios

Relatórios Locais

Após a execução local, abra os arquivos HTML no navegador:

# Linux/macOS
open newman_reports/report-adm-htmlextra.html

# Windows
start newman_reports/report-adm-htmlextra.html

Relatórios do GitHub Actions

Acesse a aba Actions no repositório
Selecione a execução desejada
Na seção Artifacts, faça o download de Reports
Extraia o arquivo ZIP e abra os relatórios HTML
OU verifique o step deploy-github-pages que contém a URL do GitHub Pages

GitHub Pages

Se os testes passarem, os relatórios são publicados automaticamente. Para acessar:

Opção 1: Acesse diretamente a URL:

https://sthefanyricardo.github.io/testes-api-postman-newman/

Opção 2: Via GitHub

Acesse a aba Settings do repositório
Navegue até Pages na barra lateral
Clique na URL listada em Your site is live at...

Opção 3: Via Logs do Pipeline

Acesse a aba Actions
Selecione a execução desejada
Veja a URL no step deploy-github-pages

🤝 Contribuindo

Contribuições são muito bem-vindas! Para contribuir com este projeto:

Como Contribuir

Fork o projeto

Crie uma branch para sua feature:

git checkout -b feature/MinhaNovaFeature

Commit suas mudanças:

git commit -m 'Add: nova funcionalidade X'

Push para a branch:

git push origin feature/MinhaNovaFeature

Abra um Pull Request

Diretrizes

✅ Siga os padrões de código existentes
✅ Adicione testes para novas funcionalidades
✅ Atualize a documentação conforme necessário
✅ Mantenha os commits pequenos e focados
✅ Descreva claramente as mudanças no PR

Reportar Bugs

Encontrou um bug? Abra uma issue com:

Descrição clara do problema
Passos para reproduzir
Comportamento esperado vs obtido
Versões (Node.js, Newman, SO)

🙏 Agradecimentos

Agradecimentos especiais a:

Priscila Caimi - Instrutora do curso no Qualiters Club, pela excelente didática e conteúdo de qualidade
Paulo Gonçalves - Criador da ServeRest API, pela ferramenta educacional incrível e suporte à comunidade
ServeRest - Pela API open source e documentação excelente
Postman - Pela plataforma robusta e completa de testes de API
Newman Team - Pelo executor CLI poderoso e extensível

📞 Contato

Sthefany Albuquerque Ricardo

GitHub: @sthefanyricardo
Linkedin: @sthefanyricardo

🔗 Links Úteis

📚 Documentação

🎓 Cursos

👥 Comunidade

Postman Community - Fórum oficial do Postman
ServeRest GitHub - Repositório da API
Postman Public Workspace - Workspace público com as coleções

⭐ Se este projeto foi útil para você, considere dar uma estrela!

Desenvolvido com ❤️ por Sthefany Ricardo

⬆ Voltar ao topo

Name		Name	Last commit message	Last commit date
Latest commit History 153 Commits
.github		.github
collections		collections
docs		docs
environment		environment
README.md		README.md

sthefanyricardo/testes-api-postman-newman

Folders and files

Latest commit

History

Repository files navigation