@kirrosh/zond 0.14.0 → 0.17.0

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

@@ -33,15 +33,18 @@ 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);
 
     case "integer":
-      return guessIntPlaceholder(propertyName);
+      return guessIntPlaceholder(propertyName, schema);
 
     case "number":
-      return "{{$randomInt}}";
+      return 29.99;
 
     case "boolean":
       return true;
@@ -81,11 +84,41 @@ 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";
+  if (schema.format === "ipv6") return "::1";
+  if (schema.format === "password") return "TestPass123!";
 
   // Name-based heuristics
   if (name) {
@@ -99,17 +132,30 @@ function guessStringPlaceholder(schema: OpenAPIV3.SchemaObject, name?: string):
     if (lower === "name" || lower.endsWith("_name") || lower.endsWith("Name")) {
       return "{{$randomName}}";
     }
+    if (lower === "url" || lower.endsWith("_url") || lower === "uri" || lower === "href" || lower === "website") {
+      return "https://example.com/test";
+    }
+    if (lower === "password" || lower.endsWith("_password")) {
+      return "TestPass123!";
+    }
+    if (lower === "phone" || lower === "telephone" || lower.endsWith("_phone")) {
+      return "+1234567890";
+    }
   }
 
   return "{{$randomString}}";
 }
 
-function guessIntPlaceholder(name?: string): string {
-  if (name) {
-    const lower = name.toLowerCase();
-    if (lower === "id" || lower.endsWith("_id") || lower.endsWith("Id")) {
-      return "{{$randomInt}}";
-    }
+function guessIntPlaceholder(name?: string, schema?: OpenAPIV3.SchemaObject): number | string {
+  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/describe.ts

@@ -0,0 +1,250 @@
+import type { OpenAPIV3 } from "openapi-types";
+import { readOpenApiSpec } from "./openapi-reader.ts";
+import { decycleSchema } from "./schema-utils.ts";
+
+export interface DescribeEndpointResult {
+  method: string;
+  path: string;
+  operationId?: string;
+  summary?: string;
+  description?: string;
+  tags?: string[];
+  deprecated: boolean;
+  security: string[];
+  parameters: Record<string, object[]>;
+  requestBody?: object;
+  responses: Record<string, object>;
+  testSnippet: string;
+}
+
+export interface CompactEndpoint {
+  method: string;
+  path: string;
+  operationId?: string;
+  summary?: string;
+  deprecated: boolean;
+}
+
+export function generateTestSnippet(params: {
+  method: string;
+  path: string;
+  operationId?: string;
+  pathParams: string[];
+  queryParams: Array<{ name: string; required?: boolean }>;
+  requestBody?: { required?: boolean; schema?: OpenAPIV3.SchemaObject };
+  hasSecurity: boolean;
+  successStatus: string;
+}): string {
+  const { method, path, operationId, queryParams, requestBody, hasSecurity, successStatus } = params;
+
+  const urlPath = path.replace(/\{([^}]+)\}/g, (_, name) => `{{${name}}}`);
+  const url = `{{base_url}}${urlPath}`;
+
+  const lines: string[] = [];
+  const testName = operationId ?? `${method} ${path}`;
+  lines.push(`- name: "${testName}"`);
+  lines.push(`  ${method}: "${url}"`);
+
+  if (hasSecurity) {
+    lines.push(`  headers:`);
+    lines.push(`    Authorization: "Bearer {{auth_token}}"`);
+  }
+
+  const requiredQuery = queryParams.filter(p => p.required);
+  if (requiredQuery.length > 0) {
+    lines.push(`  query:`);
+    for (const p of requiredQuery) {
+      lines.push(`    ${p.name}: "{{${p.name}}}"`);
+    }
+  }
+
+  if (requestBody && ["POST", "PUT", "PATCH"].includes(method)) {
+    const schema = requestBody.schema as OpenAPIV3.SchemaObject | undefined;
+    const required = Array.isArray(schema?.required) ? schema.required : [];
+    const properties = schema?.properties as Record<string, OpenAPIV3.SchemaObject> | undefined;
+    if (properties && Object.keys(properties).length > 0) {
+      lines.push(`  json:`);
+      for (const [propName, propSchema] of Object.entries(properties)) {
+        if (!required.includes(propName)) continue;
+        const type = (propSchema as OpenAPIV3.SchemaObject).type ?? "string";
+        const placeholder = type === "integer" || type === "number" ? 0 : type === "boolean" ? false : `"{{${propName}}}"`;
+        lines.push(`    ${propName}: ${placeholder}`);
+      }
+    }
+  }
+
+  lines.push(`  expect:`);
+  lines.push(`    status: ${successStatus}`);
+
+  return lines.join("\n");
+}
+
+export async function describeEndpoint(
+  specPath: string,
+  method: string,
+  endpointPath: string,
+  options?: { insecure?: boolean },
+): Promise<DescribeEndpointResult> {
+  const doc = await readOpenApiSpec(specPath, options) as OpenAPIV3.Document;
+
+  const methodLower = method.toLowerCase() as OpenAPIV3.HttpMethods;
+  const normalizedPath = endpointPath.replace(/\/+$/, "") || "/";
+
+  let operation: OpenAPIV3.OperationObject | undefined;
+  let resolvedPath = normalizedPath;
+  const paths = doc.paths ?? {};
+
+  if (paths[normalizedPath]?.[methodLower]) {
+    operation = paths[normalizedPath][methodLower] as OpenAPIV3.OperationObject;
+  } else {
+    const lowerTarget = normalizedPath.toLowerCase();
+    for (const [p, pathItem] of Object.entries(paths)) {
+      if (p.toLowerCase() === lowerTarget && pathItem?.[methodLower]) {
+        operation = pathItem[methodLower] as OpenAPIV3.OperationObject;
+        resolvedPath = p;
+        break;
+      }
+    }
+  }
+
+  if (!operation) {
+    const available = Object.entries(paths).flatMap(([p, pathItem]) =>
+      Object.keys(pathItem ?? {})
+        .filter(k => ["get","post","put","patch","delete","head","options","trace"].includes(k))
+        .map(k => `${k.toUpperCase()} ${p}`)
+    ).sort();
+    throw new Error(`Endpoint ${method.toUpperCase()} ${endpointPath} not found in spec. Available: ${available.join(", ")}`);
+  }
+
+  const pathItem = paths[resolvedPath] ?? {};
+
+  const pathLevelParams = (pathItem.parameters ?? []) as OpenAPIV3.ParameterObject[];
+  const opLevelParams = (operation.parameters ?? []) as OpenAPIV3.ParameterObject[];
+
+  const paramMap = new Map<string, OpenAPIV3.ParameterObject>();
+  for (const p of pathLevelParams) paramMap.set(`${p.in}:${p.name}`, p);
+  for (const p of opLevelParams) paramMap.set(`${p.in}:${p.name}`, p);
+
+  const grouped: Record<string, object[]> = { path: [], query: [], header: [], cookie: [] };
+  for (const p of paramMap.values()) {
+    const loc = p.in in grouped ? p.in : "query";
+    const schema = p.schema as OpenAPIV3.SchemaObject | undefined;
+    grouped[loc]!.push({
+      name: p.name,
+      required: p.required ?? false,
+      ...(schema?.type ? { type: schema.type } : {}),
+      ...(schema?.format ? { format: schema.format } : {}),
+      ...(schema?.enum ? { enum: schema.enum } : {}),
+      ...(schema?.default !== undefined ? { default: schema.default } : {}),
+      ...(p.description ? { description: p.description } : {}),
+    });
+  }
+
+  let requestBody: object | undefined;
+  if (operation.requestBody) {
+    const rb = operation.requestBody as OpenAPIV3.RequestBodyObject;
+    const contentTypes = Object.keys(rb.content ?? {});
+    const preferredCt = contentTypes.find(ct => ct.includes("application/json")) ?? contentTypes[0];
+    const mediaObj = preferredCt ? rb.content[preferredCt] : undefined;
+    requestBody = {
+      required: rb.required ?? false,
+      ...(preferredCt ? { contentType: preferredCt } : {}),
+      ...(mediaObj?.schema ? { schema: mediaObj.schema } : {}),
+      ...(rb.description ? { description: rb.description } : {}),
+    };
+  }
+
+  const responses: Record<string, object> = {};
+  for (const [statusCode, respObj] of Object.entries(operation.responses ?? {})) {
+    const resp = respObj as OpenAPIV3.ResponseObject;
+    const contentTypes = Object.keys(resp.content ?? {});
+    const preferredCt = contentTypes.find(ct => ct.includes("application/json")) ?? contentTypes[0];
+    const mediaObj = preferredCt ? resp.content?.[preferredCt] : undefined;
+
+    const headers: Record<string, object> = {};
+    for (const [hName, hObj] of Object.entries(resp.headers ?? {})) {
+      const h = hObj as OpenAPIV3.HeaderObject;
+      headers[hName] = {
+        ...(h.description ? { description: h.description } : {}),
+        ...(h.schema ? { schema: h.schema } : {}),
+      };
+    }
+
+    responses[statusCode] = {
+      description: resp.description,
+      headers,
+      ...(preferredCt ? { contentType: preferredCt } : {}),
+      ...(mediaObj?.schema ? { schema: mediaObj.schema } : {}),
+    };
+  }
+
+  const docSecurity = (doc.security ?? []) as OpenAPIV3.SecurityRequirementObject[];
+  const opSecurity = (operation.security ?? docSecurity) as OpenAPIV3.SecurityRequirementObject[];
+  const securityNames = [...new Set(opSecurity.flatMap(req => Object.keys(req)))];
+
+  const responseCodes = Object.keys(operation.responses ?? {});
+  const successStatus = responseCodes.find(c => c.startsWith("2")) ?? responseCodes[0] ?? "200";
+
+  const pathParamNames = [...paramMap.values()]
+    .filter(p => p.in === "path")
+    .map(p => p.name);
+  const queryParamsList = [...paramMap.values()]
+    .filter(p => p.in === "query")
+    .map(p => ({ name: p.name, required: p.required }));
+  const reqBodyForSnippet = requestBody
+    ? { required: (operation.requestBody as OpenAPIV3.RequestBodyObject)?.required, schema: (requestBody as any).schema }
+    : undefined;
+
+  const testSnippet = generateTestSnippet({
+    method: method.toUpperCase(),
+    path: resolvedPath,
+    operationId: operation.operationId,
+    pathParams: pathParamNames,
+    queryParams: queryParamsList,
+    requestBody: reqBodyForSnippet,
+    hasSecurity: securityNames.length > 0,
+    successStatus,
+  });
+
+  const result: DescribeEndpointResult = {
+    method: method.toUpperCase(),
+    path: resolvedPath,
+    ...(operation.operationId ? { operationId: operation.operationId } : {}),
+    ...(operation.summary ? { summary: operation.summary } : {}),
+    ...(operation.description ? { description: operation.description } : {}),
+    ...(operation.tags?.length ? { tags: operation.tags } : {}),
+    deprecated: operation.deprecated ?? false,
+    security: securityNames,
+    parameters: grouped,
+    ...(requestBody ? { requestBody } : {}),
+    responses,
+    testSnippet,
+  };
+
+  return decycleSchema(result) as DescribeEndpointResult;
+}
+
+export async function describeCompact(
+  specPath: string,
+  options?: { insecure?: boolean },
+): Promise<CompactEndpoint[]> {
+  const doc = await readOpenApiSpec(specPath, options) as OpenAPIV3.Document;
+  const paths = doc.paths ?? {};
+  const result: CompactEndpoint[] = [];
+
+  for (const [path, pathItem] of Object.entries(paths)) {
+    for (const method of ["get","post","put","patch","delete","head","options","trace"]) {
+      const op = (pathItem as any)?.[method] as OpenAPIV3.OperationObject | undefined;
+      if (!op) continue;
+      result.push({
+        method: method.toUpperCase(),
+        path,
+        ...(op.operationId ? { operationId: op.operationId } : {}),
+        ...(op.summary ? { summary: op.summary } : {}),
+        deprecated: op.deprecated ?? false,
+      });
+    }
+  }
+
+  return result;
+}

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

@@ -196,6 +196,26 @@ 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
 
+### Suite variable isolation — IMPORTANT
+Each suite runs in its own variable scope. Captured variables (via \`capture:\`) do NOT propagate between suites.
+If multiple suites need auth, each suite must either:
+- Include its own login step with \`capture: auth_token\`
+- Or use \`auth_token\` from \`.env.yaml\` (pre-configured, no capture needed)
+
+Do NOT create a separate "setup" suite expecting other suites to use its captures.
+
+### ETag / Conditional Requests
+If-Match and If-None-Match require escaped quotes around the ETag value:
+\`\`\`yaml
+  - name: Update with ETag
+    PUT: /items/{{item_id}}
+    headers:
+      If-Match: "\\"{{etag}}\\""
+    json: { name: "updated" }
+    expect:
+      status: 200
+\`\`\`
+
 ### 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".

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}- {}`);