Teste de API Postman/Newman

1) Porquê Postman/Newman

• regravações repetidas e smocks rápidos;
• parametrizar ambientes/segredos;
• métricas de qualidade e relatórios de leitura de máquina.

2) Modelo básico

A coleção é uma árvore de consultas e pastas compartilhadas.

Ambiente - Conjunto de 'Diante' de 'se' para 'para'

Pré-request script - Preparação de assinaturas, tokens, coralização de dados.
Testes - afirmações e preservação de variáveis/artefatos.
Data-files - CSV/JSON para o teste data-driven.
Mock/Monitor - Manadas e verificações periódicas.

<API v1>
├─ _bootstrap (auth, health, seeds)
├─ Public
├─ Authenticated
│  ├─ Accounts
│  ├─ Payments
│  └─ Reports
└─ _teardown (cleanup)

3) Variáveis e segredos

Defina as variáveis com o prefixo explícito «baseUrl», «tenant», «clientId».
Segredos (senhas, clientes _ segredo, chaves HMAC) guardem as variáveis de ambiente CI, não entreguem no repositório.
Use a colecção local à coleção de eventos globals (minimamente possível).

json
{
"name": "stage-eu",
"values": [
{"key":"baseUrl","value":"https://api. stage. example. com","type":"text","enabled":true},
{"key":"tenant","value":"eu-1","type":"text","enabled":true}
]
}

4) Autenticação: modelos

4. 1 OAuth2/OIDC (Client Credentials)

js if (!pm.environment. get("access_token")          Date. now() > pm. environment. get("token_exp")) {
pm. sendRequest({
url: pm. environment. get("authUrl"),
method: 'POST',
header: {'Content-Type':'application/x-www-form-urlencoded'},
body: { mode:'urlencoded', urlencoded:[
{key:'grant_type',value:'client_credentials'},
{key:'client_id',value:pm. environment. get('clientId')},
{key:'client_secret',value:pm. environment. get('clientSecret')},
{key:'scope',value:'payments:read payments:write'}
]}
}, (err, res) => {
pm. environment. set("access_token", res. json(). access_token);
pm. environment. set("token_exp", Date. now()+ (res. json(). expires_in-30)1000);
});
}

A solicitação é 'Autorization: Bearer Se Você Quiser Que Você Possa Usar Esta Coisa.

4. 2 HMAC (webhooks/associados)

js const body = pm. request. body? pm. request. body. raw          '': '';
const ts = Math. floor(Date. now()/1000);
const msg = `${ts}.${body}`;
const sig = CryptoJS. HmacSHA256(msg, pm. environment. get('hmacSecret')). toString();
pm. variables. set('ts', ts);
pm. variables. set('sig', sig);

Os cabeçalhos são 'X-Timestamp: Se não for possível.

5) Testes: aprovação e corelação

Use 'pm. expect(...)` и `pm. test("...", fn)`.
Mantenha os ID para os passos seguintes através de 'pm. collectionVariables. set`.

js pm. test("HTTP 200", () => pm. response. to. have. status(200));
pm. test ("Scheme is valid," () => {
const schema = pm. collectionVariables. get("schema_wallet");
pm. expect(tv4. validate(pm. response. json(), JSON. parse(schema))). to. be. true;
});
pm. test ("Contains id," () => {
const id = pm. response. json(). id;
pm. expect(id). to. be. a('string');
pm. collectionVariables. set("wallet_id", id);
});

6) Validação de esquema (OpenAPI/JSON Schema)

Guarde o JSON Schema em variáveis de coleção ou arquivo individual.
Para OpenAPI: use as lambas prontas no pré-request/teste (ajv, tv4) através de 'pm. sendRequest 'para o arquivo raw ou inline JSON.

js pm. collectionVariables. set("schema_wallet", JSON. stringify({
"type":"object",
"required":["id","currency","balance"],
"properties":{
"id":{"type":"string"},
"currency":{"type":"string","pattern":"^[A-Z]{3}$"},
"balance":{"type":"number","minimum":0}
}
}));

7) Script data-driven

email, password, currency u1@example. com, P@ss1, EUR u2@example. com, P@ss2, USD

A solicitação usa 'se', por exemplo, o 'se'.

newman run collection. json -e stage-eu. json -d users. csv

JSON (matriz de objetos) - conveniente para maletas e estruturas complexas.

8) Maletas negativas e sustentabilidade

• 401/403 (sem token/scope/papel errado).
• 400/422 (validação do esquema, campos obrigatórios, limites).
• 404 (BOLA/recurso alheio).
• 409 (conflitos, chaves idimpotentes).
• 429 (limites) - verifique «Retry-After».
• 5xx - degradação correta e retratos do cliente.

js pm. test ("There is Retry-After at 429," () => {
if (pm. response. code === 429) pm. expect(pm. response. headers. has('Retry-After')). to. be. true;
});

9) Idempotidade, retrai, paginação

Passe 'Idempotency-Key' e certifique-se de que a repetição dá o mesmo 'id/status'.
Teste de paginação com 'limit/offset '/' cursor', duplicado e omissão.
Simulação de retrações no Script de Teste: chamadas em sequência com a mesma chave.

js pm. test ("Idempotent repetition," () => {
pm. sendRequest(pm. request, (err, res2) => {
pm. expect(res2. code). to. eql(pm. response. code);
pm. expect(res2. json(). id). to. eql(pm. response. json(). id);
});
});

10) Newman в CI/CD

10. 1 Iniciar

newman run collection. json \
-e stage-eu. json \
-d data. csv \
--timeout-request 30000 \
--reporters cli,htmlextra,junit \
--reporter-htmlextra-export./reports/report. html \
--reporter-junit-export./reports/junit. xml

10. 2 GitHub Action (fatia)

yaml
- uses: actions/setup-node@v4 with: { node-version: '20' }
- run: npm i -g newman newman-reporter-htmlextra
- run: newman run collection. json -e stage-eu. json --reporters cli,junit --reporter-junit-export reports/junit. xml
- uses: actions/upload-artifact@v4 with: { name: newman-reports, path: reports }

10. 3 Jenkins/GitLab CI

Exporte JUnit ('-reporter-junit-export') para visualização nativa.
No pipline, divida o jobs: smoke (rápido), regressão (completo), segurança (negativo/limite).

10. 4 Docker

docker run --rm -v $PWD:/etc/newman postman/newman \
run collection. json -e stage-eu. json

11) Moki e monitorização

Mock servers Postman - manadas rápidas para frente e contratos.
Monitors é uma prova periódica de smooks da nuvem (latency, 5xx, SSL).
No repositório, mantenha os arquivos de exemplos de respostas para mocos determinados.

12) Teste de dados e limpeza

Crie/remova entidades (_ bootstrap/_ teardown).
Assinale os objetos de teste com o prefixo 'e2e _' e o TTL.

js pm. collectionVariables. set("uniq", Date. now()+"_"+Math. floor(Math. random()1e6));

13) Desempenho «no joelho»

• mede 'pm. response. responseTime`;
• exalem 5-10 iterações e fixem p95/liminares;
• pesada performance em JMeter/k6/Gatling (fora este artigo).

14) Localização e Multiplicidade

Variáveis 'tenant', 'region', 'lang'; alterna nos ambientes.
Os testes devem verificar se os dados não são «fluídos» por tenentes (BOLA-read, cross-tenant proibições).
Coletâneas/pastas individuais para características regionais (limites, moedas).

15) Relatórios e artefatos

Guarde os artefatos CI, repostos HTML, 'junit. & ', logs de respostas incompletas (response bodies).
Ligue o Slack/Teams de notificação de queda de smooks.

16) Qualidade e cobertura

• CRUD per-recurso (200/201/204 + negativos).
• Permissão: rolos/escopos/multi-tenante.
• Paginação/filtros/triagem.
• Idempotação e retraí.
• Limites: 413/414/431/429.
• Formatos e circuitos (JSON Schema/OpenAPI).
• Integrações (webhooks com HMAC/mTLS) - anti-replay.

17) Antipattern

Um «caminho feliz» sem testes negativos.
Tokens de longa vida na coleção/repositório.
Mistura de dados de teste com dados de prod.
Dependência oculta da ordem dos testes sem uma aparente coralização.
Data-files gigantes sem semeadura.
Não há relatórios JUnit/HTML → não há visibilidade na CI.

18) Folha de cheque pró-prontidão

• As coleções estão divididas em domínios, há '_ bootstrap/_ teardown'.
• Ambientes para dave/estágio/prod; segredos do depósito de segredos CI.
• Pre-request для auth (OAuth2/HMAC); os tokens são armazenados e rotativos.
• Testes: positivo + negativo, esquemas (JSON Schema), paginação, 429/Retry-After.
• Idempotidade: Verificação de 'Idempotency-Key', a chamada dupla é equivalente.
• Data-driven CSV/JSON, sufixos aleatórios para exclusividade.
• Newman em CI: JUnit/HTML relatórios, artefatos como build outputs.
• Moki/monitores para rotas-chave; A SLA de smooks.
• Documentação de variáveis, marcas de formatação e ordem de lançamento.

19) TL; DR

Mantenha a lógica dos testes em coleções Postman, os parâmetros em ambientes e faça o teste em CI através do Newman com relatórios JUNit/HTML. Cobre negativos, esquemas, idempotidade, paginação e limites. Correlacione os passos com variáveis, use entradas data-driven e motes/monitores. Os segredos são apenas da CI, os relatórios são artefactos do bildo.