All Features

Complete reference for every module, assertion operator, and tool in Hephaestus v3.8.

🔬

Assertion System

post-request

assertions map

Per-field assertion rules using a shorthand map. Supports all operators below. Each field can have multiple operators. Conditional logic via when.

  • Use soft: true per-rule to log warning instead of failing
  • Use when: "expression" to conditionally skip
  • Global softFail: true applies soft behavior to all assertions

keysToFind

Simple key existence check. Specify a dot-notation path — the engine walks the response body and confirms the key exists (or is absent with ! prefix).

assertions map example
assertions: {
  "data.id":     { exists: true, type: "number" },
  "data.email":  { matches: "@" },
  "data.score":  { gte: 0, lte: 100 },
  "data.name":   { minLen: 1, maxLen: 100 },
  "data.active": {
    eq: true,
    soft: true,   // warning only
    when: "ctx.response.code === 200"
  },
  "data.items":  { type: "array", minLen: 1 },
  "error":       { absent: true },
},

keysToFind: ["data.id", "data.name", "!error"],
exists

Key exists in response

absent

Key must NOT be present

eq

Strict equality

ne

Not equal

gt

Greater than (number)

gte

Greater than or equal

lt

Less than (number)

lte

Less than or equal

type

typeof check

minLen

Min string/array length

maxLen

Max string/array length

includes

String/array includes

matches

Regex or substring match

soft

Log warning, don't fail

when

Conditional skip expression

absent

Must not exist

📐

assertShape · assertOrder · assertUniquev3.6v3.8

post-request

assertShape — structural type check

Quick one-liner per field: declare the expected type. Options:

  • "string" "number" "boolean"
  • "object" "array"
  • "absent" — field must NOT exist
  • "any" — field must exist, any type

assertOrder — verify sort direction

Checks that an array is sorted by a field in the given direction ("asc" or "desc"). Specify type: "number" or "string".

assertUnique — no duplicatesv3.8

Checks that all values in an array (or sub-field values) are unique. Set by to check a nested field (e.g. "id").

Shape + Order + Unique
assertShape: {
  "data":        "object",
  "data.id":     "number",
  "data.name":   "string",
  "data.items":  "array",
  "data.active": "boolean",
  "error":       "absent",
  "meta":        "any",
},

assertOrder: {
  path:      "data.items",
  by:        "price",
  direction: "asc",
  type:      "number",
},

assertUnique: {
  path: "data.items",
  by:   "id",   // check item.id uniqueness
},
🔢

assertEach — array item validationv3.5

post-request

Per-item rule validation

Validates every element of an array against a set of rules. Same operator syntax as assertions map. Supports minCount / maxCount for array length, and per-rule soft mode.

Global softFail: true makes all rule violations non-fatal.

assertEach
assertEach: {
  path:     "data.products",
  minCount: 1,
  maxCount: 200,
  rules: {
    "id":       { type: "number", gt: 0 },
    "name":     { type: "string", minLen: 1 },
    "price":    { gte: 0 },
    "category": { exists: true },
    "active":   {
      eq: true,
      soft: true,  // warn only per item
    },
  }
},
📸

Snapshot Regression Testing

post-request

How it works

On first run, response body is saved as a baseline in a collection variable. On subsequent runs, the current response is compared against that baseline.

  • strict — exact deep equality
  • non-strict — structure & types only (ignores new keys)
  • ignorePaths — skip dynamic fields (timestamps, IDs)
  • checkPaths — only compare specific sub-paths
📸 Open Snapshot Viewer →
snapshot config
snapshot: {
  enabled:     true,
  mode:        "non-strict",
  ignorePaths: [
    "data.updatedAt",
    "data.requestId",
    "meta.timestamp"
  ],
  checkPaths: ["data.status", "data.type"],
  update: false,  // set true to reset baseline
},
🔐

Authentication

pre-request
Basic Auth
auth: {
  enabled: true,
  type: "basic",
  basic: {
    username: "{{user}}",
    password: "{{pass}}"
  }
},
Bearer Token
auth: {
  enabled: true,
  type: "bearer",
  bearer: {
    token: "{{access_token}}"
  }
},
OAuth2 Client Credentials
auth: {
  enabled: true,
  type: "oauth2cc",
  oauth2cc: {
    tokenUrl: "{{tokenUrl}}",
    clientId: "{{clientId}}",
    clientSecret: "{{secret}}",
    scope: "read write",
  }
},
🎲

Random Data & Date Utilsv3.8

pre-request
ctx.random + randomData
// Option 1: use ctx.random directly in scripts
ctx.random.uuid()          // → "a7f3..."
ctx.random.email()         // → "test42@example.com"
ctx.random.str(8)          // → "xK9mPqRt"
ctx.random.int(1, 100)    // → 42
ctx.random.bool()          // → true/false
ctx.random.pick(['a','b']) // → "a"
ctx.random.date()          // → "2026-04-07"

// Option 2: auto-inject into pm.variables
randomData: {
  "email":   "random.email",
  "userId":  "random.int:1:9999",
  "orderId": "random.uuid",
  "name":    "random.str:10",
}
// → {{email}}, {{userId}}, {{orderId}} in URL/Body
Date Utilities
// Configure in hephaestus.defaults or override
dates: {
  today:          "today",
  tomorrow:       "today+1d",
  yesterday:      "today-1d",
  nextWeek:       "today+7d",
  lastMonth:      "today-1m",
  startOfMonth:   "startOfMonth",
  endOfMonth:     "endOfMonth",
  q1Start:        "startOfQuarter",
}
// → {{today}}, {{tomorrow}} injected as pm.variables
⚡

Resilience & Validationv3.7

pre & post request
retryOnStatus
// Auto-retry on 503 (service unavailable) or 429 (rate limit)
retryOnStatus: {
  statuses:   [503, 429],
  maxRetries: 3,
}
// Uses pm.setNextRequest to loop.
// Assertion pipeline is skipped on intermediate retries.
// Counter auto-cleaned on success.
envRequired
// Pre-flight: halt collection if required vars missing
envRequired: [
  "BASE_URL",
  "API_KEY",
  "CLIENT_SECRET"
]
// Fails fast with clear error message:
// [Hephaestus] ❌ Required env var missing: API_KEY
📋

Logging & softFailv3.8

global config

logLevel: "silent"

No console output. Only CI JSON if ci: true. Good for data-driven runs with thousands of iterations.

logLevel: "minimal"

Single-line summary per request: method, URL, status, time. Compact output for watch mode or large test suites.

logLevel: "normal"

Default. Full bordered summary box with response preview, all assertion results, saved variables.

logLevel: "verbose"

Normal + response headers. Useful for debugging auth, CORS, and caching issues.

softFail: true

Global flag. All assertion failures log as warnings instead of failing the Postman test. Overrides per-rule soft.

ci: true

Outputs structured JSON to console alongside human-readable output. Consumed by ci-to-junit.js.

🛠️

CLI Tools

npm scripts

📝 docs.js

Generate Markdown API docs from a Postman collection. Your tests become your documentation.

npm run docs -- col.json -o API.md

📊 summary.js

Rich Newman run summary: per-folder stats, slowest endpoints, most-failed assertions.

npm run summary -- results.json --md

🔍 compare.js

Diff two Newman runs. Detect regressions, new failures, performance changes. Exit 1 on regression.

npm run compare -- before.json after.json

👁️ watch.js

Auto re-run Newman when collection or env changes. Press R to force rerun. Debounced.

npm run watch -- -c col.json

📄 generate-report.js

Beautiful self-contained HTML report from Newman JSON. Charts, pass rates, details.

npm run report -- results.json

📋 ci-to-junit.js

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

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

🧙 init.js

Interactive setup wizard. Generates defaults.json and environment template.

npm run init

🚚 migrate.js

Scan existing Postman collection and classify which requests need migration to Hephaestus.

npm run migrate -- col.json

🐳 docker-run.sh

Run full Newman + report pipeline in Docker. No local Node.js needed.

bash scripts/docker-run.sh -c col.json