A modular, zero-dependency engine for Postman & Newman. Write tests once — get assertions, snapshots, docs, HTML reports, and CI integration automatically.
// Every request: just declare what you expect const override = { expectedStatus: 200, maxResponseTime: 1500, // Structural shape check — one line per field assertShape: { "data.id": "number", "data.name": "string", "data.items": "array", "error": "absent", }, // Rich value assertions assertions: { "data.status": { eq: "active" }, "data.score": { gte: 0, lte: 100 }, "data.email": { matches: "@" }, }, snapshot: { enabled: true, mode: "non-strict" }, varsToSave: { token: { path: "data.accessToken", scope: "collection" } } }; eval(pm.collectionVariables.get("hephaestus.v3.post"));
No more copy-pasting assertion boilerplate across hundreds of requests. One engine, every request, zero duplication.
exists · absent · eq · ne · gt · gte · lt · lte · type · minLen · maxLen · includes · matches · soft · when — per field or as a structural shape check.
assertions · assertShapeSave response baselines automatically. Strict or non-strict mode. ignorePaths for dynamic fields. Visual diff in console & browser viewer.
snapshot · snapshot-viewerBasic, Bearer, custom headers, OAuth2 client_credentials with auto-refresh & token cache. Configured once in defaults, overrideable per request.
basic · bearer · oauth2ccassertEach validates every item against rules. assertUnique detects duplicates. assertOrder verifies sort direction. Respects global softFail.
assertEach · assertUnique · assertOrderretryOnStatus auto-retries on 503/429. Assertion pipeline skipped on intermediate retries. Counter in pm.variables, auto-cleared on success.
retryOnStatusBuilt-in generators: uuid, email, str, int, float, bool, pick, date. Auto-injects into pm.variables via randomData — use {{email}} in URL/Body.
ctx.random · randomDatatoday, tomorrow, startOfMonth, endOfMonth, today±7d, today±3m and more. Custom date variables injected as pm.variables before every request.
dateUtils · dates configSensitive fields auto-redacted in console logs. Configurable key patterns. URL masking. CI JSON output never leaks tokens or credentials.
secrets · ciExtend post-request with custom JS modules. Slack/Teams notifications, custom assertions, anything. Executed after the core pipeline.
hephaestus.pluginsFrom solo dev to CI pipeline — Hephaestus fits any API testing workflow.
Snapshot every API response on staging. Run Newman in CI after each deploy. If the response shape changes unexpectedly — build fails. Zero effort baselines.
Use assertShape to enforce the exact contract your frontend depends on. Declare expected field types per endpoint. Fail fast when backend breaks the contract.
Feed Newman a CSV of 10,000 users. Each row runs through the full engine. logLevel:"minimal" keeps output compact. ctx.iteration exposes row data in scripts.
Configure OAuth2 client_credentials once in defaults. Token fetched, cached, and auto-refreshed. Test protected endpoints without manual token management.
Third-party API returns 503 intermittently? Set retryOnStatus: {statuses:[503,429], maxRetries:3}. Engine retries automatically, pipeline skips on interim retries.
assertEach validates every item in data.items. assertOrder checks sort direction. assertUnique detects duplicate IDs. All in 10 lines of override config.
Every module receives the same ctx object. Override anything per-request. Defaults from hephaestus.defaults collection variable.
PRE-REQUEST
POST-REQUEST
Everything runs with npm run <command>. No special setup, no global installs required.
Generates Markdown docs from your Postman collection. Your tests are your docs.
npm run docs -- col.jsonPer-folder pass rates, top-5 slowest endpoints, most-failed assertions. Console or Markdown.
npm run summary -- results.jsonDiff two Newman runs. New failures, regressions, perf changes. CI-friendly exit code.
npm run compare -- a.json b.jsonAuto re-run Newman on file change. Press R to force rerun. Like jest --watch for APIs.
npm run watch -- -c col.jsonSelf-contained HTML report with charts, pass rates, and full assertion details.
npm run report -- results.jsonConvert Newman JSON to JUnit XML for Jenkins, GitLab, and any other CI systems.
npm run ci-to-junit -- results.jsonScan any Postman collection and classify which requests need migration.
npm run migrate -- col.jsonInteractive setup: generates defaults.json and environment file template in seconds.
npm run initRun Newman in Docker without a local Node.js install. Generates all reports.
bash scripts/docker-run.shAutomated tests for all tooling scripts. Runs in CI on every push.
npm testconst override = { expectedStatus: 200, maxResponseTime: 1000, // Type check — one line per field assertShape: { "data": "object", "data.id": "number", "data.name": "string", "data.email": "string", "data.roles": "array", "data.active": "boolean", "error": "absent", // must NOT be present }, // Value assertions assertions: { "data.id": { gt: 0 }, "data.email": { matches: "@" }, "data.active": { eq: true }, "data.roles": { minLen: 1 }, }, snapshot: { enabled: true, mode: "non-strict", ignorePaths: ["data.updatedAt"] }, };
const override = { expectedStatus: 200, // Every item in data.items must satisfy all rules assertEach: { path: "data.items", minCount: 1, maxCount: 100, rules: { "id": { type: "number", gt: 0 }, "name": { type: "string", minLen: 1 }, "price": { type: "number", gte: 0 }, "category": { type: "string" }, "active": { eq: true, soft: true }, // warn only } }, // All IDs must be unique assertUnique: { path: "data.items", by: "id" }, // Items sorted by price ascending assertOrder: { path: "data.items", by: "price", direction: "asc", type: "number" }, };
// pre-request.js const override = { auth: { enabled: true, type: "oauth2cc", oauth2cc: { tokenUrl: "https://auth.example.com/token", clientId: "{{oauth_client_id}}", clientSecret: "{{oauth_client_secret}}", scope: "orders:write", } }, envRequired: ["oauth_client_id", "oauth_client_secret"], }; // post-request.js const override = { expectedStatus: 201, retryOnStatus: { statuses: [503, 429], maxRetries: 3 }, assertShape: { "order.id": "number", "order.status": "string", "error": "absent", }, varsToSave: { orderId: { path: "order.id", scope: "collection", name: "lastOrderId" } } };
// pre-request.js — auto-generate pm.variables const override = { randomData: { "email": "random.email", // → {{email}} "userId": "random.int:1:9999", // → {{userId}} "orderId": "random.uuid", // → {{orderId}} }, }; // OR: newman run -d users.csv — iteration data // Use {{iter.email}}, {{iter.name}} in URL / Body // Access in scripts: ctx.iteration.data.email // post-request.js — conditional assertion const override = { assertions: { "data.token": { exists: true, when: "ctx.response.code === 200" }, }, logLevel: "minimal", // one line per request };
# .github/workflows/api-tests.yml name: API Tests on: [push, pull_request] jobs: test: runs-on: ubuntu-latest steps: - uses: actions/checkout@v4 - run: npm install -g newman - run: | newman run collection.json \ -e environments/prod.json \ --reporter-json-export results.json - run: node scripts/summary.js results.json - run: node scripts/ci-to-junit.js results.json junit.xml - run: | # Detect regressions vs last baseline node scripts/compare.js baseline.json results.json
You already know Postman. Hephaestus doesn't replace it — it supercharges it.
override patternnpm run reportnpm run docs, npm run summary, etc.) or run Newman from the terminal.pm sandbox object as Postman. The engine is fully compatible. Simply paste the engine code into Apidog's pre/post-request script fields the same way you would in Postman.hephaestus.defaults to your collection variables, then add eval(pm.collectionVariables.get("hephaestus.v3.post")) to any request's Test script. Existing scripts continue to work — the engine is additive. Use npm run migrate -- collection.json to see what can be migrated.pm.test() is the primitive — you write assertion logic manually for every request. Hephaestus gives you a declarative config layer on top: instead of writing 50 lines of JS per request, you write 10 lines of JSON-like override. The engine handles status checks, shape validation, auth, snapshots, logging, secret masking, and CI output automatically.softFail: true in defaults or override, and all assertion failures log a warning to console instead of failing the Postman test. Useful for smoke testing — you want to see all issues, not stop at the first failure. You can also set soft: true per individual assertion rule.override configs are not affected — only the engine code is updated.data.* and errors fields just like any REST response.Get started in 5 minutes. Load the engine, write your first override, run it.