Quickstart

1 · Prerequisites

To run inside Postman you need nothing but the app. The engine ships embedded in the collection, so there is no package to install and no code to fetch.

• Postman v10 or newer — the free desktop app.
• Optional, for CI and the CLI gates: Node.js 18+ and Newman.

The command-line gates come from a single zero-dependency package. Install it globally, or call it with npx and skip the install:

2 · Import the collection

The shipped collection embeds the engine at build time, so a fresh import is fully self-contained and runs offline.

In Postman, choose Import and select the file:

# from the repo
collection/hephaestus-template.postman_collection.json

The engine lives in two collection variables — hephaestus.v3.pre and hephaestus.v3.post — which the import brings with it. There is no fetch step and no plugin to enable.

3 · Set defaults

Open Collection Variables and set hephaestus.defaults to a JSON object. It applies to every request in the collection; any request can override a single key without touching the rest.

A minimal starting point:

{
  "baseUrl": "https://api.example.com",
  "locale": "en",
  "contentType": "json",
  "auth": { "enabled": false, "type": "none" }
}

4 · Add a request

Each request carries a small override block, then one line evaluates the engine. That line never changes between releases — only the override above it does.

In the request's Tests tab (the post-request pipeline):

const override = {
  expectedStatus: 200,
  maxResponseTime: 1000,
  assertShape: {
    "data.id":   "number",
    "data.name": "string",
    "error":     "absent",
  },
};

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

The Pre-request tab follows the same shape, ending in eval(pm.collectionVariables.get("hephaestus.v3.pre")).

5 · Run & verify

Inside Postman, hit Send. Open the console (View → Show Postman Console) to read the engine output; the Test Results tab lists every assertion, and a failure names the exact field and why.

To run the same request from a terminal, point Newman at the collection with the CLI reporter:

6 · Run in CI

In CI, run Newman with the JSON reporter, then hand the report to the CLI. Each command reads what Newman wrote and exits non-zero on the one thing that regressed — so the build fails for a reason.

newman run collection.json \
  -e env.json \
  -r json \
  --reporter-json-export run.json

Then gate on the run. The p95 latency gate and the run-to-run regression diff are two independent exit codes:

# p95 SLA gate — non-zero if p95 > 1500 ms
hephaestus summary run.json --sla=1500

# regression gate — diff two runs
hephaestus compare before.json run.json

60-second offline demo

Not ready to wire up a real API? One non-interactive command scaffolds a complete demo — a collection, an environment and a README — with no account, no API key and no network.

The collection carries its own recorded snapshots, so hephaestus mock serves those responses back and Newman runs green:

# terminal 1 — serve recorded responses
hephaestus mock \
  hephaestus-demo/demo-collection.json \
  -p 4010

# terminal 2 — run the tests
newman run \
  hephaestus-demo/demo-collection.json \
  -e hephaestus-demo/demo-environment.json

The result is 5 requests and 35 assertions, all green — including a negative test whose expected result is a 404. Every request is copy-pasteable into a real collection, one headline feature at a time.

What's next

You are up and running. From here, go deeper on the engine, look up any config key, or read the source.