@elench/testkit 0.1.53 → 0.1.55

package/lib/runner/triage.mjs

@@ -80,6 +80,49 @@ export function applyKnownFailuresToArtifacts(runArtifact, statusArtifact, known
   return { runArtifact, statusArtifact };
 }
 
+export function applyKnownFailureIssueValidationToArtifacts(
+  runArtifact,
+  statusArtifact,
+  issueValidation
+) {
+  if (!issueValidation) return { runArtifact, statusArtifact };
+
+  const validationById = new Map(
+    (issueValidation.entries || []).map((entry) => [entry.id, entry])
+  );
+
+  for (const entry of [...extractRunFileEntries(runArtifact), ...extractStatusFileEntries(statusArtifact)]) {
+    const triage = entry.target ? entry.target.triage : entry.triage;
+    if (!triage?.entries?.length) continue;
+
+    const matchedValidationEntries = triage.entries
+      .map((triageEntry) => validationById.get(triageEntry.id))
+      .filter(Boolean);
+
+    if (matchedValidationEntries.length === 0) continue;
+
+    const enrichedEntries = triage.entries.map((triageEntry) => {
+      const validationEntry = validationById.get(triageEntry.id);
+      if (!validationEntry) return triageEntry;
+      return {
+        ...triageEntry,
+        github: validationEntry.github,
+        validationStatus: validationEntry.status,
+        findings: validationEntry.findings,
+      };
+    });
+
+    const nextTriage = {
+      ...triage,
+      entries: enrichedEntries,
+      availability: summarizeIssueValidationAvailability(issueValidation, matchedValidationEntries),
+    };
+    setEntryTriage(entry, nextTriage);
+  }
+
+  return { runArtifact, statusArtifact };
+}
+
 function toArtifactTriageEntry(entry) {
   return {
     id: entry.id,
@@ -152,3 +195,27 @@ function setEntryTriage(entry, triage) {
   }
   entry.triage = triage;
 }
+
+function summarizeIssueValidationAvailability(issueValidation, entries) {
+  if (entries.some((entry) => entry.github?.cached)) {
+    return {
+      mode: "cache",
+      reason: issueValidation.availability?.usedCachedFallback
+        ? "used stale cache"
+        : "used cached issue metadata",
+    };
+  }
+  if (entries.some((entry) => entry.status === "validation_unavailable")) {
+    const globalReason = (issueValidation.findings || []).find(
+      (finding) => finding.code === "validation_unavailable"
+    );
+    return {
+      mode: "offline",
+      reason: globalReason?.message || "validation unavailable",
+    };
+  }
+  return {
+    mode: "live",
+    reason: null,
+  };
+}

package/lib/runtime/index.d.ts

@@ -9,6 +9,9 @@ export interface RuntimeCookie {
 }
 
 export interface RuntimeResponse {
+  __testkit?: {
+    httpTrace?: RuntimeHttpTrace;
+  };
   body: string;
   cookies?: Record<string, RuntimeCookie[]>;
   headers?: Record<string, string | string[] | undefined>;
@@ -18,6 +21,24 @@ export interface RuntimeResponse {
   };
 }
 
+export interface RuntimeHttpTrace {
+  id: string;
+  requestId: string;
+  startedAt: string;
+  finishedAt?: string;
+  durationMs?: number;
+  method: RuntimeMethod;
+  path: string;
+  url: string;
+  requestHeaders: Record<string, string | string[] | null>;
+  response?: {
+    status: number | null;
+    contentType: string | string[] | null;
+    bodyPreview: string | null;
+    bodyTruncated: boolean;
+  };
+}
+
 export interface RuntimeOptions {
   [key: string]: unknown;
   thresholds?: Record<string, unknown>;
@@ -144,6 +165,12 @@ export declare const check: <T>(
   value: T,
   checks: Record<string, (value: T) => boolean>
 ) => boolean;
+export declare const evaluateCheck: <T>(
+  value: T,
+  checkName: string,
+  predicate: (value: T) => boolean,
+  detailFactory?: (() => Record<string, unknown>) | null
+) => boolean;
 export declare const fail: (message: string) => never;
 export declare const group: (name: string, fn: () => void) => void;
 export declare const sleep: (seconds?: number) => void;
@@ -152,6 +179,9 @@ export declare const http: RuntimeHttpClient;
 
 export declare function file(data: unknown, filename?: string, contentType?: string): unknown;
 export declare function json<T = unknown>(response: Pick<RuntimeResponse, "body">): T;
+export declare function safeJson<T = unknown>(
+  response: Pick<RuntimeResponse, "body">
+): { ok: true; value: T } | { ok: false; error: string };
 export declare function remainingTimeSeconds(): number;
 export declare function waitFor<T>(
   read: () => T,
@@ -188,6 +218,9 @@ export declare function truncate(db: RuntimeDb, ...tables: string[]): void;
 export declare function getTestkitContext(): TestkitRuntimeContext;
 
 export declare function getEnv(): RuntimeEnv;
+export declare function getHttpTrace(response: RuntimeResponse): RuntimeHttpTrace | null;
+export declare function summarizeHttpTrace(response: RuntimeResponse): RuntimeHttpTrace | null;
+export declare function toBodyPreview(response: RuntimeResponse): string | null;
 export declare function createHttpClient<TSetup = unknown>(
   config: HttpClientConfig<TSetup>
 ): HttpClient<TSetup>;
@@ -207,6 +240,33 @@ export declare function makeGetWithHeaders<TSetup = unknown>(
   getHeaders?: (setupData?: TSetup | null) => RuntimeHeaders | void
 ): HttpClient<TSetup>["getWithHeaders"];
 
+export declare function expectStatus(
+  response: RuntimeResponse,
+  expected: number,
+  label?: string | null
+): boolean;
+export declare function expectStatusOneOf(
+  response: RuntimeResponse,
+  expectedValues: number[],
+  label?: string | null
+): boolean;
+export declare function expectNotStatus(
+  response: RuntimeResponse,
+  unexpected: number,
+  label?: string | null
+): boolean;
+export declare function expectJson<T = unknown>(
+  response: RuntimeResponse,
+  predicate: (value: T) => boolean,
+  label?: string | null
+): boolean;
+export declare function expectJsonPath(
+  response: RuntimeResponse,
+  path: string,
+  predicate: (value: unknown) => boolean,
+  label?: string | null
+): boolean;
+
 declare global {
   const __ENV: Record<string, string | undefined>;
 }

package/lib/runtime/index.mjs

@@ -26,10 +26,18 @@ export {
   allMatch,
   contains,
   defaultOptions,
+  evaluateCheck,
   isSorted,
   json,
   singleIterationOptions,
 } from "../runtime-src/k6/checks.js";
+export {
+  expectJson,
+  expectJsonPath,
+  expectNotStatus,
+  expectStatus,
+  expectStatusOneOf,
+} from "../runtime-src/k6/http-assertions.js";
 export {
   createDalContext,
   openDb,
@@ -39,9 +47,13 @@ export {
   createHttpClient,
   defaultOptions as httpDefaultOptions,
   getEnv,
+  getHttpTrace,
   makeGetWithHeaders,
   makeRawReq,
   makeReq,
+  safeJson,
+  summarizeHttpTrace,
+  toBodyPreview,
 } from "../runtime-src/k6/http.js";
 
 export function getTestkitContext() {

package/lib/runtime-src/k6/checks.js

@@ -24,23 +24,33 @@ export function check(value, checks) {
 
   for (const [name, predicate] of Object.entries(checks || {})) {
     const checkName = normalizeLabel(name, "unnamed check");
-    const passed = k6Check(value, { [checkName]: predicate });
-    if (!passed) {
-      recordFailureDetail({
-        kind: "k6-check",
-        key: buildFailureKey(failureState.groupStack, checkName),
-        title: checkName,
-        checkName,
-        groupPath: [...failureState.groupStack],
-        phase: failureState.phase,
-      });
-      allPassed = false;
-    }
+    const passed = evaluateCheck(value, checkName, predicate);
+    if (!passed) allPassed = false;
   }
 
   return allPassed;
 }
 
+export function evaluateCheck(value, checkName, predicate, detailFactory = null) {
+  const normalizedName = normalizeLabel(checkName, "unnamed check");
+  const passed = k6Check(value, { [normalizedName]: predicate });
+  if (!passed) {
+    recordFailureDetail(
+      typeof detailFactory === "function"
+        ? detailFactory()
+        : {
+            kind: "k6-check",
+            key: buildFailureKey(failureState.groupStack, normalizedName),
+            title: normalizedName,
+            checkName: normalizedName,
+            groupPath: [...failureState.groupStack],
+            phase: failureState.phase,
+          }
+    );
+  }
+  return passed;
+}
+
 export function group(name, fn) {
   const groupName = normalizeLabel(name, "unnamed group");
 
@@ -158,6 +168,24 @@ function normalizeFailureDetail(detail) {
   const message = normalizeLabel(detail.message, null);
   if (message) normalized.message = message;
 
+  if (detail.expected !== undefined) normalized.expected = detail.expected;
+  if (detail.actual !== undefined) normalized.actual = detail.actual;
+
+  const traceId = normalizeLabel(detail.traceId, null);
+  if (traceId) normalized.traceId = traceId;
+
+  const request = normalizeObject(detail.request);
+  if (request) normalized.request = request;
+
+  const response = normalizeObject(detail.response);
+  if (response) normalized.response = response;
+
+  const location = normalizeObject(detail.location);
+  if (location) normalized.location = location;
+
+  const stack = normalizeLabel(detail.stack, null);
+  if (stack) normalized.stack = stack;
+
   const groupPath = Array.isArray(detail.groupPath)
     ? detail.groupPath.map((entry) => normalizeLabel(entry, null)).filter(Boolean)
     : [];
@@ -176,3 +204,8 @@ function normalizeLabel(value, fallback) {
   const normalized = value.trim();
   return normalized.length > 0 ? normalized : fallback;
 }
+
+function normalizeObject(value) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return null;
+  return JSON.parse(JSON.stringify(value));
+}

package/lib/runtime-src/k6/http-assertions.js

@@ -0,0 +1,214 @@
+import { evaluateCheck, recordFailureDetail } from "./checks.js";
+import { safeJson, summarizeHttpTrace, toBodyPreview } from "./http.js";
+
+export function expectStatus(response, expected, label = null) {
+  return expectStatusOneOf(response, [expected], label);
+}
+
+export function expectStatusOneOf(response, expectedValues, label = null) {
+  const values = normalizeExpectedValues(expectedValues);
+  const title = normalizeLabel(label, buildExpectedStatusTitle(values));
+  const trace = summarizeHttpTrace(response);
+  const actual = Number(response?.status ?? 0);
+
+  return evaluateCheck(
+    response,
+    title,
+    (res) => values.includes(Number(res?.status ?? 0)),
+    () => buildHttpAssertionDetail({
+      kind: "http-assertion",
+      title,
+      trace,
+      expected: values.length === 1 ? values[0] : values,
+      actual,
+      response,
+      message: `${trace?.method || "HTTP"} ${trace?.path || "(unknown path)"} expected ${formatExpectedValues(values)}, got ${actual}`,
+    })
+  );
+}
+
+export function expectNotStatus(response, unexpected, label = null) {
+  const title = normalizeLabel(label, `status is not ${unexpected}`);
+  const trace = summarizeHttpTrace(response);
+  const actual = Number(response?.status ?? 0);
+
+  return evaluateCheck(
+    response,
+    title,
+    (res) => Number(res?.status ?? 0) !== unexpected,
+    () => buildHttpAssertionDetail({
+      kind: "http-assertion",
+      title,
+      trace,
+      expected: { not: unexpected },
+      actual,
+      response,
+      message: `${trace?.method || "HTTP"} ${trace?.path || "(unknown path)"} expected not ${unexpected}, got ${actual}`,
+    })
+  );
+}
+
+export function expectJson(response, predicate, label = null) {
+  const title = normalizeLabel(label, "response JSON matches expectation");
+  const trace = summarizeHttpTrace(response);
+  const jsonResult = safeJson(response);
+
+  if (!jsonResult.ok) {
+    recordFailureDetail(
+      buildHttpAssertionDetail({
+        kind: "http-json-assertion",
+        title,
+        trace,
+        expected: "valid JSON response",
+        actual: "invalid JSON response",
+        response,
+        message: `${trace?.method || "HTTP"} ${trace?.path || "(unknown path)"} did not return valid JSON`,
+      })
+    );
+    return false;
+  }
+
+  return evaluateCheck(
+    jsonResult.value,
+    title,
+    (value) => Boolean(predicate(value)),
+    () => ({
+      kind: "json-assertion",
+      key: buildTraceFailureKey(trace, title),
+      title,
+      message: `${trace?.method || "HTTP"} ${trace?.path || "(unknown path)"} JSON assertion failed`,
+      request: trace ? buildRequestSummary(trace) : null,
+      response: trace ? buildResponseSummary(trace) : null,
+      actual: toValuePreview(jsonResult.value),
+    })
+  );
+}
+
+export function expectJsonPath(response, path, predicate, label = null) {
+  const title = normalizeLabel(label, `response JSON path ${path} matches expectation`);
+  const trace = summarizeHttpTrace(response);
+  const jsonResult = safeJson(response);
+
+  if (!jsonResult.ok) {
+    recordFailureDetail(
+      buildHttpAssertionDetail({
+        kind: "http-json-assertion",
+        title,
+        trace,
+        expected: `valid JSON containing ${path}`,
+        actual: "invalid JSON response",
+        response,
+        message: `${trace?.method || "HTTP"} ${trace?.path || "(unknown path)"} did not return valid JSON`,
+      })
+    );
+    return false;
+  }
+
+  const actualValue = getJsonPathValue(jsonResult.value, path);
+  return evaluateCheck(
+    actualValue,
+    title,
+    (value) => Boolean(predicate(value)),
+    () => ({
+      kind: "json-path-assertion",
+      key: buildTraceFailureKey(trace, title),
+      title,
+      message: `${trace?.method || "HTTP"} ${trace?.path || "(unknown path)"} JSON path ${path} assertion failed`,
+      expected: path,
+      actual: toValuePreview(actualValue),
+      request: trace ? buildRequestSummary(trace) : null,
+      response: trace ? buildResponseSummary(trace) : null,
+    })
+  );
+}
+
+function buildHttpAssertionDetail({ kind, title, trace, expected, actual, response, message }) {
+  return {
+    kind,
+    key: buildTraceFailureKey(trace, title),
+    title,
+    message,
+    expected,
+    actual,
+    traceId: trace?.id || null,
+    request: trace ? buildRequestSummary(trace) : null,
+    response: trace ? buildResponseSummary(trace, response) : null,
+  };
+}
+
+function buildRequestSummary(trace) {
+  return {
+    id: trace.id,
+    requestId: trace.requestId,
+    method: trace.method,
+    path: trace.path,
+    url: trace.url,
+    headers: trace.requestHeaders || {},
+  };
+}
+
+function buildResponseSummary(trace, response = null) {
+  return {
+    status: (trace.response?.status ?? Number(response?.status ?? 0)) || null,
+    contentType: trace.response?.contentType ?? null,
+    bodyPreview: trace.response?.bodyPreview ?? toBodyPreview(response),
+    bodyTruncated: Boolean(trace.response?.bodyTruncated),
+  };
+}
+
+function buildTraceFailureKey(trace, title) {
+  if (trace?.path && trace?.method) {
+    return `${trace.method} ${trace.path} > ${title}`;
+  }
+  return title;
+}
+
+function buildExpectedStatusTitle(expectedValues) {
+  return `status is ${formatExpectedValues(expectedValues)}`;
+}
+
+function formatExpectedValues(values) {
+  if (!Array.isArray(values) || values.length === 0) return "expected";
+  if (values.length === 1) return String(values[0]);
+  return values.map((value) => String(value)).join(" or ");
+}
+
+function normalizeExpectedValues(values) {
+  const normalized = (Array.isArray(values) ? values : [values])
+    .map((value) => Number(value))
+    .filter((value) => Number.isFinite(value));
+
+  if (normalized.length === 0) {
+    throw new Error("expectStatusOneOf requires at least one numeric expected status");
+  }
+  return normalized;
+}
+
+function getJsonPathValue(value, path) {
+  const tokens = String(path || "")
+    .split(".")
+    .map((token) => token.trim())
+    .filter(Boolean);
+
+  let current = value;
+  for (const token of tokens) {
+    if (current == null || typeof current !== "object") return undefined;
+    current = current[token];
+  }
+  return current;
+}
+
+function toValuePreview(value) {
+  if (value == null) return value;
+  if (typeof value === "string") return value.length > 240 ? `${value.slice(0, 237)}...` : value;
+  try {
+    return JSON.stringify(value).slice(0, 240);
+  } catch {
+    return String(value);
+  }
+}
+
+function normalizeLabel(value, fallback) {
+  const normalized = typeof value === "string" ? value.trim() : "";
+  return normalized.length > 0 ? normalized : fallback;
+}