@elench/testkit 0.1.53 → 0.1.54

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;
+}

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

@@ -1,8 +1,14 @@
 import http from "k6/http";
 import { defaultOptions } from "./checks.js";
+import { emitArtifact } from "./artifacts.js";
 
 export { defaultOptions };
 
+const REDACTED_QUERY_PARAMS = new Set(["token", "organizationId"]);
+const REDACTED_HEADERS = new Set(["authorization", "cookie", "x-admin-key"]);
+const TRACE_PREVIEW_LIMIT = 320;
+const traceState = createTraceState();
+
 export function getEnv() {
   const BASE = __ENV.BASE_URL;
   const MACHINE_ID = __ENV.MACHINE_ID;
@@ -40,19 +46,23 @@ export function createHttpClient(config) {
   function request(method, path, setupData, body, extraHeaders = {}) {
     const url = `${baseUrl}${path}`;
     const headers = buildHeaders(getHeaders, setupData, extraHeaders);
-    return runHttpRequest(method, url, body, headers);
+    return runHttpRequest(method, path, url, body, headers);
   }
 
   function raw(method, path, body, extraHeaders = {}) {
     const url = `${baseUrl}${path}`;
     const headers = buildHeaders(getRawHeaders, null, extraHeaders);
-    return runHttpRequest(method, url, body, headers);
+    return runHttpRequest(method, path, url, body, headers);
   }
 
   function getWithHeaders(path, setupData, extraHeaders = {}) {
-    return http.get(`${baseUrl}${path}`, {
-      headers: buildHeaders(getHeaders, setupData, extraHeaders),
-    });
+    return runHttpRequest(
+      "GET",
+      path,
+      `${baseUrl}${path}`,
+      null,
+      buildHeaders(getHeaders, setupData, extraHeaders)
+    );
   }
 
   return {
@@ -117,19 +127,257 @@ export function makeGetWithHeaders(baseUrl, routeHeaders = {}, getHeaders = null
   }).getWithHeaders;
 }
 
-function runHttpRequest(method, url, body, headers) {
-  const options = { headers };
+function runHttpRequest(method, path, url, body, headers) {
+  const ordinal = nextTraceOrdinal();
+  const requestId = buildRequestId(ordinal);
+  const finalHeaders = {
+    ...headers,
+    "x-request-id": headers?.["x-request-id"] || headers?.["X-Request-Id"] || requestId,
+  };
+  const trace = createTrace({
+    ordinal,
+    requestId: finalHeaders["x-request-id"],
+    method,
+    path,
+    url,
+    requestHeaders: finalHeaders,
+  });
+  const options = { headers: finalHeaders };
+
+  let rawResponse;
+  if (method === "GET") rawResponse = http.get(url, options);
+  else if (method === "PUT") rawResponse = http.put(url, JSON.stringify(body), options);
+  else if (method === "POST") rawResponse = http.post(url, JSON.stringify(body), options);
+  else if (method === "PATCH") rawResponse = http.patch(url, JSON.stringify(body), options);
+  else if (method === "DELETE") rawResponse = http.del(url, null, options);
+  else throw new Error(`unsupported method: ${method}`);
+
+  finalizeTrace(trace, rawResponse);
+  traceState.traces.push(trace);
+  trimTraceBuffer();
+  return createWrappedResponse(rawResponse, trace);
+}
+
+export function startHttpTraceCollection(phase) {
+  traceState.phase = normalizeLabel(phase, "exec");
+  traceState.traces = [];
+  traceState.counter = 0;
+}
+
+export function emitHttpTraceCollectionArtifact() {
+  const traces = traceState.traces.map((trace) => ({ ...trace }));
+  if (traces.length > 0) {
+    emitArtifact(
+      "http-traces",
+      {
+        phase: traceState.phase,
+        traces,
+      },
+      {
+        kind: "testkit.http-traces",
+        summary: `${traces.length} HTTP trace(s)`,
+      }
+    );
+  }
+  startHttpTraceCollection(traceState.phase);
+}
 
-  if (method === "GET") return http.get(url, options);
-  if (method === "PUT") return http.put(url, JSON.stringify(body), options);
-  if (method === "POST") return http.post(url, JSON.stringify(body), options);
-  if (method === "PATCH") return http.patch(url, JSON.stringify(body), options);
-  if (method === "DELETE") return http.del(url, null, options);
+export function getHttpTrace(response) {
+  return response?.__testkit?.httpTrace || null;
+}
 
-  throw new Error(`unsupported method: ${method}`);
+export function summarizeHttpTrace(response) {
+  const trace = getHttpTrace(response);
+  if (!trace) return null;
+  return {
+    id: trace.id,
+    requestId: trace.requestId,
+    method: trace.method,
+    path: trace.path,
+    url: trace.url,
+    requestHeaders: trace.requestHeaders,
+    response: trace.response,
+    startedAt: trace.startedAt,
+    finishedAt: trace.finishedAt,
+    durationMs: trace.durationMs,
+  };
+}
+
+export function safeJson(response) {
+  try {
+    return {
+      ok: true,
+      value: JSON.parse(response?.body || ""),
+    };
+  } catch (error) {
+    return {
+      ok: false,
+      error: error instanceof Error ? error.message : String(error),
+    };
+  }
+}
+
+export function toBodyPreview(response) {
+  const contentType = toHeaderText(
+    response?.headers?.["Content-Type"] || response?.headers?.["content-type"] || null
+  );
+  const rawBody = typeof response?.body === "string" ? response.body : "";
+  if (!rawBody.trim()) return null;
+
+  if (contentType?.includes("application/json")) {
+    try {
+      return truncate(JSON.stringify(JSON.parse(rawBody)), TRACE_PREVIEW_LIMIT);
+    } catch {
+      return truncate(rawBody, TRACE_PREVIEW_LIMIT);
+    }
+  }
+
+  return truncate(rawBody, TRACE_PREVIEW_LIMIT);
+}
+
+function createTrace({ ordinal, requestId, method, path, url, requestHeaders }) {
+  return {
+    id: `${traceState.phase}-${String(ordinal).padStart(3, "0")}`,
+    requestId,
+    startedAt: new Date().toISOString(),
+    method,
+    path: sanitizePath(path),
+    url: sanitizeUrl(url),
+    requestHeaders: sanitizeHeaders(requestHeaders),
+  };
+}
+
+function finalizeTrace(trace, response) {
+  const finishedAt = new Date();
+  trace.finishedAt = finishedAt.toISOString();
+  trace.durationMs = Math.max(0, finishedAt.getTime() - Date.parse(trace.startedAt));
+  trace.response = {
+    status: Number(response?.status ?? 0) || null,
+    contentType: toHeaderText(
+      response?.headers?.["Content-Type"] || response?.headers?.["content-type"] || null
+    ),
+    bodyPreview: toBodyPreview(response),
+    bodyTruncated: typeof response?.body === "string" && response.body.length > TRACE_PREVIEW_LIMIT,
+  };
+}
+
+function trimTraceBuffer() {
+  if (traceState.traces.length <= traceState.maxEntries) return;
+  traceState.traces.splice(0, traceState.traces.length - traceState.maxEntries);
+}
+
+function createTraceState() {
+  return {
+    phase: "exec",
+    traces: [],
+    counter: 0,
+    maxEntries: 50,
+  };
+}
+
+function sanitizePath(rawPath) {
+  if (typeof rawPath !== "string") return rawPath;
+  const [pathname, query] = rawPath.split("?");
+  if (!query) return pathname;
+  const parts = query.split("&").map((entry) => {
+    const [rawKey, ...rawValueParts] = entry.split("=");
+    const key = decodeQueryComponent(rawKey);
+    if (!REDACTED_QUERY_PARAMS.has(key)) return entry;
+    const encodedKey = rawKey || encodeURIComponent(key);
+    return `${encodedKey}=${encodeURIComponent("[REDACTED]")}`;
+  });
+  return `${pathname}?${parts.join("&")}`;
+}
+
+function sanitizeUrl(rawUrl) {
+  if (typeof rawUrl !== "string") return rawUrl;
+  const protocolIndex = rawUrl.indexOf("://");
+  if (protocolIndex === -1) return sanitizePath(rawUrl);
+  const pathIndex = rawUrl.indexOf("/", protocolIndex + 3);
+  if (pathIndex === -1) return rawUrl;
+  return `${rawUrl.slice(0, pathIndex)}${sanitizePath(rawUrl.slice(pathIndex))}`;
+}
+
+function sanitizeHeaders(headers) {
+  if (!headers || typeof headers !== "object") return {};
+  const output = {};
+  for (const [name, value] of Object.entries(headers)) {
+    const normalizedName = String(name);
+    const lower = normalizedName.toLowerCase();
+    output[normalizedName] = REDACTED_HEADERS.has(lower) ? "[REDACTED]" : normalizeHeaderValue(value);
+  }
+  return output;
+}
+
+function normalizeHeaderValue(value) {
+  if (Array.isArray(value)) return value.map((entry) => String(entry));
+  if (value == null) return null;
+  return String(value);
+}
+
+function toHeaderText(value) {
+  const normalized = normalizeHeaderValue(value);
+  return Array.isArray(normalized) ? normalized[0] || null : normalized;
+}
+
+function buildRequestId(ordinal) {
+  const runtimeId = normalizeLabel(__ENV.TESTKIT_RUNTIME_ID, "runtime");
+  return `tk_${runtimeId}_${traceState.phase}_${String(ordinal).padStart(4, "0")}`;
+}
+
+function nextTraceOrdinal() {
+  traceState.counter += 1;
+  return traceState.counter;
+}
+
+function truncate(value, limit) {
+  const normalized = String(value || "").replace(/\s+/g, " ").trim();
+  if (normalized.length <= limit) return normalized;
+  return `${normalized.slice(0, Math.max(0, limit - 3))}...`;
+}
+
+function normalizeLabel(value, fallback) {
+  if (typeof value !== "string") return fallback;
+  const normalized = value.trim();
+  return normalized.length > 0 ? normalized : fallback;
 }
 
 function safeHeaders(builder, setupData) {
   if (typeof builder !== "function") return {};
   return builder(setupData) || {};
 }
+
+function createWrappedResponse(rawResponse, trace) {
+  if (!rawResponse || typeof rawResponse !== "object") {
+    return rawResponse;
+  }
+
+  const wrapped = {};
+  for (const key of Object.keys(rawResponse)) {
+    wrapped[key] = rawResponse[key];
+  }
+
+  const prototype = Object.getPrototypeOf(rawResponse);
+  if (prototype && typeof prototype === "object") {
+    for (const name of Object.getOwnPropertyNames(prototype)) {
+      if (name === "constructor" || name in wrapped) continue;
+      const descriptor = Object.getOwnPropertyDescriptor(prototype, name);
+      if (!descriptor || typeof descriptor.value !== "function") continue;
+      wrapped[name] = descriptor.value.bind(rawResponse);
+    }
+  }
+
+  wrapped.__testkit = {
+    httpTrace: trace,
+    rawResponse,
+  };
+  return wrapped;
+}
+
+function decodeQueryComponent(value) {
+  try {
+    return decodeURIComponent(String(value || ""));
+  } catch {
+    return String(value || "");
+  }
+}

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

@@ -2,10 +2,16 @@ import { fail } from "k6";
 import {
   defaultOptions,
   emitFailureCollectionArtifact,
+  recordFailureDetail,
   recordRuntimeFailure,
   startFailureCollection,
 } from "./checks.js";
-import { createHttpClient, getEnv } from "./http.js";
+import {
+  createHttpClient,
+  emitHttpTraceCollectionArtifact,
+  getEnv,
+  startHttpTraceCollection,
+} from "./http.js";
 import {
   clearRuntimeContext,
   registerRuntimeContext,
@@ -22,21 +28,25 @@ export function defineHttpSuite(configOrRun, maybeRun) {
     setup() {
       const resolved = resolveRuntimeConfig(config);
       startFailureCollection("setup");
+      startHttpTraceCollection("setup");
       try {
         registerRuntimeContext({ env: resolved.env, http: resolved.client.rawHttp || null });
         if (typeof resolved.auth?.setup !== "function") return null;
         return resolved.auth.setup({ env: resolved.env });
       } catch (error) {
+        recordFailureDetail(buildRuntimeExceptionDetail("setup", error));
         recordRuntimeFailure();
         fail(formatFatalSuiteError("setup", error));
       } finally {
         emitFailureCollectionArtifact();
+        emitHttpTraceCollectionArtifact();
         clearRuntimeContext();
       }
     },
     exec(setupData) {
       const resolved = resolveRuntimeConfig(config);
       startFailureCollection("exec");
+      startHttpTraceCollection("exec");
       try {
         registerRuntimeContext({ env: resolved.env, http: resolved.client.rawHttp || null });
         return run({
@@ -48,10 +58,12 @@ export function defineHttpSuite(configOrRun, maybeRun) {
           session: setupData,
         });
       } catch (error) {
+        recordFailureDetail(buildRuntimeExceptionDetail("exec", error));
         recordRuntimeFailure();
         fail(formatFatalSuiteError("exec", error));
       } finally {
         emitFailureCollectionArtifact();
+        emitHttpTraceCollectionArtifact();
         clearRuntimeContext();
       }
     },
@@ -123,3 +135,36 @@ function formatFatalSuiteError(phase, error) {
   }
   return `Uncaught testkit suite error during ${phase}: ${String(error)}`;
 }
+
+function buildRuntimeExceptionDetail(phase, error) {
+  const message =
+    error instanceof Error ? error.message : String(error);
+  const stack = error instanceof Error && typeof error.stack === "string" ? error.stack : "";
+  const location = extractLocationFromStack(stack);
+  return {
+    kind: "runtime-exception",
+    key: location ? `${location.path}:${location.line}:${location.column}` : `runtime-exception:${phase}:${message}`,
+    title: "Uncaught runtime exception",
+    message: `Uncaught testkit suite error during ${phase}: ${message}`,
+    location,
+    stack,
+  };
+}
+
+function extractLocationFromStack(stack) {
+  if (!stack) return null;
+  const matches = [...String(stack).matchAll(/(file:\/\/[^\s)]+|\/[^\s):]+):(\d+):(\d+)/g)].map((match) => ({
+    path: normalizeStackPath(match[1]),
+    line: Number(match[2]),
+    column: Number(match[3]),
+  }));
+  return matches[0] || null;
+}
+
+function normalizeStackPath(rawPath) {
+  if (typeof rawPath !== "string") return rawPath;
+  if (rawPath.startsWith("file://")) {
+    return rawPath.slice("file://".length);
+  }
+  return rawPath;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@elench/testkit",
-  "version": "0.1.53",
+  "version": "0.1.54",
   "description": "CLI for discovering and running local HTTP, DAL, and Playwright test suites",
   "type": "module",
   "types": "./lib/index.d.ts",
@@ -48,10 +48,12 @@
     "vitest": "^3.2.4"
   },
   "dependencies": {
+    "@babel/code-frame": "^7.29.0",
     "@oclif/core": "^4.10.6",
     "esbuild": "^0.25.11",
     "execa": "^9.5.0",
     "ink": "^7.0.1",
+    "picocolors": "^1.1.1",
     "react": "^19.2.5"
   },
   "engines": {