v3.8.0
← Home Quick Start Features
🌐 Connection
baseUrl
Base URL for all requests. Used with {{baseUrl}} in request URLs.
stringv3.0
Default:""
// hephaestus.defaults
{ "baseUrl": "https://api.example.com" }

// per-request override (different server)
const override = { baseUrl: "https://auth.example.com" };
defaultProtocol
Auto-prepended if baseUrl has no protocol. Values: https | http.
stringv3.0
Default:"https"
httpshttp
✅ Response Validation
expectedStatus
Expected HTTP status codes. Request passes if response code is in the list. Use for negative testing (e.g. assert 400).
number | number[]v3.2
Default:[200, 201, 202]
// Single status
const override = { expectedStatus: 204 };

// Multiple statuses
const override = { expectedStatus: [200, 201] };

// Negative testing
const override = { expectedStatus: 422 };
contentType
Expected response content type. Determines how the body is parsed.
stringv3.0
Default:"json"
jsonxmltext
expectEmpty
Set to true for requests that return an empty body (e.g. 204 No Content). Skips body parsing.
booleanv3.0
Default:false
const override = { expectedStatus: 204, expectEmpty: true };
maxResponseTime
Maximum allowed response time in milliseconds. Fails the test if response takes longer.
numberv3.1
Default:1000
const override = { maxResponseTime: 3000 }; // 3 seconds
🔐 Authentication
auth.enabled
Master switch for authentication. When false, the auth block is ignored entirely.
booleanv3.0
Default:false
auth.type
Authentication mechanism to use. Each type has its own sub-config keys.
stringv3.0
nonebasicbearerheadersvariablesoauth2cc 
// Basic auth
const override = { auth: { enabled: true, type: "basic", user: "{{login}}", pass: "{{password}}" } };

// Bearer
const override = { auth: { enabled: true, type: "bearer", token: "{{prod.token}}" } };

// OAuth2 client_credentials — auto-refresh
const override = { auth: {
    enabled: true, type: "oauth2cc",
    oauth2cc: {
        tokenUrl:     "https://auth.example.com/oauth/token",
        clientId:     "{{oauth_client_id}}",
        clientSecret: "{{oauth_client_secret}}",
        scope:        "api:read api:write"
    }
} };
📅 Date Utilities
dateFormat
Format string for {{currentDate}} and custom date variables. Tokens: yyyy MM dd hh mm ss.
stringv3.0
Default:"yyyy-MM-dd"
yyyy-MM-dddd.MM.yyyyyyyy-MM-dd'T'hh:mm:ss

Built-in variables (always available): {{currentDate}}, {{monthsAgo1}}, {{monthsAgo3}}, {{monthsAgo6}}, {{monthsAgo12}}

dates
Custom date variables computed at request time. Expressions: today, today+7d, today-1m, startOfMonth, etc.
objectv3.0 
const override = {
    dates: {
        "dateFrom": "startOfMonth",
        "dateTo":   "endOfMonth",
        "nextWeek": "today+7d",
    }
};
// Use {{dateFrom}}, {{dateTo}}, {{nextWeek}} in request URL/body

Expressions: today · yesterday · tomorrow · startOfMonth · endOfMonth · startOfNextMonth · startOfPrevMonth · startOfYear · today±Nd · today±Nw · today±Nm · today±Ny

🔬 Assertions
assertions
Shorthand map of JSONPath assertions. Operators per field: exists, absent, eq, ne, gt/gte/lt/lte, type, minLen/maxLen, includes, matches, soft, when.
objectv3.4 
const override = {
    assertions: {
        "data.id":     { exists: true },
        "data.status": { eq: "active" },
        "data.count":  { gte: 1, lte: 100 },
        "data.items":  { type: "array", minLen: 1 },
        "data.email":  { matches: "@" },
        "meta.error":  { absent: true },
        "data.token":  { exists: true, soft: true },
        "data.extra":  { exists: true, when: "ctx.api.status === 200" },
    }
};
assertEach
Validates every element of an array against a rule set. Same operators as assertions map. Violations are aggregated into a single test.
objectv3.5 
const override = {
    assertEach: {
        path:     "data.items",
        minCount: 1,
        maxCount: 100,
        rules: {
            "id":     { type: "number", gt: 0 },
            "status": { eq: "active" },
            "email":  { matches: "@", soft: true },
        }
    }
};
assertShape
Quick structural type check — one line per field. Types: string | number | boolean | object | array | null | any | absent.
objectv3.6 
const override = {
    assertShape: {
        "data":          "object",
        "data.id":       "number",
        "data.name":     "string",
        "data.items":    "array",
        "data.active":   "boolean",
        "meta":          "any",      // exists, any type
        "error":         "absent",   // must NOT be present
    }
};
assertOrder
Asserts an array is sorted by a given field. Checks consecutive pairs.
objectv3.6 
const override = {
    assertOrder: {
        path:      "data.items",
        by:        "createdAt",
        direction: "desc",     // "asc" | "desc"
        type:      "date"      // "string" | "number" | "date"
    }
};
keysToFind
Array of field checks with optional expect, transform, filter, ignoreCase, soft, when.
arrayv3.0 
const override = {
    keysToFind: [
        { path: "data.id", name: "User ID" },
        { path: "data.status", expect: "active" },
        { path: "data.score", expect: v => v >= 0 },
        { path: "data.role", soft: true, when: "ctx.api.status !== 404" },
    ]
};
varsToSave
Extract values from response and save to Postman variables.
objectv3.0 
const override = {
    varsToSave: {
        token: { path: "data.accessToken", scope: "collection", name: "prod.token" },
        userId: { path: "data.user.id", scope: "environment", name: "USER_ID" },
    }
};

Scope values: collection (default) · environment · local

📨 Header Assertions
assertHeaders
Assert response headers — existence, content match, exact value, absence, or custom predicate.
arrayv3.2 
const override = {
    assertHeaders: [
        { name: "X-Request-Id" },                               // exists
        { name: "Content-Type", expect: "application/json" },  // contains
        { name: "X-Version",    equals: "v2" },               // exact
        { name: "X-Deprecated", absent: true },              // must be absent
        { name: "X-Rate-Limit", label: "Rate limit > 0",
          expect: v => Number(v) > 0 },                        // predicate
    ]
};
📸 Snapshot Regression
snapshot
Regression testing by comparing responses against saved baselines. Baseline saved automatically on first run.
objectv3.0 
const override = {
    snapshot: {
        enabled:         true,
        mode:            "non-strict", // "strict" | "non-strict"
        autoSaveMissing: true,         // save on first run
        checkPaths:      ["data.status", "data.items[*].id"],
        ignorePaths:     ["data.timestamp", "data.requestId"],
    }
};

strict — full deep-equal comparison (with ignorePaths). non-strict — all baseline keys must be present in current response (allows new keys).

Stored in hephaestus.snapshots collection variable. View with Snapshot Viewer or 📋 snapshot-view request.

🔬 JSON Schema Validation
schema
Validate response body against a JSON Schema (draft-07) using the built-in tv4 library.
objectv3.0 
const override = {
    schema: {
        enabled: true,
        definition: {
            type: "object",
            required: ["id", "status"],
            properties: {
                id:     { type: "number" },
                status: { type: "string", enum: ["active", "inactive"] },
            }
        }
    }
};
🧩 Plugin System
hephaestus.plugins (collection variable)
JSON array of plugin descriptors. Each plugin is a self-contained JS function executed after the main pipeline. See docs/plugins/ for ready-to-use examples.
JSON stringv3.2 
// Set in collection Pre-request Script:
pm.collectionVariables.set('hephaestus.plugins', JSON.stringify([
    { name: 'slack-notifier', code: pm.collectionVariables.get('hephaestus.plugin.slack') },
    { name: 'custom-assertions', code: pm.collectionVariables.get('hephaestus.plugin.custom') },
]));

// Plugin receives (ctx) with:
// ctx.api.body, ctx.api.status, ctx.api.headers, ctx.api.responseTime
// ctx.config, ctx.request, ctx.iteration, ctx._meta
🔒 Security & CI
envRequired
List of environment variable names that must be set before the request fires. Prevents cryptic failures from empty variables.
string[]v3.5
Default:[]
// In hephaestus.defaults (all requests):
{ "envRequired": ["BASE_URL", "OAUTH_CLIENT_ID"] }

// Per-request override:
const override = { envRequired: ["PAYMENT_API_KEY"] };
secrets
List of key substrings to mask in logs. Any variable whose name contains one of these strings is replaced with *** in console output.
string[]v3.0
Default:["token", "password", "pass", "secret", "key", "authorization", "session"]
ci
When true, emits a structured [HEPHAESTUS_CI] {json} line to console after each request. Used by scripts/ci-to-junit.js and CI pipelines.
booleanv3.0
Default:false
// Enable in defaults for CI runs:
{ "ci": true }

// Or via Newman --env-var:
newman run col.json --env-var ci=true
🆕 v3.7 — v3.8 Features
retryOnStatus
Automatically retries the request when the response status matches. Assertion and snapshot pipeline is skipped on intermediate retries.
objectv3.7 
const override = {
    retryOnStatus: {
        statuses:   [503, 429],  // retry on these HTTP codes
        maxRetries: 3             // default: 3
    }
};

Counter stored in pm.variables (key: hephaestus.retry.<requestName>), auto-cleared on success or exhaustion.

softFail
Global soft-fail mode. When true, ALL assertion failures (keysToFind, assertions, assertEach, assertShape, assertOrder, assertUnique) are logged to console but do NOT fail the test run. Ideal for smoke testing.
booleanv3.8
Default:false
// In hephaestus.defaults — smoke test mode:
{ "softFail": true }

// Per-request override — just this request is soft:
const override = { softFail: true };
logLevel
Controls console verbosity. CI JSON (ci: true) is always emitted regardless of logLevel.
stringv3.8
Default:"normal"
silentminimalnormalverbose 
// silent  — no console output (CI JSON still written)
// minimal — one compact line per request: [H] GET Users → ✅ 200 | 123ms | 🔎×3
// normal  — full box layout (default)
// verbose — box + response headers (first 10)
{ "logLevel": "minimal" }
assertUnique
Asserts all values at a path within an array are unique. Respects global softFail.
objectv3.8 
const override = {
    assertUnique: {
        path:  "data.items",  // path to array
        by:    "id",          // field to extract (optional — compares whole item if omitted)
        label: "item IDs"    // optional test label
    }
};
randomData
Auto-populates pm.variables with random test data before the request. Use {{varName}} in URL, body, and headers.
objectv3.8 
// In override or hephaestus.defaults:
const override = {
    randomData: {
        email:   "random.email",        // "user_a3f2@test.com"
        userId:  "random.int:1:9999",   // "4287"
        token:   "random.uuid",         // "550e8400-..."
        name:    "random.str:12",       // "xk8mP2nQ7w3b"
        active:  "random.bool",         // "true"
        dob:     "random.date",         // "1994-07-21"
    }
};
// ctx.random also available directly in plugins:
// ctx.random.uuid(), .email(), .str(n), .int(min,max), .float(), .bool(), .pick(arr), .date()