QUICK START GUIDE

Up and running in 5 minutes

Hephaestus runs inside Postman as a collection-level script. No npm install, no build step — just paste and run.

✓ Postman 10+ ✓ Newman 6+ No local Node.js required for Postman MIT License

⚙

Prerequisites

You need Postman (free) and optionally Newman for CI runs:

Postman — download the desktop app (v10 or newer)
Clone or download this repo to get templates and scripts
Optional for CI: npm install -g newman

Tip: If you want to use the CLI tools (npm run docs, npm run compare, etc.), run npm install in the repo root once.

Create or open your collection

You can start fresh or add Hephaestus to an existing collection.

In Postman, click New → Collection
Name it (e.g. My API)
Alternatively, import collection/hephaestus-template.postman_collection.json from this repo — it comes pre-wired

Recommended: Use the template collection. It includes the engine-update helper request, a working example folder, and pre-configured collection variables.

Load the engine into collection variables

The engine lives in two collection variables: hephaestus.v3.pre and hephaestus.v3.post. The easiest way is to run the included setup request:

Open the 🛠️ Hephaestus System folder in the template collection
Run 🔧 engine-update — it fetches the latest engine from GitHub and saves it to collection variables

Or do it manually via the Collection Variables tab — paste the contents of engine/pre-request.js into hephaestus.v3.pre and engine/post-request.js into hephaestus.v3.post.

Collection → Pre-request (one-time setup)

// This is already in the template collection's Pre-request script.
// It loads the engine from GitHub on first run.
const version = pm.collectionVariables.get('hephaestus.version') || 'main';
// Engine is auto-loaded by engine-update.js setup request

Configure hephaestus.defaults

Open Collection Variables and set hephaestus.defaults to a JSON config. This applies to all requests in the collection.

hephaestus.defaults (collection variable)

{
  "baseUrl": "https://api.example.com",
  "auth": { "enabled": false, "type": "none" },
  "expectedStatus": [200, 201, 202],
  "maxResponseTime": 2000,
  "contentType": "json",
  "snapshot": { "enabled": false, "mode": "non-strict" },
  "secrets": ["token", "password", "secret", "key"],
  "ci": false,
  "logLevel": "normal",
  "softFail": false,
  "envRequired": []
}

Copy the full template from setup/defaults.json in the repo. Use the init wizard to generate it interactively:

Terminal

npm run init   # interactive wizard — generates defaults.json + environment template

Add your first request

Every request follows the same pattern: override object in the Pre-request and Test scripts, then eval() to run the engine.

Pre-request Script (copy from templates/method.pre-request.js)

const override = {
  // Optional: override baseUrl for this specific request
  // baseUrl: "https://other-api.example.com",

  // Auth override (if different from defaults)
  // auth: { enabled: true, type: "bearer", token: "{{prod.token}}" },
};

eval(pm.collectionVariables.get("hephaestus.v3.pre"));

Test Script (copy from templates/method.post-request.js)

const override = {

  expectedStatus: 200,
  maxResponseTime: 1000,

  // Check response structure
  assertShape: {
    "data.id":   "number",
    "data.name": "string",
    "error":     "absent",
  },

  // Save a value for the next request
  varsToSave: {
    userId: { path: "data.id", scope: "collection", name: "lastUserId" }
  },

};

eval(pm.collectionVariables.get("hephaestus.v3.post"));

Pro tip: Templates are in templates/. Copy them as starting points for every new request. The engine is the only thing that changes between releases — your override stays the same.

Run & verify

Hit Send in Postman. Open the Console (View → Show Postman Console) to see the Hephaestus output:

Postman Console output

╔══════════════════════════════════════════════════════════════╗
║  HEPHAESTUS v3.8.0  ·  POST-REQUEST
║  📅 2026-04-07 12:34:56 UTC
╠══════════════════════════════════════════════════════════════╣
║  📋  GET  Get User
║  🌐  https://api.example.com/users/42
╠══════════════════════════════════════════════════════════════╣
║  ✅ STATUS  200 — OK
║  ⏱   124 ms   📦 1.2 KB   📄 JSON
╠══════════════════════════════════════════════════════════════╣
║  📤 RESPONSE PREVIEW
──────────────────────────────────────────────────────────────
{ "data": { "id": 42, "name": "John Doe", ... } }
──────────────────────────────────────────────────────────────
║  🧩 shape "data.id": number ✅
║  🧩 shape "data.name": string ✅
║  🧩 shape "error": absent ✅
║  💾 SAVED    'userId' → collection ✅
╚══════════════════════════════════════════════════════════════╝

Check the Test Results tab to see all assertion outcomes. Green = pass. If something fails, you'll see exactly which field and why.

Run in CI with Newman

Export your collection and environment from Postman, then run with Newman:

Terminal

# Install Newman once
npm install -g newman

# Run collection
newman run collection.json \
  -e environments/prod.json \
  --reporter-json-export results.json \
  -r json

# View rich summary
npm run summary -- results.json

# Generate HTML report
npm run report -- results.json report.html

# Convert to JUnit XML for CI
npm run ci-to-junit -- results.json junit.xml

Docker alternative: No Newman install needed.
bash scripts/docker-run.sh -c collection.json -e env.json -o reports/

See the full Newman + CI Guide for GitHub Actions, GitLab CI, and Jenkins examples.

What's next?

Now that you're up and running, explore the full feature set:

📖

Up and running in 5 minutes

Prerequisites

Create or open your collection

Load the engine into collection variables

Configure hephaestus.defaults

Add your first request

Run & verify

Run in CI with Newman

What's next?

Config Reference

All Features

Snapshot Viewer