✦ Open Source · MIT · v3.8.0

API Testing,
Engineered.

A modular, zero-dependency engine for Postman & Newman. Write tests once — get assertions, snapshots, docs, HTML reports, and CI integration automatically.

20+assertion operators
12pipeline modules
10+CLI tools
30automated tests
method.post-request.js
// 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"));
Everything in one engine

No more copy-pasting assertion boilerplate across hundreds of requests. One engine, every request, zero duplication.

🔬

20+ Assertion Operators

exists · absent · eq · ne · gt · gte · lt · lte · type · minLen · maxLen · includes · matches · soft · when — per field or as a structural shape check.

assertions · assertShape
📸

Snapshot Regression

Save response baselines automatically. Strict or non-strict mode. ignorePaths for dynamic fields. Visual diff in console & browser viewer.

snapshot · snapshot-viewer
🔐

Auth — All Patterns

Basic, Bearer, custom headers, OAuth2 client_credentials with auto-refresh & token cache. Configured once in defaults, overrideable per request.

basic · bearer · oauth2cc
🔢

Array Validation

assertEach validates every item against rules. assertUnique detects duplicates. assertOrder verifies sort direction. Respects global softFail.

assertEach · assertUnique · assertOrder

Retry & Resilience

retryOnStatus auto-retries on 503/429. Assertion pipeline skipped on intermediate retries. Counter in pm.variables, auto-cleared on success.

retryOnStatus
🎲

Random Test Data

Built-in generators: uuid, email, str, int, float, bool, pick, date. Auto-injects into pm.variables via randomData — use {{email}} in URL/Body.

ctx.random · randomData
📅

Date Utilities

today, tomorrow, startOfMonth, endOfMonth, today±7d, today±3m and more. Custom date variables injected as pm.variables before every request.

dateUtils · dates config
🔒

Secret Masking

Sensitive fields auto-redacted in console logs. Configurable key patterns. URL masking. CI JSON output never leaks tokens or credentials.

secrets · ci
🧩

Plugin System

Extend post-request with custom JS modules. Slack/Teams notifications, custom assertions, anything. Executed after the core pipeline.

hephaestus.plugins
What teams use it for

From solo dev to CI pipeline — Hephaestus fits any API testing workflow.

Use case 01

Regression Testing on Every Deploy

Snapshot every API response on staging. Run Newman in CI after each deploy. If the response shape changes unexpectedly — build fails. Zero effort baselines.

snapshotnewmangithub-actions
Use case 02

API Contract Verification

Use assertShape to enforce the exact contract your frontend depends on. Declare expected field types per endpoint. Fail fast when backend breaks the contract.

assertShapeassertionscontract
Use case 03

Data-driven Load Scenarios

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.

data-drivencsvctx.iteration
Use case 04

OAuth2 Auth Flow Testing

Configure OAuth2 client_credentials once in defaults. Token fetched, cached, and auto-refreshed. Test protected endpoints without manual token management.

oauth2ccauthtoken-cache
Use case 05

Flaky API Handling

Third-party API returns 503 intermittently? Set retryOnStatus: {statuses:[503,429], maxRetries:3}. Engine retries automatically, pipeline skips on interim retries.

retryOnStatusresilience503
Use case 06

Pagination & List Validation

assertEach validates every item in data.items. assertOrder checks sort direction. assertUnique detects duplicate IDs. All in 10 lines of override config.

assertEachassertOrderassertUnique
Modular pipeline, shared context

Every module receives the same ctx object. Override anything per-request. Defaults from hephaestus.defaults collection variable.

PRE-REQUEST

configMerge
defaults + override
envRequired
pre-flight
iterationData
ctx.iteration
random
ctx.random
urlBuilder
{{baseUrl}}
auth
basic/bearer/oauth2cc
dateUtils
date variables
logger
summary

POST-REQUEST

configMerge
merge
retryOnStatus
auto-retry
normalizeResponse
parse body
metrics
status/time/size
extractor
ctx.api.get()
assertions
keysToFind · map
assertEach
array items
assertShape
type check
assertOrder
sort order
assertUnique
no dupes
assertHeaders
headers
snapshot
regression
schema (tv4)
JSON Schema
plugins
custom
logger
summary
CLI tools for every workflow

Everything runs with npm run <command>. No special setup, no global installs required.

📝

API Docs Generator

Generates Markdown docs from your Postman collection. Your tests are your docs.

npm run docs -- col.json
📊

Run Summary

Per-folder pass rates, top-5 slowest endpoints, most-failed assertions. Console or Markdown.

npm run summary -- results.json
🔍

Run Comparator

Diff two Newman runs. New failures, regressions, perf changes. CI-friendly exit code.

npm run compare -- a.json b.json
👁️

Watch Mode

Auto re-run Newman on file change. Press R to force rerun. Like jest --watch for APIs.

npm run watch -- -c col.json
📄

HTML Report

Self-contained HTML report with charts, pass rates, and full assertion details.

npm run report -- results.json
📋

JUnit XML

Convert Newman JSON to JUnit XML for Jenkins, GitLab, and any other CI systems.

npm run ci-to-junit -- results.json
🚚

Migration Tool

Scan any Postman collection and classify which requests need migration.

npm run migrate -- col.json
🧙

Init Wizard

Interactive setup: generates defaults.json and environment file template in seconds.

npm run init
📸

Snapshot Viewer

Visual browser UI for comparing response snapshots. Filter, diff, inspect.

Open →
🐳

Docker Runner

Run Newman in Docker without a local Node.js install. Generates all reports.

bash scripts/docker-run.sh
🔬

Test Suite (30 tests)

Automated tests for all tooling scripts. Runs in CI on every push.

npm test
📖

Config Reference

Every config option with type, default, examples and version. Searchable.

Open →
Real-world patterns
Shape Check
assertEach
OAuth2 + Retry
Data-driven
CI Mode
GET /users/:id — structural check
const 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"] },
};
GET /products — validate every array item
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"
  },
};
POST /orders — OAuth2 + retry on 503
// 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" }
  }
};
Data-driven + random data generators
// 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
};
CI/CD — GitHub Actions pipeline
# .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
Beyond vanilla Postman

You already know Postman. Hephaestus doesn't replace it — it supercharges it.

Vanilla Postman scripts
Assertion boilerplate copy-pasted in every request
No consistent structure between team members
Auth logic duplicated per-request
No snapshot regression testing
No HTML reports without external tools
Secrets visible in console logs
No array item validation
CI integration requires custom scripting
With Hephaestus
One engine, all requests — zero duplication
Consistent declarative override pattern
Auth configured once in defaults, overrideable per-request
Snapshot baselines auto-saved, visual diffs
Beautiful HTML report with npm run report
Auto-masking for token, password, secret, key
assertEach, assertShape, assertOrder, assertUnique
JUnit XML, GitHub Actions, Docker — ready to go
Frequently asked
Do I need Node.js installed?
No. The engine runs entirely inside Postman's JavaScript sandbox — no Node.js, no npm, no local setup required. Node.js is only needed if you want to use the CLI tools (npm run docs, npm run summary, etc.) or run Newman from the terminal.
Does it work with Apidog?
Yes. Apidog exposes the same 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.
Can I use it with my existing collection?
Yes. Load the engine once (via the engine-update helper request), add 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.
What's the difference from plain pm.test()?
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.
How does softFail work?
Set 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.
Is it free? Can I use it commercially?
Yes and yes. Hephaestus is MIT-licensed — free forever, for any purpose, including commercial use. No attribution required, no royalties, no restrictions. See the LICENSE file.
How do I update the engine?
Run the 🔧 engine-update request inside the Hephaestus System folder in your collection. It fetches the latest engine from GitHub and saves it to collection variables automatically. Your override configs are not affected — only the engine code is updated.
Does it support GraphQL?
Hephaestus works with any HTTP API — GraphQL included. Since GraphQL returns JSON over HTTP, all assertion operators (assertShape, assertEach, assertions map) work on the response body. The engine doesn't parse GraphQL-specific syntax, but you can validate data.* and errors fields just like any REST response.

Ready to ship better APIs?

Get started in 5 minutes. Load the engine, write your first override, run it.

🚀 Quick Start 📖 Config Reference ⭐ Star on GitHub