postman
π―SkillInstallation
npx skills add g1joshi/agent-skills --skill postmanRun it in a terminal; it asks which AI coding tools to install it for (Claude Code, Codex, Cursor and more).
Uses skills.sh Β· Node.js 22.20+
After installing
Ask for related work and the agent uses it on its own, or call it yourself.
/postmanInstall by hand
Copy the whole skill folder from GitHub to the place below. Copying only SKILL.md can leave out files the skill uses.
Open the skill folder β- This project
.claude/skills/postman/ - All projects
~/.claude/skills/postman/
These paths are for Claude Code. For other tools, the command above puts it in the right place.
SKILL.md
View on GitHub βExpert Postman assistance covering API collection design, pre-request scripts, Newman CI/CD test automation, mock servers, and environment variable management. Use when creating automated API test suites, running collections via Newman CLI, managing environment secrets, or generating API documentation.
Postman
Postman is an API platform for building and using APIs, providing automated collection testing, mock servers, environment management, and Newman CLI integration for CI/CD.
When to Use
- REST, GraphQL, & gRPC API Testing: Designing requests, inspecting headers, and verifying streaming payloads.
- Automated CI/CD API Regression Suites: Running Postman Collections in automated pipelines using the Newman CLI.
- Dynamic Authentication Handling: Scripting OAuth 2.0 token refreshes, HMAC signatures, and AWS SigV4 in Pre-request scripts.
- Mock Servers & API Documentation: Creating instant mock endpoints and publishing interactive team API documentation.
Quick Start
1. Test Script in Postman
// Tests tab in Postman Request
pm.test("Status code is 200 OK", function () {
pm.response.to.have.status(200);
});
pm.test("Response time is under 400ms", function () {
pm.expect(pm.response.responseTime).to.be.below(400);
});
pm.test("Token returned and set in environment", function () {
const jsonData = pm.response.json();
pm.expect(jsonData.access_token).to.be.a("string");
pm.environment.set("AUTH_TOKEN", jsonData.access_token);
});
2. Run via Newman CLI
npm install -g newman
newman run collection.json -e environment.json --reporters cli,junit
Core Concepts
Pre-Request Script: Automated JWT / HMAC Signature
Generating dynamic cryptographic signatures and injecting timestamps before request execution:
// Pre-request Script (PM API)
const timestamp = Math.floor(Date.now() / 1000).toString();
const apiKey = pm.environment.get("API_KEY");
const apiSecret = pm.environment.get("API_SECRET");
const requestBody = pm.request.body.raw || "";
// Generate SHA256 HMAC
const message = `${pm.request.method}\n${pm.request.url.getPath()}\n${timestamp}\n${requestBody}`;
const signature = CryptoJS.HmacSHA256(message, apiSecret).toString(
CryptoJS.enc.Hex,
);
pm.request.headers.add({ key: "X-Auth-Key", value: apiKey });
pm.request.headers.add({ key: "X-Auth-Timestamp", value: timestamp });
pm.request.headers.add({ key: "X-Auth-Signature", value: signature });
Automated Response Assertions & Variable Extraction
Validating HTTP response code, schema, and saving output for downstream requests:
// Tests Script
pm.test("Status code is 200 OK", function () {
pm.response.to.have.status(200);
});
pm.test("Response contains valid user session", function () {
const json = pm.response.json();
pm.expect(json).to.have.property("access_token");
pm.expect(json.expires_in).to.be.above(0);
// Propagate access token to active environment
pm.environment.set("AUTH_TOKEN", json.access_token);
});
pm.test("Response time is under 300ms", function () {
pm.expect(pm.response.responseTime).to.be.below(300);
});
Newman CLI Execution in CI/CD Pipeline
Executing collection tests headlessly and generating JUnit reports:
# Run Postman collection with environment and HTML/JUnit reports
npx newman run ./collections/auth-api-tests.json \
-e ./environments/staging.postman_environment.json \
--reporters cli,junit \
--reporter-junit-export ./reports/newman-results.xml \
--bail \
--env-var "BASE_URL=https://staging-api.example.com"
Common Patterns
Pre-Request HMAC Signature Generation
Problem: API requests require timestamp and SHA-256 HMAC signature headers calculated per request.
Solution: Generate headers dynamically in the Pre-request Script tab.
const secret = pm.environment.get("API_SECRET");
const timestamp = Math.floor(Date.now() / 1000).toString();
const payload = pm.request.body.raw || "";
const message = `${timestamp}.${pm.request.method}.${payload}`;
const signature = CryptoJS.HmacSHA256(message, secret).toString();
pm.request.headers.add({ key: "X-Timestamp", value: timestamp });
pm.request.headers.add({ key: "X-Signature", value: signature });
Chained API Testing (Login -> Create -> Delete)
Problem: Execute multi-step end-to-end user workflows using dynamically extracted identifiers.
Solution: Set variables in pm.collectionVariables and trigger conditional next requests via postman.setNextRequest().
// Step 1: Capture created resource ID
const res = pm.response.json();
pm.collectionVariables.set("ITEM_ID", res.id);
// Conditionally skip to cleanup on error
if (pm.response.code !== 201) {
postman.setNextRequest("Cleanup Endpoint");
}
Best Practices
Do:
- Parameterize environment URLs, tenant IDs, and credentials using
{{base_url}}variables. - Store sensitive credentials in Environment variables with type Secret to mask values from UI and exports.
- Run collections via Newman in CI/CD workflows to prevent regressions before deployment.
- Organize collections by domain resource with clear folder-level authorization inheritance.
Don't:
- Hardcode raw JWT tokens or passwords directly in request headers or body payloads.
- Commit environment files containing active production API keys to public repositories.
- Duplicate authentication headers manually; configure Auth at the Collection level.
Troubleshooting
| Error | Cause | Solution |
|---|---|---|
SSL Error: Self-signed certificate in certificate chain | Target endpoint uses local dev or untrusted SSL certificate | Turn off SSL certificate verification in Postman Settings > General, or pass --insecure to Newman. |
Variable not substituting ({{API_URL}} remains literal) | Active environment not selected in dropdown or variable misspelled | Ensure environment dropdown in top-right is selected and scope matches (environment vs collectionVariables). |
| Newman exit code failure in CI pipeline | Assertion failed in collection run | Check test summary output; run Newman with --bail to stop on first failure or inspect JUnit XML report. |
References
More from this repository10
A template skill providing a starter framework for creating new agent skills with structured sections for triggers, quick start examples, and capability descriptions.
Skill
Skill
Skill
Skill
Skill
Skill
Skill
Skill
Skill