Skills
skills/smithery.ai/postman-execution

postman-execution

SKILL.md

Postman Execution - Comandos e Automação

Skill para executar operações Postman: converter OpenAPI, executar testes, gerar relatórios.

Quando Usar

Aplicar esta skill quando o agente for instruído a:

  • Converter OpenAPI/Swagger em collection Postman
  • Executar testes de uma collection Postman
  • Gerar relatórios de testes
  • Validar collection Postman
  • Atualizar collection a partir de OpenAPI

Comandos Disponíveis

1. Converter OpenAPI → Postman Collection

Comando: make postman-generate ou make postman-generate OPENAPI=openapi.json OUTPUT=postman

O que faz:

  • Converte arquivo OpenAPI/Swagger em collection Postman
  • Instala openapi-to-postmanv2 se necessário
  • Gera postman/collection.json

Quando usar:

  • Quando OpenAPI foi atualizado
  • Quando precisa gerar collection automaticamente
  • Antes de executar testes pela primeira vez

Exemplo:

# Usar defaults (openapi.json → postman/collection.json)
make postman-generate

# Especificar arquivo e diretório
make postman-generate OPENAPI=docs/swagger.json OUTPUT=postman

2. Executar Testes Postman (Newman)

Comando: make postman-test ou make postman-test COLLECTION=postman/collection.json ENV=postman/environment.json

O que faz:

  • Executa todos os requests da collection Postman
  • Roda test scripts de cada request
  • Gera relatórios (CLI, JUnit XML, HTML)
  • Retorna código de saída (0 = sucesso, != 0 = falha)

Quando usar:

  • Para validar que a API está funcionando
  • Após fazer mudanças na API
  • No CI/CD pipeline
  • Para gerar relatórios de testes

Exemplo:

# Usar defaults (postman/collection.json, postman/environment.json)
make postman-test

# Especificar collection e environment
make postman-test COLLECTION=postman/api.json ENV=postman/prod.json

Relatórios gerados:

  • reports/postman/junit-results.xml - Para integração com CI/CD
  • reports/postman/report.html - Relatório visual HTML

3. Validar Collection Postman

Comando: make postman-validate ou make postman-validate COLLECTION=postman/collection.json

O que faz:

  • Valida se a collection Postman está bem formada
  • Verifica estrutura JSON
  • Verifica se tem requests válidos
  • Não executa testes, apenas valida estrutura

Quando usar:

  • Antes de commitar collection
  • Após gerar collection a partir de OpenAPI
  • Para verificar se collection está correta

Exemplo:

# Validar collection padrão
make postman-validate

# Validar collection específica
make postman-validate COLLECTION=postman/api.json

4. Atualizar Collection a partir de OpenAPI

Comando: make postman-update ou make postman-update OPENAPI=openapi.json

O que faz:

  • Converte OpenAPI → Postman Collection
  • Preserva scripts customizados (se possível)
  • Atualiza endpoints e schemas

Quando usar:

  • Quando OpenAPI foi atualizado e collection precisa ser atualizada
  • Para manter collection sincronizada com código

Exemplo:

# Atualizar collection padrão
make postman-update

# Especificar arquivo OpenAPI
make postman-update OPENAPI=docs/swagger.json

Regras de Execução para Agentes

1. SEMPRE executar comandos diretamente

  • ❌ NUNCA apenas mostrar o comando para o usuário
  • ✅ SEMPRE executar via make ou diretamente
  • ✅ SEMPRE analisar a saída e reportar resultados

2. Verificar pré-requisitos

Antes de executar qualquer comando:

# Verificar se Node.js está instalado
node --version

# Verificar se collection existe (para testes)
test -f postman/collection.json

# Verificar se OpenAPI existe (para conversão)
test -f openapi.json

3. Analisar resultados

Após executar:

  • Sucesso: Reportar quantos testes passaram
  • Falha: Analisar erros e sugerir correções
  • Conversão: Verificar se collection foi gerada corretamente

4. Workflow recomendado

1. Verificar se OpenAPI existe → Se não, informar usuário
2. Executar make postman-generate → Gerar collection
3. Validar collection → make postman-validate
4. Executar testes → make postman-test
5. Analisar relatórios → Reportar resultados

Estrutura de Diretórios Esperada

projeto/
├── openapi.json              # Ou swagger.json, docs/openapi.yaml
├── postman/
│   ├── collection.json       # Collection gerada/atualizada
│   └── environment.json      # Variáveis de ambiente
├── reports/
│   └── postman/              # Relatórios gerados (gitignored)
│       ├── junit-results.xml
│       └── report.html
└── Makefile                  # Comandos disponíveis

Tratamento de Erros

Erro: OpenAPI não encontrado

Ação:

  1. Informar que arquivo OpenAPI não foi encontrado
  2. Sugerir locais comuns: openapi.json, swagger.json, docs/openapi.yaml
  3. Perguntar se usuário quer gerar OpenAPI primeiro

Erro: Collection não encontrada

Ação:

  1. Informar que collection não existe
  2. Sugerir executar make postman-generate primeiro
  3. Ou perguntar se usuário quer criar collection manualmente

Erro: Testes falharam

Ação:

  1. Analisar relatório HTML ou JUnit XML
  2. Identificar quais requests falharam
  3. Verificar se é problema na API ou na collection
  4. Sugerir correções

Erro: openapi-to-postmanv2 não instalado

Ação:

  1. Instalar automaticamente: npm install -g openapi-to-postmanv2
  2. Se falhar, informar usuário para instalar manualmente
  3. Continuar com conversão após instalação

Checklist de Execução

Antes de executar qualquer comando:

  • Verificar se pré-requisitos estão instalados (Node.js, npm)
  • Verificar se arquivos necessários existem (OpenAPI ou Collection)
  • Executar comando via make quando disponível
  • Analisar saída do comando
  • Reportar resultados ao usuário
  • Em caso de erro, analisar e sugerir correções

Exemplos de Uso pelos Agentes

Cenário 1: Gerar Collection pela primeira vez

# Agente executa:
make postman-generate

# Analisa saída:
# ✅ Collection gerada em postman/collection.json
# ⚠️  PRÓXIMOS PASSOS: Adicionar scripts de autenticação

# Agente reporta:
"Collection Postman gerada com sucesso. Próximo passo: adicionar scripts de autenticação."

Cenário 2: Executar testes

# Agente executa:
make postman-test

# Analisa saída:
# ✅ 15/15 testes passaram
# Relatórios: reports/postman/report.html

# Agente reporta:
"Todos os testes passaram (15/15). Relatório disponível em reports/postman/report.html"

Cenário 3: Atualizar collection

# Agente executa:
make postman-update

# Analisa saída:
# ✅ Collection atualizada
# ⚠️  Verificar scripts customizados

# Agente reporta:
"Collection atualizada. Verifique se scripts de autenticação foram preservados."

Referências

Weekly Installs
1
Source
smithery.ai/ski…xecution
First Seen
3 days ago
Installed on
antigravity1