@kirrosh/zond 0.12.5 → 0.13.0

package/CHANGELOG.md

@@ -50,6 +50,16 @@ All notable changes to this project will be documented in this file.
 
 ### Added
 
+- **Extended YAML test format** — 12 new assertion operators, flow control, and data transforms:
+  - **Assertion operators**: `not_equals`, `not_contains`, `gte`, `lte`, `length`, `length_gt/gte/lt/lte`
+  - **Array assertions**: `each` (every element matches), `contains_item` (at least one matches), `set_equals` (order-independent comparison)
+  - **Flow control**: `skip_if` (conditional skip with expression evaluator), `retry_until` (retry with condition/max_attempts/delay_ms), `for_each` (iterate over array)
+  - **Data transforms**: `set` steps with directives — `concat`, `append`, `length`, `get`, `first`, `map_field`
+  - **Generator**: `{{$isoTimestamp}}` — ISO 8601 timestamp string
+  - **Expression evaluator**: supports `==`, `!=`, `>`, `<`, `>=`, `<=` for skip_if/retry_until conditions
+  - Guide-builder YAML cheatsheet updated with all new features
+  - Full backward compatibility — all existing tests continue to work unchanged
+
 - **MCP feedback improvements**
   - `diagnose_failure` now includes `response_headers` in failure output (e.g. `X-Ably-ErrorMessage`)
   - `generate_tests_guide`: annotates `any`-typed request bodies with a warning comment

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kirrosh/zond",
-  "version": "0.12.5",
+  "version": "0.13.0",
   "description": "API testing platform — define tests in YAML, run from CLI or WebUI, generate from OpenAPI specs",
   "license": "MIT",
   "module": "index.ts",

package/src/cli/commands/add-api.ts

@@ -7,10 +7,11 @@ export interface AddApiOptions {
   dir?: string;
   envPairs?: string[];
   dbPath?: string;
+  insecure?: boolean;
 }
 
 export async function addApiCommand(options: AddApiOptions): Promise<number> {
-  const { name, spec, envPairs, dbPath, dir } = options;
+  const { name, spec, envPairs, dbPath, dir, insecure } = options;
 
   // Parse --env key=value pairs into a record
   const envVars: Record<string, string> = {};
@@ -31,6 +32,7 @@ export async function addApiCommand(options: AddApiOptions): Promise<number> {
       dir,
       envVars: Object.keys(envVars).length > 0 ? envVars : undefined,
       dbPath,
+      insecure,
     });
 
     printSuccess(`API '${name}' created (id=${result.collectionId})`);

package/src/cli/index.ts

@@ -96,6 +96,7 @@ Options for 'add-api':
   --spec <path-or-url>   OpenAPI spec (extracts base_url from servers[0])
   --dir <directory>      Base directory (default: ./apis/<name>/)
   --env key=value        Set environment variables (repeatable)
+  --insecure             Skip TLS verification (self-signed certs)
 
 Options for 'chat':
   --provider <name>    LLM provider: ollama, openai, anthropic, custom (default: ollama)
@@ -210,6 +211,7 @@ async function main(): Promise<number> {
         dir: typeof flags["dir"] === "string" ? flags["dir"] : undefined,
         envPairs: envValues.length > 0 ? envValues : undefined,
         dbPath: typeof flags["db"] === "string" ? flags["db"] : undefined,
+        insecure: flags["insecure"] === true,
       });
     }
 

package/src/core/generator/guide-builder.ts

@@ -106,18 +106,21 @@ Inline the value directly — there is NO \`params\` field:
 - Array element: \`items.0.name: { exists: true }\`
 - YAML keys must be unique — do NOT repeat \`_body\` twice
 
-### Request body (JSON)
+### Request body — IMPORTANT
+Use \`json:\` for JSON request bodies. Do NOT use \`body:\` — it is not a valid key.
 \`\`\`yaml
   - name: Create resource
     POST: /resources
-    json: { name: "test", email: "a@b.com" }
+    json: { name: "test", email: "a@b.com" }   # correct — use json:
+    # body: { ... }                              # WRONG — body: is not supported
     expect:
       status: 201
       id: { exists: true }
 \`\`\`
+For form-encoded: use \`form:\` instead of \`json:\`.
 
 ### Built-in generators
-\`{{$uuid}}\`, \`{{$randomInt}}\`, \`{{$timestamp}}\`, \`{{$randomName}}\`, \`{{$randomEmail}}\`, \`{{$randomString}}\`
+\`{{$uuid}}\`, \`{{$randomInt}}\`, \`{{$timestamp}}\`, \`{{$isoTimestamp}}\`, \`{{$randomName}}\`, \`{{$randomEmail}}\`, \`{{$randomString}}\`
 
 ### Variable capture & interpolation
 \`\`\`yaml
@@ -136,10 +139,68 @@ Inline the value directly — there is NO \`params\` field:
       id: { equals: "{{created_id}}" }
 \`\`\`
 
+### Array assertions
+\`\`\`yaml
+items:
+  each:                          # every element must match
+    status: { not_equals: "deleted" }
+    id: { type: integer }
+
+items:
+  contains_item:                 # at least one element matches
+    name: { contains: "test" }
+
+ids:
+  set_equals: [1, 2, 3]         # same elements, order-independent
+\`\`\`
+
+### Flow control
+\`\`\`yaml
+  # skip_if — skip step when condition is true (after variable substitution)
+  - name: Delete only if exists
+    DELETE: /items/{{item_id}}
+    skip_if: "{{item_id}} == 0"
+    expect:
+      status: 204
+
+  # retry_until — repeat request until condition met
+  - name: Wait for processing
+    GET: /jobs/{{job_id}}
+    retry_until:
+      condition: "{{status}} == completed"
+      max_attempts: 5
+      delay_ms: 1000
+    expect:
+      status: 200
+
+  # for_each — repeat step for each item in array
+  - name: Delete item
+    DELETE: /items/{{id}}
+    for_each:
+      var: id
+      in: "{{item_ids}}"
+    expect:
+      status: [200, 204]
+
+  # set — transform variables without HTTP request
+  - name: Extract IDs
+    set:
+      all_ids: { map_field: ["{{items}}", "id"] }
+      count: { length: "{{items}}" }
+      first_item: { first: "{{items}}" }
+      merged: { concat: ["{{list_a}}", "{{list_b}}"] }
+\`\`\`
+
 ### Coverage matching
 Use spec paths with \`{param}\` placeholders in the path for coverage to match:
 - Spec says \`GET /products/{id}\` → write \`GET: /products/1\` (hardcode the value)
 - Coverage scanner matches test paths against spec paths automatically
+
+### CRITICAL: Never mask server errors
+- If an endpoint returns 500 — do NOT change expect to \`status: 500\`. Keep \`status: 200\` and let the test fail.
+- A failing test = signal about an API bug. The goal is NOT "all tests green" but "tests reflect expected behavior".
+- Fixing tests means fixing test logic (wrong path, missing auth, bad body), NOT accepting error responses as expected.
+- Legitimate error expectations: 404 for missing resources, 400/422 for invalid input, 401 for no auth — these are negative tests by design.
 `;
 
 export interface GuideOptions {

package/src/core/generator/openapi-reader.ts

@@ -4,10 +4,12 @@ import type { EndpointInfo, ResponseInfo, SecuritySchemeInfo } from "./types.ts"
 
 const HTTP_METHODS = ["get", "post", "put", "patch", "delete"] as const;
 
-export async function readOpenApiSpec(specPath: string): Promise<OpenAPIV3.Document> {
+export async function readOpenApiSpec(specPath: string, options?: { insecure?: boolean }): Promise<OpenAPIV3.Document> {
   // For HTTP URLs, fetch the spec first then dereference the parsed object
   if (specPath.startsWith("http://") || specPath.startsWith("https://")) {
-    const resp = await fetch(specPath);
+    const resp = await fetch(specPath, {
+      ...(options?.insecure ? { tls: { rejectUnauthorized: false } } : {}),
+    });
     if (!resp.ok) throw new Error(`Failed to fetch spec: ${resp.status} ${resp.statusText}`);
     const spec = await resp.json();
     const api = await dereference(spec as string);

package/src/core/generator/serializer.ts

@@ -93,17 +93,53 @@ export function serializeSuite(suite: RawSuite): string {
       serializeValue(test.query, 3, lines);
     }
 
-    // expect
-    lines.push("    expect:");
-    if (test.expect.status !== undefined) {
-      lines.push(`      status: ${test.expect.status}`);
+    // skip_if
+    if (test.skip_if) {
+      lines.push(`    skip_if: ${yamlScalar(String(test.skip_if))}`);
+    }
+
+    // retry_until
+    if (test.retry_until && typeof test.retry_until === "object") {
+      const rt = test.retry_until as Record<string, unknown>;
+      lines.push("    retry_until:");
+      if (rt.condition !== undefined) lines.push(`      condition: ${yamlScalar(String(rt.condition))}`);
+      if (rt.max_attempts !== undefined) lines.push(`      max_attempts: ${rt.max_attempts}`);
+      if (rt.delay_ms !== undefined) lines.push(`      delay_ms: ${rt.delay_ms}`);
     }
-    if (test.expect.body) {
-      lines.push("      body:");
-      for (const [key, rule] of Object.entries(test.expect.body)) {
-        lines.push(`        ${key}:`);
-        for (const [rk, rv] of Object.entries(rule)) {
-          lines.push(`          ${rk}: ${yamlScalar(String(rv))}`);
+
+    // for_each
+    if (test.for_each && typeof test.for_each === "object") {
+      const fe = test.for_each as Record<string, unknown>;
+      lines.push("    for_each:");
+      if (fe.var !== undefined) lines.push(`      var: ${yamlScalar(String(fe.var))}`);
+      if (fe.in !== undefined) lines.push(`      in: ${yamlScalar(String(fe.in))}`);
+    }
+
+    // set
+    if (test.set && typeof test.set === "object") {
+      lines.push("    set:");
+      serializeValue(test.set, 3, lines);
+    }
+
+    // expect
+    const hasExpect = test.expect && (test.expect.status !== undefined || test.expect.body);
+    if (hasExpect) {
+      lines.push("    expect:");
+      if (test.expect.status !== undefined) {
+        lines.push(`      status: ${test.expect.status}`);
+      }
+      if (test.expect.body) {
+        lines.push("      body:");
+        for (const [key, rule] of Object.entries(test.expect.body)) {
+          lines.push(`        ${key}:`);
+          for (const [rk, rv] of Object.entries(rule)) {
+            if (typeof rv === "object" && rv !== null) {
+              lines.push(`          ${rk}:`);
+              serializeValue(rv, 6, lines);
+            } else {
+              lines.push(`          ${rk}: ${yamlScalar(String(rv))}`);
+            }
+          }
         }
       }
     }

package/src/core/generator/suite-generator.ts

@@ -62,10 +62,19 @@ function getAuthHeaders(
     const scheme = schemes.find(s => s.name === secName);
     if (!scheme) continue;
 
-    if (scheme.type === "http" && scheme.scheme === "bearer") {
-      return { Authorization: "Bearer {{auth_token}}" };
+    if (scheme.type === "http") {
+      if (scheme.scheme === "bearer" || !scheme.scheme) {
+        return { Authorization: "Bearer {{auth_token}}" };
+      }
+      if (scheme.scheme === "basic") {
+        return { Authorization: "Basic {{auth_token}}" };
+      }
     }
     if (scheme.type === "apiKey" && scheme.in === "header" && scheme.apiKeyName) {
+      // When apiKey scheme uses Authorization header, it's typically a Bearer token
+      if (scheme.apiKeyName === "Authorization") {
+        return { Authorization: "Bearer {{auth_token}}" };
+      }
       return { [scheme.apiKeyName]: "{{api_key}}" };
     }
   }

package/src/core/parser/schema.ts

@@ -1,5 +1,5 @@
 import { z } from "zod";
-import type { TestSuite, TestStep, AssertionRule, TestStepExpect, SuiteConfig } from "./types.ts";
+import type { TestSuite, TestStep, AssertionRule, TestStepExpect, SuiteConfig, RetryUntil, ForEach } from "./types.ts";
 
 const HTTP_METHODS = ["GET", "POST", "PUT", "PATCH", "DELETE"] as const;
 
@@ -26,11 +26,19 @@ function extractMethodAndPath(raw: unknown): unknown {
     return { ...rest, method: foundMethod, path };
   }
 
+  // set-only step: no HTTP method required
+  if (obj.set && !obj.method) {
+    return { ...obj, method: "GET", path: "" };
+  }
+
   return raw;
 }
 
 const ASSERTION_KEYS = new Set([
-  "capture", "type", "equals", "contains", "matches", "gt", "lt", "exists",
+  "capture", "type", "equals", "not_equals", "contains", "not_contains",
+  "matches", "gt", "lt", "gte", "lte", "exists",
+  "length", "length_gt", "length_gte", "length_lt", "length_lte",
+  "each", "contains_item", "set_equals",
 ]);
 
 /**
@@ -68,7 +76,7 @@ export function flattenBodyAssertions(body: Record<string, unknown>): Record<str
   return result;
 }
 
-const AssertionRuleSchema: z.ZodType<AssertionRule> = z.preprocess(
+const AssertionRuleSchemaInner: z.ZodType<AssertionRule> = z.preprocess(
   (val) => {
     if (typeof val === "string") return { type: val };
     if (val === null || val === undefined) return { exists: true };
@@ -86,14 +94,28 @@ const AssertionRuleSchema: z.ZodType<AssertionRule> = z.preprocess(
     capture: z.string().optional(),
     type: z.enum(["string", "integer", "number", "boolean", "array", "object"]).optional(),
     equals: z.unknown().optional(),
+    not_equals: z.unknown().optional(),
     contains: z.string().optional(),
+    not_contains: z.string().optional(),
     matches: z.string().optional(),
     gt: z.number().optional(),
     lt: z.number().optional(),
+    gte: z.number().optional(),
+    lte: z.number().optional(),
     exists: z.boolean().optional(),
+    length: z.number().int().optional(),
+    length_gt: z.number().int().optional(),
+    length_gte: z.number().int().optional(),
+    length_lt: z.number().int().optional(),
+    length_lte: z.number().int().optional(),
+    each: z.record(z.string(), z.lazy(() => AssertionRuleSchemaInner)).optional(),
+    contains_item: z.record(z.string(), z.lazy(() => AssertionRuleSchemaInner)).optional(),
+    set_equals: z.unknown().optional(),
   }),
 ) as z.ZodType<AssertionRule>;
 
+const AssertionRuleSchema = AssertionRuleSchemaInner;
+
 const TestStepExpectSchema: z.ZodType<TestStepExpect> = z.preprocess(
   (val) => {
     if (typeof val !== "object" || val === null) return val;
@@ -117,8 +139,29 @@ const TestStepExpectSchema: z.ZodType<TestStepExpect> = z.preprocess(
   }),
 ) as z.ZodType<TestStepExpect>;
 
+const RetryUntilSchema: z.ZodType<RetryUntil> = z.object({
+  condition: z.string(),
+  max_attempts: z.number().int().positive(),
+  delay_ms: z.number().int().nonnegative(),
+});
+
+const ForEachSchema: z.ZodType<ForEach> = z.object({
+  var: z.string(),
+  in: z.unknown(),
+});
+
 const TestStepSchema: z.ZodType<TestStep> = z.preprocess(
-  extractMethodAndPath,
+  (raw) => {
+    const obj = extractMethodAndPath(raw);
+    // Make expect optional for set-only steps
+    if (typeof obj === "object" && obj !== null) {
+      const o = obj as Record<string, unknown>;
+      if (o.set && !o.expect) {
+        o.expect = {};
+      }
+    }
+    return obj;
+  },
   z.object({
     name: z.string(),
     method: z.enum(HTTP_METHODS),
@@ -128,6 +171,10 @@ const TestStepSchema: z.ZodType<TestStep> = z.preprocess(
     form: z.record(z.string(), z.string()).optional(),
     query: z.record(z.string(), z.string()).optional(),
     expect: TestStepExpectSchema,
+    skip_if: z.string().optional(),
+    retry_until: RetryUntilSchema.optional(),
+    for_each: ForEachSchema.optional(),
+    set: z.record(z.string(), z.unknown()).optional(),
   }),
 ) as z.ZodType<TestStep>;
 

package/src/core/parser/types.ts

@@ -4,11 +4,23 @@ export interface AssertionRule {
   capture?: string;
   type?: "string" | "integer" | "number" | "boolean" | "array" | "object";
   equals?: unknown;
+  not_equals?: unknown;
   contains?: string;
+  not_contains?: string;
   matches?: string;
   gt?: number;
   lt?: number;
+  gte?: number;
+  lte?: number;
   exists?: boolean;
+  length?: number;
+  length_gt?: number;
+  length_gte?: number;
+  length_lt?: number;
+  length_lte?: number;
+  each?: Record<string, AssertionRule>;
+  contains_item?: Record<string, AssertionRule>;
+  set_equals?: unknown;
 }
 
 export interface TestStepExpect {
@@ -18,6 +30,17 @@ export interface TestStepExpect {
   duration?: number;
 }
 
+export interface RetryUntil {
+  condition: string;
+  max_attempts: number;
+  delay_ms: number;
+}
+
+export interface ForEach {
+  var: string;
+  in: unknown;
+}
+
 export interface TestStep {
   name: string;
   method: HttpMethod;
@@ -27,6 +50,10 @@ export interface TestStep {
   form?: Record<string, string>;
   query?: Record<string, string>;
   expect: TestStepExpect;
+  skip_if?: string;
+  retry_until?: RetryUntil;
+  for_each?: ForEach;
+  set?: Record<string, unknown>;
 }
 
 export interface SuiteConfig {

package/src/core/parser/variables.ts

@@ -19,6 +19,7 @@ function randomChars(len: number): string {
 export const GENERATORS: Record<string, () => string | number> = {
   "$uuid": () => crypto.randomUUID(),
   "$timestamp": () => Math.floor(Date.now() / 1000),
+  "$isoTimestamp": () => new Date().toISOString(),
   "$randomName": () => randomFrom(NAMES),
   "$randomEmail": () => `${randomChars(8).toLowerCase()}@test.com`,
   "$randomInt": () => Math.floor(Math.random() * 10000),

package/src/core/runner/assertions.ts

@@ -90,6 +90,132 @@ function checkRule(path: string, rule: AssertionRule, actual: unknown): Assertio
     });
   }
 
+  if (rule.not_equals !== undefined) {
+    results.push({
+      field, rule: `not_equals ${JSON.stringify(rule.not_equals)}`,
+      passed: !deepEquals(actual, rule.not_equals), actual, expected: rule.not_equals,
+    });
+  }
+
+  if (rule.not_contains !== undefined) {
+    const passed = typeof actual === "string" && !actual.includes(rule.not_contains);
+    results.push({
+      field, rule: `not_contains "${rule.not_contains}"`,
+      passed, actual, expected: rule.not_contains,
+    });
+  }
+
+  if (rule.gte !== undefined) {
+    const passed = typeof actual === "number" && actual >= rule.gte;
+    results.push({
+      field, rule: `gte ${rule.gte}`,
+      passed, actual, expected: rule.gte,
+    });
+  }
+
+  if (rule.lte !== undefined) {
+    const passed = typeof actual === "number" && actual <= rule.lte;
+    results.push({
+      field, rule: `lte ${rule.lte}`,
+      passed, actual, expected: rule.lte,
+    });
+  }
+
+  if (rule.length !== undefined) {
+    const hasLength = (Array.isArray(actual) || typeof actual === "string");
+    const passed = hasLength && (actual as string | unknown[]).length === rule.length;
+    results.push({
+      field, rule: `length ${rule.length}`,
+      passed, actual: hasLength ? (actual as string | unknown[]).length : describeType(actual), expected: rule.length,
+    });
+  }
+
+  if (rule.length_gt !== undefined) {
+    const hasLength = (Array.isArray(actual) || typeof actual === "string");
+    const passed = hasLength && (actual as string | unknown[]).length > rule.length_gt;
+    results.push({
+      field, rule: `length_gt ${rule.length_gt}`,
+      passed, actual: hasLength ? (actual as string | unknown[]).length : describeType(actual), expected: rule.length_gt,
+    });
+  }
+
+  if (rule.length_gte !== undefined) {
+    const hasLength = (Array.isArray(actual) || typeof actual === "string");
+    const passed = hasLength && (actual as string | unknown[]).length >= rule.length_gte;
+    results.push({
+      field, rule: `length_gte ${rule.length_gte}`,
+      passed, actual: hasLength ? (actual as string | unknown[]).length : describeType(actual), expected: rule.length_gte,
+    });
+  }
+
+  if (rule.length_lt !== undefined) {
+    const hasLength = (Array.isArray(actual) || typeof actual === "string");
+    const passed = hasLength && (actual as string | unknown[]).length < rule.length_lt;
+    results.push({
+      field, rule: `length_lt ${rule.length_lt}`,
+      passed, actual: hasLength ? (actual as string | unknown[]).length : describeType(actual), expected: rule.length_lt,
+    });
+  }
+
+  if (rule.length_lte !== undefined) {
+    const hasLength = (Array.isArray(actual) || typeof actual === "string");
+    const passed = hasLength && (actual as string | unknown[]).length <= rule.length_lte;
+    results.push({
+      field, rule: `length_lte ${rule.length_lte}`,
+      passed, actual: hasLength ? (actual as string | unknown[]).length : describeType(actual), expected: rule.length_lte,
+    });
+  }
+
+  if (rule.each !== undefined) {
+    if (!Array.isArray(actual)) {
+      results.push({ field, rule: "each", passed: false, actual: describeType(actual), expected: "array" });
+    } else {
+      for (let i = 0; i < actual.length; i++) {
+        for (const [subPath, subRule] of Object.entries(rule.each)) {
+          const subActual = getByPath(actual[i], subPath);
+          const subResults = checkRule(`${path}[${i}].${subPath}`, subRule, subActual);
+          results.push(...subResults);
+        }
+      }
+    }
+  }
+
+  if (rule.contains_item !== undefined) {
+    if (!Array.isArray(actual)) {
+      results.push({ field, rule: "contains_item", passed: false, actual: describeType(actual), expected: "array" });
+    } else {
+      const found = actual.some((item) => {
+        for (const [subPath, subRule] of Object.entries(rule.contains_item!)) {
+          const subActual = getByPath(item, subPath);
+          const subResults = checkRule("", subRule, subActual);
+          if (subResults.some(r => !r.passed)) return false;
+        }
+        return true;
+      });
+      results.push({
+        field, rule: "contains_item",
+        passed: found, actual: `array(${actual.length})`, expected: "at least one matching item",
+      });
+    }
+  }
+
+  if (rule.set_equals !== undefined) {
+    if (!Array.isArray(actual) || !Array.isArray(rule.set_equals)) {
+      results.push({
+        field, rule: "set_equals",
+        passed: false, actual: describeType(actual), expected: "both must be arrays",
+      });
+    } else {
+      const actualSet = new Set(actual.map(v => JSON.stringify(v)));
+      const expectedSet = new Set((rule.set_equals as unknown[]).map(v => JSON.stringify(v)));
+      const passed = actualSet.size === expectedSet.size && [...actualSet].every(v => expectedSet.has(v));
+      results.push({
+        field, rule: "set_equals",
+        passed, actual, expected: rule.set_equals,
+      });
+    }
+  }
+
   return results;
 }
 

package/src/core/runner/executor.ts

@@ -1,8 +1,10 @@
-import type { TestSuite, Environment } from "../parser/types.ts";
+import type { TestSuite, TestStep, Environment } from "../parser/types.ts";
 import { substituteString, substituteStep, substituteDeep, extractVariableReferences } from "../parser/variables.ts";
 import type { TestRunResult, StepResult, HttpRequest } from "./types.ts";
 import { executeRequest, type FetchOptions } from "./http-client.ts";
 import { checkAssertions, extractCaptures } from "./assertions.ts";
+import { evaluateExpr } from "./expr-eval.ts";
+import { applyTransform } from "./transforms.ts";
 
 function buildUrl(baseUrl: string | undefined, path: string, query?: Record<string, string>): string {
   let url = baseUrl ? `${baseUrl.replace(/\/+$/, "")}${path}` : path;
@@ -38,7 +40,61 @@ export async function runSuite(suite: TestSuite, env: Environment = {}, dryRun =
     follow_redirects: suite.config.follow_redirects,
   };
 
-  for (const step of suite.tests) {
+  // Expand steps lazily (for_each needs current variables)
+  let stepIndex = 0;
+  const rawSteps = [...suite.tests];
+
+  while (stepIndex < rawSteps.length) {
+    const step = rawSteps[stepIndex]!;
+    stepIndex++;
+
+    // Expand for_each: insert expanded steps and skip current
+    if (step.for_each) {
+      const resolvedIn = substituteDeep(step.for_each.in, variables);
+      const items = Array.isArray(resolvedIn) ? resolvedIn : [];
+      const expanded: TestStep[] = [];
+      for (const item of items) {
+        const { for_each: _, ...rest } = step;
+        expanded.push({ ...rest, name: `${step.name} [${step.for_each.var}=${JSON.stringify(item)}]` } as TestStep);
+        // We'll inject the variable right before executing each expanded step
+        // Store the var assignment via a set field
+      }
+      // Insert expanded steps at current position
+      rawSteps.splice(stepIndex, 0, ...expanded);
+      // Set the for_each variable for each expanded step
+      for (let i = 0; i < items.length; i++) {
+        const expandedStep = rawSteps[stepIndex + i]!;
+        // Temporarily inject into variables when we reach this step
+        // We need a way to pass the variable — use a hidden _for_each_vars
+        (expandedStep as Record<string, unknown>).__for_each_var = { key: step.for_each.var, value: items[i] };
+      }
+      continue;
+    }
+
+    // Inject for_each variable if present
+    const forEachData = (step as Record<string, unknown>).__for_each_var as { key: string; value: unknown } | undefined;
+    if (forEachData) {
+      variables[forEachData.key] = forEachData.value;
+      delete (step as Record<string, unknown>).__for_each_var;
+    }
+
+    // Handle set-only steps (no HTTP request)
+    if (step.set && step.path === "") {
+      for (const [key, rawDirective] of Object.entries(step.set)) {
+        const substituted = substituteDeep(rawDirective, variables);
+        variables[key] = applyTransform(substituted);
+      }
+      steps.push({
+        name: step.name,
+        status: "pass",
+        duration_ms: 0,
+        request: { method: "", url: "", headers: {} },
+        assertions: [],
+        captures: {},
+      });
+      continue;
+    }
+
     // Skip check: if step references a failed capture variable, skip it
     const referencedVars = extractVariableReferences(step);
     const missingCapture = referencedVars.find((v) => failedCaptures.has(v));
@@ -47,6 +103,15 @@ export async function runSuite(suite: TestSuite, env: Environment = {}, dryRun =
       continue;
     }
 
+    // skip_if evaluation
+    if (step.skip_if) {
+      const exprAfterSubst = String(substituteString(step.skip_if, variables));
+      if (evaluateExpr(exprAfterSubst)) {
+        steps.push(makeSkippedResult(step.name, `Skipped: ${step.skip_if}`));
+        continue;
+      }
+    }
+
     // Substitute variables
     const resolved = substituteStep(step, variables);
 
@@ -104,6 +169,59 @@ export async function runSuite(suite: TestSuite, env: Environment = {}, dryRun =
       continue;
     }
 
+    // retry_until wrapper
+    if (step.retry_until) {
+      const rt = step.retry_until;
+      let lastStepResult: StepResult | undefined;
+      for (let attempt = 0; attempt < rt.max_attempts; attempt++) {
+        try {
+          const response = await executeRequest(request, fetchOptions);
+          const captures = extractCaptures(resolved.expect.body, response.body_parsed);
+          const assertions = checkAssertions(resolved.expect, response);
+          const allPassed = assertions.every((a) => a.passed);
+
+          lastStepResult = {
+            name: step.name,
+            status: allPassed ? "pass" : "fail",
+            duration_ms: response.duration_ms,
+            request,
+            response,
+            assertions,
+            captures,
+          };
+
+          // Evaluate condition with response context
+          const condVars: Record<string, unknown> = { ...variables, ...captures, status: response.status };
+          if (response.body_parsed && typeof response.body_parsed === "object") {
+            for (const [k, v] of Object.entries(response.body_parsed as Record<string, unknown>)) {
+              condVars[k] = v;
+            }
+          }
+          const condStr = String(substituteString(rt.condition, condVars));
+          if (evaluateExpr(condStr)) {
+            Object.assign(variables, captures);
+            break;
+          }
+
+          if (attempt < rt.max_attempts - 1) {
+            await new Promise((resolve) => setTimeout(resolve, rt.delay_ms));
+          }
+        } catch (err) {
+          lastStepResult = {
+            name: step.name,
+            status: "error",
+            duration_ms: 0,
+            request,
+            assertions: [],
+            captures: {},
+            error: err instanceof Error ? err.message : String(err),
+          };
+        }
+      }
+      if (lastStepResult) steps.push(lastStepResult);
+      continue;
+    }
+
     try {
       const response = await executeRequest(request, fetchOptions);
 

package/src/core/runner/expr-eval.ts

@@ -0,0 +1,41 @@
+const OPERATORS = ["!=", "==", ">=", "<=", ">", "<"] as const;
+
+export function evaluateExpr(expr: string): boolean {
+  const trimmed = expr.trim();
+  if (trimmed === "") return false;
+
+  for (const op of OPERATORS) {
+    const idx = trimmed.indexOf(op);
+    if (idx !== -1) {
+      const left = trimmed.slice(0, idx).trim();
+      const right = trimmed.slice(idx + op.length).trim();
+      return compareValues(left, right, op);
+    }
+  }
+
+  // No operator — truthiness
+  return isTruthy(trimmed);
+}
+
+function compareValues(left: string, right: string, op: string): boolean {
+  const lNum = Number(left);
+  const rNum = Number(right);
+  const numeric = !isNaN(lNum) && !isNaN(rNum) && left !== "" && right !== "";
+
+  switch (op) {
+    case "==": return numeric ? lNum === rNum : left === right;
+    case "!=": return numeric ? lNum !== rNum : left !== right;
+    case ">":  return numeric ? lNum > rNum : left > right;
+    case "<":  return numeric ? lNum < rNum : left < right;
+    case ">=": return numeric ? lNum >= rNum : left >= right;
+    case "<=": return numeric ? lNum <= rNum : left <= right;
+    default: return false;
+  }
+}
+
+function isTruthy(value: string): boolean {
+  if (value === "" || value === "0" || value === "false" || value === "null" || value === "undefined") {
+    return false;
+  }
+  return true;
+}

package/src/core/runner/http-client.ts

@@ -53,6 +53,16 @@ export async function executeRequest(
           // Body is not valid JSON despite content-type
         }
       }
+      // Fallback: for non-JSON responses, store trimmed body as string
+      // so that captures like `_body` work for text/plain, text/html, etc.
+      if (body_parsed === undefined && bodyText.length > 0) {
+        // Try JSON parse as fallback (some APIs omit content-type)
+        try {
+          body_parsed = JSON.parse(bodyText);
+        } catch {
+          body_parsed = bodyText.trim();
+        }
+      }
 
       const headers: Record<string, string> = {};
       response.headers.forEach((v, k) => {

package/src/core/runner/transforms.ts

@@ -0,0 +1,65 @@
+const DIRECTIVES = new Set(["concat", "append", "length", "get", "first", "map_field"]);
+
+export function applyTransform(directive: unknown): unknown {
+  if (typeof directive !== "object" || directive === null || Array.isArray(directive)) {
+    return directive;
+  }
+
+  const obj = directive as Record<string, unknown>;
+  const keys = Object.keys(obj);
+
+  if (keys.length !== 1 || !DIRECTIVES.has(keys[0]!)) {
+    return directive;
+  }
+
+  const op = keys[0]!;
+  const arg = obj[op];
+
+  switch (op) {
+    case "concat": {
+      if (!Array.isArray(arg)) return directive;
+      const result: unknown[] = [];
+      for (const item of arg) {
+        if (Array.isArray(item)) result.push(...item);
+        else result.push(item);
+      }
+      return result;
+    }
+    case "append": {
+      if (!Array.isArray(arg) || arg.length < 2) return directive;
+      const arr = Array.isArray(arg[0]) ? [...arg[0]] : [];
+      return [...arr, ...arg.slice(1)];
+    }
+    case "length": {
+      if (Array.isArray(arg)) return arg.length;
+      if (typeof arg === "string") return arg.length;
+      return 0;
+    }
+    case "get": {
+      if (!Array.isArray(arg) || arg.length < 2) return directive;
+      const [source, index] = arg;
+      if (Array.isArray(source) && typeof index === "number") return source[index];
+      if (typeof source === "object" && source !== null && typeof index === "string") {
+        return (source as Record<string, unknown>)[index];
+      }
+      return undefined;
+    }
+    case "first": {
+      if (Array.isArray(arg)) return arg[0];
+      return undefined;
+    }
+    case "map_field": {
+      if (!Array.isArray(arg) || arg.length < 2) return directive;
+      const [items, field] = arg;
+      if (!Array.isArray(items) || typeof field !== "string") return directive;
+      return items.map((item) => {
+        if (typeof item === "object" && item !== null) {
+          return (item as Record<string, unknown>)[field];
+        }
+        return undefined;
+      });
+    }
+    default:
+      return directive;
+  }
+}

package/src/core/setup-api.ts

@@ -20,6 +20,7 @@ export interface SetupApiOptions {
   envVars?: Record<string, string>;
   dbPath?: string;
   force?: boolean;
+  insecure?: boolean;
 }
 
 export interface SetupApiResult {
@@ -30,6 +31,7 @@ export interface SetupApiResult {
   baseUrl: string;
   specEndpoints: number;
   pathParams?: Record<string, string>;
+  warnings?: string[];
 }
 
 export async function setupApi(options: SetupApiOptions): Promise<SetupApiResult> {
@@ -42,13 +44,17 @@ export async function setupApi(options: SetupApiOptions): Promise<SetupApiResult
   let baseUrl = "";
   let endpointCount = 0;
   const pathParams = new Map<string, string>();
+  const warnings: string[] = [];
   let specTitle: string | undefined;
   if (spec) {
-    const doc = await readOpenApiSpec(spec);
+    const doc = await readOpenApiSpec(spec, { insecure: options.insecure });
     openapiSpec = spec;
     if ((doc as any).servers?.[0]?.url) {
       baseUrl = (doc as any).servers[0].url;
     }
+    if (baseUrl && !baseUrl.startsWith("http://") && !baseUrl.startsWith("https://")) {
+      warnings.push(`Spec server URL "${baseUrl}" is relative — requests will fail without a host. Override with envVars: {"base_url": "https://your-host${baseUrl}"}`);
+    }
     specTitle = (doc as any).info?.title;
     const endpoints = extractEndpoints(doc);
     endpointCount = endpoints.length;
@@ -139,5 +145,6 @@ export async function setupApi(options: SetupApiOptions): Promise<SetupApiResult
     baseUrl,
     specEndpoints: endpointCount,
     ...(pathParamsObj ? { pathParams: pathParamsObj } : {}),
+    ...(warnings.length > 0 ? { warnings } : {}),
   };
 }

package/src/mcp/descriptions.ts

@@ -12,7 +12,8 @@ export const TOOL_DESCRIPTIONS = {
   setup_api:
     "Register a new API for testing. Creates directory structure, reads OpenAPI spec, " +
     "sets up environment variables, and creates a collection in the database. " +
-    "Use this before generating tests for a new API.",
+    "Use this before generating tests for a new API. " +
+    "Warns if spec has relative server URL. Use insecure: true for self-signed HTTPS certs.",
 
   describe_endpoint:
     "Full details for one endpoint: params grouped by type, request body schema, " +
@@ -36,7 +37,7 @@ export const TOOL_DESCRIPTIONS = {
     "Query the zond database. Actions: list_collections (all APIs with run stats), " +
     "list_runs (recent test runs), get_run_results (full detail for a run), " +
     "diagnose_failure (only failed/errored steps for a run — each failure includes failure_type: api_error/assertion_failed/network_error, " +
-    "and summary includes api_errors/assertion_failures/network_errors counts), " +
+    "and summary includes api_errors/assertion_failures/network_errors counts; stack traces are truncated by default, use verbose: true for full traces), " +
     "compare_runs (regressions and fixes between two runs).",
 
   coverage_analysis:
@@ -46,7 +47,8 @@ export const TOOL_DESCRIPTIONS = {
     "Always includes static spec warnings (deprecated, missing response schemas, required params without examples).",
 
   send_request:
-    "Send an ad-hoc HTTP request. Supports variable interpolation from environments (e.g. {{base_url}}).",
+    "Send an ad-hoc HTTP request. Supports variable interpolation from environments (e.g. {{base_url}}). " +
+    "Use jsonPath to extract a subset of the response (e.g. '[0].code'), maxResponseChars to truncate large responses.",
 
   manage_server:
     "Start, stop, restart, or check status of the zond WebUI server. " +

package/src/mcp/tools/query-db.ts

@@ -6,6 +6,28 @@ import { join } from "node:path";
 import { TOOL_DESCRIPTIONS } from "../descriptions.js";
 import { statusHint, classifyFailure, envHint, envCategory, schemaHint } from "../../core/diagnostics/failure-hints.ts";
 
+function truncateErrorMessage(raw: string | null | undefined, verbose?: boolean): string | undefined {
+  if (!raw) return undefined;
+  if (verbose || raw.length < 500) return raw;
+  const lines = raw.split(/\r?\n/);
+  // First line is the error message itself
+  const msgLines = [lines[0]!];
+  // Grab up to 3 stack-trace lines (indented or starting with "at ")
+  let traceCount = 0;
+  for (let i = 1; i < lines.length && traceCount < 3; i++) {
+    const line = lines[i]!;
+    if (/^\s+/.test(line) || /^\s*at\s/.test(line)) {
+      msgLines.push(line);
+      traceCount++;
+    }
+  }
+  const remaining = lines.length - msgLines.length;
+  if (remaining > 0) {
+    msgLines.push(`...[truncated ${remaining} lines]`);
+  }
+  return msgLines.join("\n");
+}
+
 function parseBodySafe(raw: string | null | undefined): unknown {
   if (!raw) return undefined;
   const truncated = raw.length > 2000 ? raw.slice(0, 2000) + "…[truncated]" : raw;
@@ -49,8 +71,10 @@ export function registerQueryDbTool(server: McpServer, dbPath?: string) {
         .describe("Second run ID (required for compare_runs — this is the newer run)"),
       limit: z.optional(z.number().int().min(1).max(100))
         .describe("Max number of runs to return (default: 20, only for list_runs)"),
+      verbose: z.optional(z.boolean())
+        .describe("Show full error messages and stack traces (default: false, truncates long traces)"),
     },
-  }, async ({ action, runId, runIdB, limit }) => {
+  }, async ({ action, runId, runIdB, limit, verbose }) => {
     try {
       getDb(dbPath);
 
@@ -105,7 +129,7 @@ export function registerQueryDbTool(server: McpServer, dbPath?: string) {
               request_method: r.request_method,
               request_url: r.request_url,
               response_status: r.response_status,
-              error_message: r.error_message,
+              error_message: truncateErrorMessage(r.error_message, verbose),
               assertions: r.assertions,
             })),
           };
@@ -151,7 +175,7 @@ export function registerQueryDbTool(server: McpServer, dbPath?: string) {
                 test_name: r.test_name,
                 status: r.status,
                 failure_type,
-                error_message: r.error_message,
+                error_message: truncateErrorMessage(r.error_message, verbose),
                 request_method: r.request_method,
                 request_url: r.request_url,
                 response_status: r.response_status,

package/src/mcp/tools/send-request.ts

@@ -6,6 +6,24 @@ import { getDb } from "../../db/schema.ts";
 import { findCollectionByNameOrId } from "../../db/queries.ts";
 import { TOOL_DESCRIPTIONS } from "../descriptions.js";
 
+function extractByPath(obj: unknown, path: string): unknown {
+  const segments = path.replace(/\[(\d+)\]/g, '.$1').split('.').filter(Boolean);
+  let current: unknown = obj;
+  for (const seg of segments) {
+    if (current === null || current === undefined) return undefined;
+    if (Array.isArray(current)) {
+      const idx = parseInt(seg, 10);
+      if (isNaN(idx)) return undefined;
+      current = current[idx];
+    } else if (typeof current === 'object') {
+      current = (current as Record<string, unknown>)[seg];
+    } else {
+      return undefined;
+    }
+  }
+  return current;
+}
+
 export function registerSendRequestTool(server: McpServer, dbPath?: string) {
   server.registerTool("send_request", {
     description: TOOL_DESCRIPTIONS.send_request,
@@ -17,8 +35,10 @@ export function registerSendRequestTool(server: McpServer, dbPath?: string) {
       timeout: z.optional(z.number().int().positive()).describe("Request timeout in ms"),
       envName: z.optional(z.string()).describe("Environment name for variable interpolation"),
       collectionName: z.optional(z.string()).describe("Collection name to load env from its base_dir (e.g. 'petstore'). Required for {{variable}} interpolation."),
+      jsonPath: z.optional(z.string()).describe("Simple dot-notation path to extract from response body (e.g. '[0].code', 'data.items', 'id'). Supports array indices."),
+      maxResponseChars: z.optional(z.number().int().positive()).describe("Truncate response body to this many characters"),
     },
-  }, async ({ method, url, headers, body, timeout, envName, collectionName }) => {
+  }, async ({ method, url, headers, body, timeout, envName, collectionName, jsonPath, maxResponseChars }) => {
     try {
       let searchDir = process.cwd();
       if (collectionName) {
@@ -43,15 +63,29 @@ export function registerSendRequestTool(server: McpServer, dbPath?: string) {
         timeout ? { timeout } : undefined,
       );
 
+      let responseBody: unknown = response.body_parsed ?? response.body;
+
+      // Apply jsonPath filter
+      if (jsonPath && responseBody !== undefined) {
+        responseBody = extractByPath(responseBody, jsonPath);
+      }
+
       const result = {
         status: response.status,
         headers: response.headers,
-        body: response.body_parsed ?? response.body,
+        body: responseBody,
         duration_ms: response.duration_ms,
       };
 
+      let text = JSON.stringify(result, null, 2);
+
+      // Apply maxResponseChars truncation
+      if (maxResponseChars && text.length > maxResponseChars) {
+        text = text.slice(0, maxResponseChars) + '\n…[truncated]';
+      }
+
       return {
-        content: [{ type: "text" as const, text: JSON.stringify(result, null, 2) }],
+        content: [{ type: "text" as const, text }],
       };
     } catch (err) {
       return {

package/src/mcp/tools/setup-api.ts

@@ -27,8 +27,9 @@ export function registerSetupApiTool(server: McpServer, dbPath?: string) {
       dir: z.optional(z.string()).describe("Base directory (default: ./apis/<name>/)"),
       envVars: z.optional(z.string()).describe("Environment variables as JSON string (e.g. '{\"base_url\": \"...\", \"token\": \"...\"}')"),
       force: z.optional(z.boolean()).describe("If true, delete existing API with same name and recreate from scratch"),
+      insecure: z.optional(z.boolean()).describe("Skip TLS certificate verification when fetching spec over HTTPS (for self-signed certs)"),
     },
-  }, async ({ name, specPath, dir, envVars, force }) => {
+  }, async ({ name, specPath, dir, envVars, force, insecure }) => {
     try {
       let parsedEnvVars: Record<string, string> | undefined;
       if (envVars) {
@@ -59,12 +60,15 @@ export function registerSetupApiTool(server: McpServer, dbPath?: string) {
         envVars: parsedEnvVars,
         dbPath,
         force,
+        insecure,
       });
 
       const envFilePath = join(result.baseDir, ".env.yaml");
+      const warningSteps = result.warnings?.map(w => `WARNING: ${w}`) ?? [];
       const response = {
         ...result,
         nextSteps: [
+          ...warningSteps,
           `Edit ${envFilePath} to add credentials (auth_token, api_key, base_url, etc.)`,
           `File is already git-ignored via .gitignore`,
           `Then run: run_tests(testPath: "${result.testPath}")`,