@kirrosh/zond 0.16.0 → 0.17.0

package/src/core/generator/data-factory.ts

@@ -33,6 +33,9 @@ export function generateFromSchema(
     return schema.enum[0];
   }
 
+  // uuid format overrides type (e.g. integer fields with format: uuid)
+  if (schema.format === "uuid") return "{{$uuid}}";
+
   switch (schema.type) {
     case "string":
       return guessStringPlaceholder(schema, propertyName);
@@ -81,11 +84,36 @@ export function generateFromSchema(
   }
 }
 
+/**
+ * Generate a multipart body object from an OpenAPI multipart/form-data schema.
+ * Binary fields (format: binary/byte) become file upload objects; all others become strings.
+ */
+export function generateMultipartFromSchema(
+  schema: OpenAPIV3.SchemaObject,
+): Record<string, unknown> {
+  const result: Record<string, unknown> = {};
+
+  if (!schema.properties) return result;
+
+  for (const [key, propSchema] of Object.entries(schema.properties)) {
+    const s = propSchema as OpenAPIV3.SchemaObject;
+    if (s.format === "binary" || s.format === "byte") {
+      result[key] = { file: `./fixtures/${key}.bin`, content_type: "application/octet-stream" };
+    } else {
+      const val = generateFromSchema(s, key);
+      result[key] = val;
+    }
+  }
+
+  return result;
+}
+
 function guessStringPlaceholder(schema: OpenAPIV3.SchemaObject, name?: string): string {
   // Format-based
   if (schema.format === "email") return "{{$randomEmail}}";
   if (schema.format === "uuid") return "{{$uuid}}";
-  if (schema.format === "date-time" || schema.format === "date") return "2025-01-01T00:00:00Z";
+  if (schema.format === "date-time") return "2025-01-01T00:00:00Z";
+  if (schema.format === "date") return "2025-01-01";
   if (schema.format === "uri" || schema.format === "url") return "https://example.com/test";
   if (schema.format === "hostname") return "example.com";
   if (schema.format === "ipv4") return "192.168.1.1";
@@ -119,8 +147,15 @@ function guessStringPlaceholder(schema: OpenAPIV3.SchemaObject, name?: string):
 }
 
 function guessIntPlaceholder(name?: string, schema?: OpenAPIV3.SchemaObject): number | string {
-  if (schema?.minimum !== undefined && schema.minimum > 0) {
-    return schema.minimum;
+  const min = schema?.minimum;
+  const max = schema?.maximum;
+  if (max !== undefined) {
+    // Use a safe concrete value within the declared range
+    const lo = min !== undefined && min > 0 ? min : 1;
+    return Math.min(lo, max);
+  }
+  if (min !== undefined && min > 0) {
+    return min;
   }
   return "{{$randomInt}}";
 }

package/src/core/generator/index.ts

@@ -9,4 +9,4 @@ export { compressEndpointsWithSchemas, buildGenerationGuide } from "./guide-buil
 export type { GuideOptions } from "./guide-builder.ts";
 export type { EndpointWarning, WarningCode } from "./endpoint-warnings.ts";
 export type { EndpointInfo, ResponseInfo, GenerateOptions, SecuritySchemeInfo, CrudGroup } from "./types.ts";
-export { generateSuites, generateStep, detectCrudGroups, generateCrudSuite, findUnresolvedVars } from "./suite-generator.ts";
+export { generateSuites, generateStep, detectCrudGroups, generateCrudSuite, generateSanitySuite, findUnresolvedVars } from "./suite-generator.ts";

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

@@ -124,6 +124,11 @@ export function extractEndpoints(doc: OpenAPIV3.Document): EndpointInfo[] {
       const securityReqs = operation.security ?? doc.security ?? [];
       const security = securityReqs.flatMap((req) => Object.keys(req));
 
+      // ETag optimistic locking: detect if endpoint requires If-Match header
+      const requiresEtag =
+        responses.some(r => r.statusCode === 412) ||
+        parameters.some(p => p.name.toLowerCase() === "if-match" && p.in === "header");
+
       endpoints.push({
         path,
         method: method.toUpperCase(),
@@ -137,6 +142,7 @@ export function extractEndpoints(doc: OpenAPIV3.Document): EndpointInfo[] {
         responses,
         security,
         deprecated: operation.deprecated ?? false,
+        requiresEtag,
       });
     }
   }

package/src/core/generator/serializer.ts

@@ -29,11 +29,13 @@ export interface RawStep {
   expect: {
     status?: number;
     body?: Record<string, Record<string, string>>;
+    headers?: Record<string, unknown>;
   };
 }
 
 export interface RawSuite {
   name: string;
+  setup?: boolean;
   tags?: string[];
   folder?: string;
   fileStem?: string;
@@ -49,6 +51,9 @@ export interface RawSuite {
 export function serializeSuite(suite: RawSuite): string {
   const lines: string[] = [];
   lines.push(`name: ${yamlScalar(suite.name)}`);
+  if (suite.setup) {
+    lines.push("setup: true");
+  }
   if (suite.tags && suite.tags.length > 0) {
     lines.push(`tags: [${suite.tags.join(", ")}]`);
   }
@@ -167,10 +172,20 @@ function serializeValue(value: unknown, indent: number, lines: string[]): void {
         const entries = Object.entries(item as Record<string, unknown>);
         if (entries.length > 0) {
           const [firstKey, firstVal] = entries[0]!;
-          lines.push(`${prefix}- ${firstKey}: ${formatInlineValue(firstVal)}`);
+          if (typeof firstVal === "object" && firstVal !== null) {
+            lines.push(`${prefix}- ${firstKey}:`);
+            serializeValue(firstVal, indent + 1, lines);
+          } else {
+            lines.push(`${prefix}- ${firstKey}: ${formatInlineValue(firstVal)}`);
+          }
           for (let i = 1; i < entries.length; i++) {
             const [k, v] = entries[i]!;
-            lines.push(`${prefix}  ${k}: ${formatInlineValue(v)}`);
+            if (typeof v === "object" && v !== null) {
+              lines.push(`${prefix}  ${k}:`);
+              serializeValue(v, indent + 1, lines);
+            } else {
+              lines.push(`${prefix}  ${k}: ${formatInlineValue(v)}`);
+            }
           }
         } else {
           lines.push(`${prefix}- {}`);

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

@@ -1,7 +1,7 @@
 import type { OpenAPIV3 } from "openapi-types";
 import type { EndpointInfo, SecuritySchemeInfo, CrudGroup } from "./types.ts";
 import type { RawSuite, RawStep } from "./serializer.ts";
-import { generateFromSchema } from "./data-factory.ts";
+import { generateFromSchema, generateMultipartFromSchema } from "./data-factory.ts";
 import { groupEndpointsByTag } from "./chunker.ts";
 
 // ──────────────────────────────────────────────
@@ -13,6 +13,22 @@ function convertPath(path: string): string {
   return path.replace(/\{([^}]+)\}/g, "{{$1}}");
 }
 
+/**
+ * Convert path params to seed values for smoke suites (no capture context).
+ * Uses the parameter's example/default from the spec, or falls back to "1" for
+ * id-like params. Non-id string params keep the {{placeholder}} form.
+ */
+function convertPathWithSeeds(path: string, ep: EndpointInfo): string {
+  return path.replace(/\{([^}]+)\}/g, (_, name: string) => {
+    const param = ep.parameters.find(p => p.name === name && p.in === "path");
+    const schema = param?.schema as OpenAPIV3.SchemaObject | undefined;
+    const example = (param as any)?.example ?? schema?.example ?? schema?.default;
+    if (example !== undefined) return String(example);
+    if (schema?.type === "integer" || /^id$|_id$|Id$/i.test(name)) return "1";
+    return `{{${name}}}`;
+  });
+}
+
 function slugify(s: string): string {
   return s.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-|-$/g, "");
 }
@@ -21,6 +37,19 @@ function escapeRegex(s: string): string {
   return s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
 }
 
+const HEALTHCHECK_PATH_RE = /\/(health|healthz|ping|status|ready|readiness|liveness|alive)\b/i;
+const RESET_PATH_RE = /\/(reset|flush|purge|truncate|wipe|clear-data|factory-reset)\b/i;
+const LOGOUT_PATH_RE = /\/(logout|signout|invalidate|revoke)\b/i;
+const SHORT_PATH_RE = /^\/[a-z0-9-]*$/i; // matches /, /api, /v1, etc.
+
+function selectHealthcheckEndpoint(gets: EndpointInfo[]): EndpointInfo | undefined {
+  return (
+    gets.find(ep => HEALTHCHECK_PATH_RE.test(ep.path) && !ep.parameters.some(p => p.in === "path")) ??
+    gets.find(ep => SHORT_PATH_RE.test(ep.path) && !ep.parameters.some(p => p.in === "path") && ep.security.length === 0) ??
+    gets.find(ep => !ep.parameters.some(p => p.in === "path") && ep.security.length === 0)
+  );
+}
+
 function getExpectedStatus(ep: EndpointInfo): number {
   const success = ep.responses.find(r => r.statusCode >= 200 && r.statusCode < 300);
   if (success) return success.statusCode;
@@ -161,7 +190,11 @@ export function generateStep(
   }
 
   if (["POST", "PUT", "PATCH"].includes(method) && ep.requestBodySchema) {
-    step.json = generateFromSchema(ep.requestBodySchema);
+    if (ep.requestBodyContentType === "multipart/form-data") {
+      step.multipart = generateMultipartFromSchema(ep.requestBodySchema);
+    } else {
+      step.json = generateFromSchema(ep.requestBodySchema);
+    }
   }
 
   const query = getRequiredQueryParams(ep);
@@ -265,13 +298,31 @@ export function generateCrudSuite(
   // 3. Update
   if (group.update) {
     const method = group.update.method.toUpperCase();
+    const itemPath = convertPath(group.itemPath).replace(`{{${group.idParam}}}`, `{{${captureVar}}}`);
+    const etagVar = `${group.resource.replace(/s$/, "")}_etag`;
+
+    // If endpoint requires ETag (optimistic locking), capture it from a GET step first
+    if (group.update.requiresEtag && group.read) {
+      tests.push({
+        name: `Get ETag before update ${group.resource.replace(/s$/, "")}`,
+        GET: itemPath,
+        expect: {
+          status: getExpectedStatus(group.read),
+          headers: { ETag: { capture: etagVar } },
+        },
+      });
+    }
+
     const step: RawStep = {
       name: group.update.operationId ?? `Update ${group.resource.replace(/s$/, "")}`,
-      [method]: convertPath(group.itemPath).replace(`{{${group.idParam}}}`, `{{${captureVar}}}`),
+      [method]: itemPath,
       expect: {
         status: getExpectedStatus(group.update),
       },
     };
+    if (group.update.requiresEtag) {
+      step.headers = { "If-Match": `"{{${etagVar}}}"` };
+    }
     if (group.update.requestBodySchema) {
       step.json = generateFromSchema(group.update.requestBodySchema);
     }
@@ -280,13 +331,32 @@ export function generateCrudSuite(
 
   // 4. Delete
   if (group.delete) {
+    const itemPath = convertPath(group.itemPath).replace(`{{${group.idParam}}}`, `{{${captureVar}}}`);
+    const etagVar = `${group.resource.replace(/s$/, "")}_etag`;
+
+    // If delete requires ETag and update didn't already capture it, add a GET step
+    const updateAlreadyCapturedEtag = group.update?.requiresEtag;
+    if (group.delete.requiresEtag && group.read && !updateAlreadyCapturedEtag) {
+      tests.push({
+        name: `Get ETag before delete ${group.resource.replace(/s$/, "")}`,
+        GET: itemPath,
+        expect: {
+          status: getExpectedStatus(group.read),
+          headers: { ETag: { capture: etagVar } },
+        },
+      });
+    }
+
     const step: RawStep = {
       name: group.delete.operationId ?? `Delete ${group.resource.replace(/s$/, "")}`,
-      DELETE: convertPath(group.itemPath).replace(`{{${group.idParam}}}`, `{{${captureVar}}}`),
+      DELETE: itemPath,
       expect: {
         status: getExpectedStatus(group.delete),
       },
     };
+    if (group.delete.requiresEtag) {
+      step.headers = { "If-Match": `"{{${etagVar}}}"` };
+    }
     tests.push(step);
 
     // 5. Verify deleted
@@ -374,12 +444,14 @@ export function generateAuthSuite(
     return generateConsistentAuthSuite(registerEp, loginEp, authEndpoints, securitySchemes);
   }
 
-  // Fallback: plain auth suite
-  const tests = authEndpoints.map(ep => generateStep(ep, securitySchemes));
-  const headers = getSuiteHeaders(authEndpoints, securitySchemes);
+  // Fallback: plain auth suite — exclude logout/revoke endpoints from setup suite
+  const nonLogoutEndpoints = authEndpoints.filter(ep => !LOGOUT_PATH_RE.test(ep.path));
+  const tests = nonLogoutEndpoints.map(ep => generateStep(ep, securitySchemes));
+  const headers = getSuiteHeaders(nonLogoutEndpoints, securitySchemes);
 
   const suite: RawSuite = {
     name: "auth",
+    setup: true,
     tags: ["auth"],
     fileStem: "auth",
     base_url: "{{base_url}}",
@@ -452,14 +524,18 @@ function generateConsistentAuthSuite(
   }
   tests.push(loginStep);
 
-  // 3. Any remaining auth endpoints (not register/login)
-  const others = allAuthEndpoints.filter(ep => ep !== registerEp && ep !== loginEp);
+  // 3. Any remaining auth endpoints (not register/login, not logout)
+  // Logout/revoke endpoints must NOT be in a setup suite — they invalidate the token
+  const others = allAuthEndpoints.filter(ep =>
+    ep !== registerEp && ep !== loginEp && !LOGOUT_PATH_RE.test(ep.path)
+  );
   for (const ep of others) {
     tests.push(generateStep(ep, securitySchemes));
   }
 
   return {
     name: "auth",
+    setup: true,
     tags: ["auth"],
     fileStem: "auth",
     base_url: "{{base_url}}",
@@ -467,6 +543,40 @@ function generateConsistentAuthSuite(
   };
 }
 
+/** Generate 1-2 minimal tests for quick connectivity and auth validation */
+export function generateSanitySuite(opts: {
+  authEndpoints: EndpointInfo[];
+  nonAuthGetEndpoints: EndpointInfo[];
+  securitySchemes: SecuritySchemeInfo[];
+}): RawSuite | null {
+  const { authEndpoints, nonAuthGetEndpoints, securitySchemes } = opts;
+  const tests: RawStep[] = [];
+
+  // Priority 1: auth login/token endpoint
+  if (authEndpoints.length > 0) {
+    const loginEp =
+      authEndpoints.find(ep => /\/(login|signin|token)\b/i.test(ep.path) && ep.method.toUpperCase() === "POST") ??
+      authEndpoints[0]!;
+    tests.push(generateStep(loginEp, securitySchemes));
+  }
+
+  // Priority 2: healthcheck or first simple GET with no path params
+  const healthEp = selectHealthcheckEndpoint(nonAuthGetEndpoints);
+  if (healthEp) {
+    tests.push(generateStep(healthEp, securitySchemes));
+  }
+
+  if (tests.length === 0) return null;
+
+  return {
+    name: "sanity",
+    tags: ["sanity"],
+    fileStem: "sanity",
+    base_url: "{{base_url}}",
+    tests: tests.slice(0, 2),
+  };
+}
+
 /** Main entry point: generate all suites from endpoints */
 export function generateSuites(opts: {
   endpoints: EndpointInfo[];
@@ -505,10 +615,16 @@ export function generateSuites(opts: {
   for (const [tag, tagEndpoints] of byTag) {
     const tagSlug = slugify(tag) || "api";
 
-    // GET endpoints → smoke suite
+    // GET endpoints → smoke suite (use seed values for path params — no capture context)
     const getEndpoints = tagEndpoints.filter(ep => ep.method.toUpperCase() === "GET");
     if (getEndpoints.length > 0) {
-      const tests = getEndpoints.map(ep => generateStep(ep, securitySchemes));
+      const tests = getEndpoints.map(ep => {
+        const step = generateStep(ep, securitySchemes);
+        // Replace path param placeholders with seed values so the suite runs out of the box
+        const seededPath = convertPathWithSeeds(ep.path, ep);
+        (step as any)[ep.method.toUpperCase()] = seededPath;
+        return step;
+      });
       const headers = getSuiteHeaders(getEndpoints, securitySchemes);
 
       const suite: RawSuite = {
@@ -531,8 +647,37 @@ export function generateSuites(opts: {
       suites.push(suite);
     }
 
-    // Non-GET endpoints → smoke-unsafe suite
-    const unsafeEndpoints = tagEndpoints.filter(ep => ep.method.toUpperCase() !== "GET");
+    // Non-GET endpoints: split reset/system endpoints out of smoke-unsafe
+    const nonGetEndpoints = tagEndpoints.filter(ep => ep.method.toUpperCase() !== "GET");
+    const resetEndpoints = nonGetEndpoints.filter(ep => RESET_PATH_RE.test(ep.path));
+    const unsafeEndpoints = nonGetEndpoints.filter(ep => !RESET_PATH_RE.test(ep.path));
+
+    // Reset/system endpoints → [system, reset] suite (never run as part of smoke)
+    if (resetEndpoints.length > 0) {
+      const tests = resetEndpoints.map(ep => generateStep(ep, securitySchemes));
+      const headers = getSuiteHeaders(resetEndpoints, securitySchemes);
+
+      const suite: RawSuite = {
+        name: `${tagSlug}-system`,
+        tags: ["system", "reset"],
+        fileStem: `system-${tagSlug}`,
+        base_url: "{{base_url}}",
+        tests,
+      };
+
+      if (headers) {
+        suite.headers = headers;
+        for (const t of tests) {
+          if (t.headers && JSON.stringify(t.headers) === JSON.stringify(headers)) {
+            delete (t as any).headers;
+          }
+        }
+      }
+
+      suites.push(suite);
+    }
+
+    // Remaining non-GET endpoints → smoke-unsafe suite
     if (unsafeEndpoints.length > 0) {
       const tests = unsafeEndpoints.map(ep => generateStep(ep, securitySchemes));
       const headers = getSuiteHeaders(unsafeEndpoints, securitySchemes);
@@ -569,5 +714,9 @@ export function generateSuites(opts: {
     suites.push(suite);
   }
 
-  return suites;
+  // 5. Sanity suite (prepend — 1-2 tests for quick connectivity/auth check)
+  const nonAuthGetEndpoints = nonAuth.filter(ep => ep.method.toUpperCase() === "GET");
+  const sanitySuite = generateSanitySuite({ authEndpoints, nonAuthGetEndpoints, securitySchemes });
+
+  return sanitySuite ? [sanitySuite, ...suites] : suites;
 }

package/src/core/generator/types.ts

@@ -19,6 +19,7 @@ export interface EndpointInfo {
   responses: ResponseInfo[];
   security: string[];
   deprecated?: boolean;
+  requiresEtag?: boolean;
 }
 
 export interface SecuritySchemeInfo {

package/src/core/meta/meta-store.ts

@@ -0,0 +1,78 @@
+import { join } from "path";
+import { createHash } from "crypto";
+import type { ZondMeta, FileMeta } from "./types.ts";
+import type { RawSuite } from "../generator/serializer.ts";
+import { normalizePath } from "../generator/coverage-scanner.ts";
+
+const META_FILENAME = ".zond-meta.json";
+
+export async function readMeta(testsDir: string): Promise<ZondMeta | null> {
+  const metaPath = join(testsDir, META_FILENAME);
+  const file = Bun.file(metaPath);
+  if (!(await file.exists())) return null;
+  try {
+    return JSON.parse(await file.text()) as ZondMeta;
+  } catch {
+    return null;
+  }
+}
+
+export async function writeMeta(testsDir: string, meta: ZondMeta): Promise<void> {
+  const metaPath = join(testsDir, META_FILENAME);
+  await Bun.write(metaPath, JSON.stringify(meta, null, 2) + "\n");
+}
+
+export function hashSpec(specContent: string): string {
+  return createHash("sha256").update(specContent).digest("hex");
+}
+
+/**
+ * Derive suite type from tags array or filename.
+ */
+function detectSuiteType(suite: RawSuite): FileMeta["suiteType"] {
+  const tags = suite.tags ?? [];
+  if (tags.includes("auth")) return "auth";
+  if (tags.includes("sanity")) return "sanity";
+  if (tags.includes("crud")) return "crud";
+  if (tags.includes("unsafe")) return "unsafe";
+  return "smoke";
+}
+
+/**
+ * Extract first tag from fileStem or suite folder for grouping.
+ * e.g. fileStem "smoke-users" → tag "users"
+ */
+function detectTag(suite: RawSuite): string | undefined {
+  const stem = suite.fileStem ?? suite.name;
+  const match = stem.match(/^(?:smoke|crud|auth|sanity|unsafe)-(.+?)(?:-unsafe)?$/);
+  return match?.[1];
+}
+
+/**
+ * Build normalized endpoint keys from a raw suite's test steps.
+ * e.g. "GET /users/{*}", "POST /users"
+ */
+function extractEndpointKeys(suite: RawSuite): string[] {
+  const HTTP_METHODS = ["GET", "POST", "PUT", "PATCH", "DELETE"];
+  const keys: string[] = [];
+  for (const step of suite.tests) {
+    for (const method of HTTP_METHODS) {
+      const path = step[method] as string | undefined;
+      if (path) {
+        keys.push(`${method} ${normalizePath(path)}`);
+        break;
+      }
+    }
+  }
+  return [...new Set(keys)];
+}
+
+export function buildFileMeta(suite: RawSuite, zondVersion: string): FileMeta {
+  return {
+    generatedAt: new Date().toISOString(),
+    zondVersion,
+    suiteType: detectSuiteType(suite),
+    tag: detectTag(suite),
+    endpoints: extractEndpointKeys(suite),
+  };
+}

package/src/core/meta/types.ts

@@ -0,0 +1,21 @@
+export interface FileMeta {
+  generatedAt: string;
+  zondVersion: string;
+  suiteType: "smoke" | "crud" | "auth" | "sanity" | "unsafe";
+  tag?: string;
+  /** Normalized endpoint keys, e.g. ["GET /users", "POST /users/{*}"] */
+  endpoints: string[];
+}
+
+export interface ZondMeta {
+  /** Version of zond that last wrote this metadata */
+  zondVersion: string;
+  /** ISO timestamp of last sync/generate */
+  lastSyncedAt: string;
+  /** Spec URL or file path used for last generation */
+  specUrl: string;
+  /** SHA-256 hex of spec content at time of last generation */
+  specHash: string;
+  /** Per-file metadata, keyed by filename (e.g. "smoke-users.yaml") */
+  files: Record<string, FileMeta>;
+}

package/src/core/parser/schema.ts

@@ -1,5 +1,5 @@
 import { z } from "zod";
-import type { TestSuite, TestStep, AssertionRule, TestStepExpect, SuiteConfig, RetryUntil, ForEach } from "./types.ts";
+import type { TestSuite, TestStep, AssertionRule, TestStepExpect, SuiteConfig, RetryUntil, ForEach, MultipartField } from "./types.ts";
 
 const HTTP_METHODS = ["GET", "POST", "PUT", "PATCH", "DELETE"] as const;
 
@@ -134,7 +134,7 @@ const TestStepExpectSchema: z.ZodType<TestStepExpect> = z.preprocess(
   z.object({
     status: z.union([z.number().int(), z.array(z.number().int())]).optional(),
     body: z.record(z.string(), AssertionRuleSchema).optional(),
-    headers: z.record(z.string(), z.string()).optional(),
+    headers: z.record(z.string(), z.union([z.string(), AssertionRuleSchema])).optional(),
     duration: z.number().optional(),
   }),
 ) as z.ZodType<TestStepExpect>;
@@ -150,6 +150,14 @@ const ForEachSchema: z.ZodType<ForEach> = z.object({
   in: z.unknown(),
 });
 
+const MultipartFileFieldSchema = z.object({
+  file: z.string(),
+  filename: z.string().optional(),
+  content_type: z.string().optional(),
+});
+
+const MultipartFieldSchema: z.ZodType<MultipartField> = z.union([z.string(), MultipartFileFieldSchema]);
+
 const TestStepSchema: z.ZodType<TestStep> = z.preprocess(
   (raw) => {
     const obj = extractMethodAndPath(raw);
@@ -169,6 +177,7 @@ const TestStepSchema: z.ZodType<TestStep> = z.preprocess(
     headers: z.record(z.string(), z.string()).optional(),
     json: z.unknown().optional(),
     form: z.record(z.string(), z.string()).optional(),
+    multipart: z.record(z.string(), MultipartFieldSchema).optional(),
     query: z.record(z.string(), z.string()).optional(),
     expect: TestStepExpectSchema,
     skip_if: z.string().optional(),
@@ -207,6 +216,7 @@ const TestSuiteSchema = z.preprocess(
   z.object({
     name: z.string(),
     description: z.string().optional(),
+    setup: z.boolean().optional(),
     tags: z.array(z.string()).optional(),
     base_url: z.string().optional(),
     headers: z.record(z.string(), z.string()).optional(),

package/src/core/parser/types.ts

@@ -26,7 +26,7 @@ export interface AssertionRule {
 export interface TestStepExpect {
   status?: number | number[];
   body?: Record<string, AssertionRule>;
-  headers?: Record<string, string>;
+  headers?: Record<string, string | AssertionRule>;
   duration?: number;
 }
 
@@ -41,6 +41,14 @@ export interface ForEach {
   in: unknown;
 }
 
+export interface MultipartFileField {
+  file: string;
+  filename?: string;
+  content_type?: string;
+}
+
+export type MultipartField = string | MultipartFileField;
+
 export interface TestStep {
   name: string;
   method: HttpMethod;
@@ -48,6 +56,7 @@ export interface TestStep {
   headers?: Record<string, string>;
   json?: unknown;
   form?: Record<string, string>;
+  multipart?: Record<string, MultipartField>;
   query?: Record<string, string>;
   expect: TestStepExpect;
   skip_if?: string;
@@ -67,6 +76,8 @@ export interface SuiteConfig {
 export interface TestSuite {
   name: string;
   description?: string;
+  /** If true, this suite runs before all regular suites and its captures are shared into their env */
+  setup?: boolean;
   tags?: string[];
   base_url?: string;
   headers?: Record<string, string>;

package/src/core/parser/variables.ts

@@ -79,6 +79,9 @@ export function substituteStep(step: TestStep, vars: Record<string, unknown>): T
   if (step.form) {
     result.form = substituteDeep(step.form, vars);
   }
+  if (step.multipart) {
+    result.multipart = substituteDeep(step.multipart, vars);
+  }
   if (step.query) {
     result.query = substituteDeep(step.query, vars);
   }

package/src/core/parser/yaml-parser.ts

@@ -1,4 +1,5 @@
 import { Glob } from "bun";
+import { resolve } from "node:path";
 import { validateSuite } from "./schema.ts";
 import type { TestSuite } from "./types.ts";
 
@@ -19,7 +20,7 @@ export async function parseFile(filePath: string): Promise<TestSuite> {
 
   try {
     const suite = validateSuite(raw);
-    suite.filePath = filePath;
+    suite.filePath = resolve(filePath);
     return suite;
   } catch (err) {
     throw new Error(`Validation error in ${filePath}: ${(err as Error).message}`);