@elench/testkit 0.1.81 → 0.1.83

package/lib/runtime/index.d.ts

@@ -23,6 +23,9 @@ export interface RuntimeResponse {
 
 export interface RuntimeHttpTrace {
   id: string;
+  actorName: string | null;
+  organizationKey?: string | null;
+  organizationName?: string | null;
   requestId: string;
   startedAt: string;
   finishedAt?: string;
@@ -93,6 +96,27 @@ export interface RuntimeHttpClient {
   put(url: string, body?: unknown, params?: HttpRequestParams): RuntimeResponse;
 }
 
+export interface RuntimeActorRecord<TSession = Record<string, unknown>> {
+  actorIndex: number;
+  actorName: string;
+  email?: string;
+  name?: string;
+  organizationKey?: string;
+  organizationName?: string;
+  session: TSession | null;
+}
+
+export interface AuthSessionBundle<TSession = Record<string, unknown>> {
+  actors: Record<string, RuntimeActorRecord<TSession> & TSession>;
+  primaryActor: string | null;
+}
+
+export interface HttpHeaderBuildContext<TSession = Record<string, unknown>> {
+  actor: (RuntimeActorRecord<TSession> & TSession) | null;
+  actorName: string | null;
+  sessionBundle: AuthSessionBundle<TSession> | null;
+}
+
 export interface Metric {
   add(value: number): void;
 }
@@ -109,53 +133,105 @@ export declare class Trend implements Metric {
 
 export interface HttpClientConfig<TSetup = unknown> {
   baseUrl: string;
+  defaultActor?: string | null;
   defaultHeaders?: RuntimeHeaders;
-  getHeaders?: (setupData?: TSetup | null) => RuntimeHeaders | void;
-  getRawHeaders?: (setupData?: TSetup | null) => RuntimeHeaders | void;
+  getHeaders?: (context: HttpHeaderBuildContext<TSetup>) => RuntimeHeaders | void;
+  getRawHeaders?: (context: HttpHeaderBuildContext<TSetup>) => RuntimeHeaders | void;
   routeHeaders?: RuntimeHeaders;
+  sessionBundle?: AuthSessionBundle<TSetup> | null;
 }
 
-export interface HttpClient<TSetup = unknown> {
-  delete(path: string, setupData?: TSetup | null, extraHeaders?: RuntimeHeaders): RuntimeResponse;
-  get(path: string, setupData?: TSetup | null, extraHeaders?: RuntimeHeaders): RuntimeResponse;
-  getWithHeaders(
-    path: string,
-    setupData?: TSetup | null,
-    extraHeaders?: RuntimeHeaders
-  ): RuntimeResponse;
-  patch(
+export interface MultipartFileInput {
+  contentType?: string;
+  data: unknown;
+  field: string;
+  filename?: string;
+}
+
+export interface MultipartPayload {
+  fields?: Record<string, unknown>;
+  files?: MultipartFileInput[];
+}
+
+export interface MultipartRequestClient {
+  patch(path: string, payload: MultipartPayload, extraHeaders?: RuntimeHeaders): RuntimeResponse;
+  post(path: string, payload: MultipartPayload, extraHeaders?: RuntimeHeaders): RuntimeResponse;
+  put(path: string, payload: MultipartPayload, extraHeaders?: RuntimeHeaders): RuntimeResponse;
+}
+
+export interface RawRequestClient {
+  (
+    method: RuntimeMethod,
     path: string,
-    setupData?: TSetup | null,
     body?: unknown,
     extraHeaders?: RuntimeHeaders
   ): RuntimeResponse;
-  post(
+  as(actorName: string): RawRequestClient;
+  delete(path: string, extraHeaders?: RuntimeHeaders): RuntimeResponse;
+  get(path: string, extraHeaders?: RuntimeHeaders): RuntimeResponse;
+  headers(extraHeaders?: RuntimeHeaders): RuntimeHeaders;
+  multipart: MultipartRequestClient;
+  patch(path: string, body?: unknown, extraHeaders?: RuntimeHeaders): RuntimeResponse;
+  post(path: string, body?: unknown, extraHeaders?: RuntimeHeaders): RuntimeResponse;
+  put(path: string, body?: unknown, extraHeaders?: RuntimeHeaders): RuntimeResponse;
+  request(
+    method: RuntimeMethod,
     path: string,
-    setupData?: TSetup | null,
     body?: unknown,
     extraHeaders?: RuntimeHeaders
   ): RuntimeResponse;
-  put(
+}
+
+export interface ActorRequestClient {
+  headers(extraHeaders?: RuntimeHeaders): RuntimeHeaders;
+  multipart: MultipartRequestClient;
+  raw(
+    method: RuntimeMethod,
     path: string,
-    setupData?: TSetup | null,
     body?: unknown,
     extraHeaders?: RuntimeHeaders
   ): RuntimeResponse;
-  raw(
+  rawDelete(path: string, extraHeaders?: RuntimeHeaders): RuntimeResponse;
+  rawGet(path: string, extraHeaders?: RuntimeHeaders): RuntimeResponse;
+  rawHeaders(extraHeaders?: RuntimeHeaders): RuntimeHeaders;
+  rawMultipart: MultipartRequestClient;
+  rawPatch(path: string, body?: unknown, extraHeaders?: RuntimeHeaders): RuntimeResponse;
+  rawPost(path: string, body?: unknown, extraHeaders?: RuntimeHeaders): RuntimeResponse;
+  rawPut(path: string, body?: unknown, extraHeaders?: RuntimeHeaders): RuntimeResponse;
+  rawReq: RawRequestClient;
+  delete(path: string, extraHeaders?: RuntimeHeaders): RuntimeResponse;
+  get(path: string, extraHeaders?: RuntimeHeaders): RuntimeResponse;
+  patch(path: string, body?: unknown, extraHeaders?: RuntimeHeaders): RuntimeResponse;
+  post(path: string, body?: unknown, extraHeaders?: RuntimeHeaders): RuntimeResponse;
+  put(path: string, body?: unknown, extraHeaders?: RuntimeHeaders): RuntimeResponse;
+  request(
     method: RuntimeMethod,
     path: string,
     body?: unknown,
     extraHeaders?: RuntimeHeaders
   ): RuntimeResponse;
+}
+
+export interface HttpClient<TSetup = unknown> {
+  as(actorName: string): ActorRequestClient;
+  headers(extraHeaders?: RuntimeHeaders): RuntimeHeaders;
+  multipart: MultipartRequestClient;
+  delete(path: string, extraHeaders?: RuntimeHeaders): RuntimeResponse;
+  get(path: string, extraHeaders?: RuntimeHeaders): RuntimeResponse;
+  patch(path: string, body?: unknown, extraHeaders?: RuntimeHeaders): RuntimeResponse;
+  post(path: string, body?: unknown, extraHeaders?: RuntimeHeaders): RuntimeResponse;
+  put(path: string, body?: unknown, extraHeaders?: RuntimeHeaders): RuntimeResponse;
   rawDelete(path: string, extraHeaders?: RuntimeHeaders): RuntimeResponse;
   rawGet(path: string, extraHeaders?: RuntimeHeaders): RuntimeResponse;
+  rawHeaders(actorName?: string | null, extraHeaders?: RuntimeHeaders): RuntimeHeaders;
+  rawMultipart: MultipartRequestClient;
   rawPatch(path: string, body?: unknown, extraHeaders?: RuntimeHeaders): RuntimeResponse;
   rawPost(path: string, body?: unknown, extraHeaders?: RuntimeHeaders): RuntimeResponse;
   rawPut(path: string, body?: unknown, extraHeaders?: RuntimeHeaders): RuntimeResponse;
+  raw: RawRequestClient;
   request(
     method: RuntimeMethod,
     path: string,
-    setupData?: TSetup | null,
     body?: unknown,
     extraHeaders?: RuntimeHeaders
   ): RuntimeResponse;
@@ -226,19 +302,16 @@ export declare function createHttpClient<TSetup = unknown>(
 ): HttpClient<TSetup>;
 export declare function makeReq<TSetup = unknown>(
   baseUrl: string,
+  sessionBundle?: AuthSessionBundle<TSetup> | null,
   routeHeaders?: RuntimeHeaders,
-  getHeaders?: (setupData?: TSetup | null) => RuntimeHeaders | void
-): HttpClient<TSetup>["request"];
+  getHeaders?: (context: HttpHeaderBuildContext<TSetup>) => RuntimeHeaders | void,
+  defaultActor?: string | null
+): HttpClient<TSetup>;
 export declare function makeRawReq(
   baseUrl: string,
   routeHeaders?: RuntimeHeaders,
-  getRawHeaders?: (setupData?: never) => RuntimeHeaders | void
-): HttpClient["raw"];
-export declare function makeGetWithHeaders<TSetup = unknown>(
-  baseUrl: string,
-  routeHeaders?: RuntimeHeaders,
-  getHeaders?: (setupData?: TSetup | null) => RuntimeHeaders | void
-): HttpClient<TSetup>["getWithHeaders"];
+  getRawHeaders?: (context: HttpHeaderBuildContext<never>) => RuntimeHeaders | void
+): RawRequestClient;
 
 export declare function expectStatus(
   response: RuntimeResponse,
@@ -266,6 +339,83 @@ export declare function expectJsonPath(
   predicate: (value: unknown) => boolean,
   label?: string | null
 ): boolean;
+export declare function expectErrorShape(
+  response: RuntimeResponse,
+  label?: string | null
+): boolean;
+export declare function expectErrorMessage(
+  response: RuntimeResponse,
+  label?: string | null
+): boolean;
+export declare function expectResponse(
+  response: RuntimeResponse,
+  predicate: (response: RuntimeResponse) => boolean,
+  label: string
+): boolean;
+export declare function expectValue<T>(
+  value: T,
+  predicate: (value: T) => boolean,
+  label: string
+): boolean;
+export declare function expectCondition(
+  predicate: () => boolean,
+  label: string
+): boolean;
+
+export declare function runAuthGateChecks(
+  rawReq: RawRequestClient,
+  scope: string,
+  descriptors: {
+    delete?: Array<string>;
+    get?: Array<string>;
+    patch?: Array<string | [string, unknown]>;
+    post?: Array<string | [string, unknown]>;
+    put?: Array<string | [string, unknown]>;
+    validateGetErrorShape?: boolean;
+  }
+): void;
+export declare function runPaginationChecks(
+  req: Pick<HttpClient, "get">,
+  endpoint: string,
+  options?: { auditLogsExtra?: boolean }
+): void;
+
+export interface RuntimeExpectNamespace {
+  condition: typeof expectCondition;
+  error: {
+    message: typeof expectErrorMessage;
+    shape: typeof expectErrorShape;
+  };
+  json: typeof expectJson;
+  jsonPath: typeof expectJsonPath;
+  notStatus: typeof expectNotStatus;
+  response: typeof expectResponse;
+  status: typeof expectStatus;
+  statusOneOf: typeof expectStatusOneOf;
+  value: typeof expectValue;
+}
+
+export interface RuntimeParseNamespace {
+  cookie(response: Pick<RuntimeResponse, "headers">, cookieName: string): string | null;
+  json<T = unknown>(response: Pick<RuntimeResponse, "body">): T;
+  safeJson: typeof safeJson;
+  sse(body: string): Array<{ event: string | null; data: unknown }>;
+  sseEvent<T = unknown>(body: string, eventName: string): T | null;
+}
+
+export interface RuntimeChecksNamespace {
+  authGate: typeof runAuthGateChecks;
+  pagination: typeof runPaginationChecks;
+}
+
+export interface RuntimeNetworkNamespace {
+  deterministicIp(seed: string | number, offset?: number): string;
+}
+
+export declare const expect: RuntimeExpectNamespace;
+export declare const parse: RuntimeParseNamespace;
+export declare const checks: RuntimeChecksNamespace;
+export declare const network: RuntimeNetworkNamespace;
 
 declare global {
   const __ENV: Record<string, string | undefined>;

package/lib/runtime/index.mjs

@@ -1,6 +1,13 @@
 import rawHttp from "k6/http";
 import { Rate, Trend } from "k6/metrics";
 import { fail, sleep } from "k6";
+import { deriveDeterministicIp } from "../runtime-src/shared/error-body.mjs";
+import {
+  extractCookie,
+  getSseEventData,
+  parseJsonBody,
+  parseSseEvents,
+} from "../runtime-src/shared/http-parsing.mjs";
 import {
   formatWaitForTimeoutError,
   normalizeWaitIntervalSeconds,
@@ -27,17 +34,26 @@ export {
   contains,
   defaultOptions,
   evaluateCheck,
-  isSorted,
   json,
+  isSorted,
   singleIterationOptions,
 } from "../runtime-src/k6/checks.js";
 export {
+  expectCondition,
+  expectErrorMessage,
+  expectErrorShape,
   expectJson,
   expectJsonPath,
   expectNotStatus,
+  expectResponse,
   expectStatus,
   expectStatusOneOf,
+  expectValue,
 } from "../runtime-src/k6/http-assertions.js";
+export {
+  runAuthGateChecks,
+  runPaginationChecks,
+} from "../runtime-src/k6/http-checks.js";
 export {
   createDalContext,
   openDb,
@@ -48,14 +64,63 @@ export {
   defaultOptions as httpDefaultOptions,
   getEnv,
   getHttpTrace,
-  makeGetWithHeaders,
-  makeRawReq,
   makeReq,
+  makeRawReq,
   safeJson,
   summarizeHttpTrace,
   toBodyPreview,
 } from "../runtime-src/k6/http.js";
 
+import {
+  expectCondition,
+  expectErrorMessage,
+  expectErrorShape,
+  expectJson,
+  expectJsonPath,
+  expectNotStatus,
+  expectResponse,
+  expectStatus,
+  expectStatusOneOf,
+  expectValue,
+} from "../runtime-src/k6/http-assertions.js";
+import {
+  runAuthGateChecks,
+  runPaginationChecks,
+} from "../runtime-src/k6/http-checks.js";
+import { safeJson } from "../runtime-src/k6/http.js";
+
+export const expect = {
+  condition: expectCondition,
+  error: {
+    message: expectErrorMessage,
+    shape: expectErrorShape,
+  },
+  json: expectJson,
+  jsonPath: expectJsonPath,
+  notStatus: expectNotStatus,
+  response: expectResponse,
+  status: expectStatus,
+  statusOneOf: expectStatusOneOf,
+  value: expectValue,
+};
+
+export const parse = {
+  cookie: extractCookie,
+  json: parseJsonBody,
+  safeJson,
+  sse: parseSseEvents,
+  sseEvent: getSseEventData,
+};
+
+export const checks = {
+  authGate: runAuthGateChecks,
+  pagination: runPaginationChecks,
+};
+
+export const network = {
+  deterministicIp: deriveDeterministicIp,
+};
+
 export function getTestkitContext() {
   return readTestkitContext(__ENV);
 }

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

@@ -1,4 +1,8 @@
-import { evaluateCheck, recordFailureDetail } from "./checks.js";
+import { check, evaluateCheck, recordFailureDetail } from "./checks.js";
+import {
+  extractErrorMessageFromBody,
+  hasStandardErrorShape,
+} from "../shared/error-body.mjs";
 import { safeJson, summarizeHttpTrace, toBodyPreview } from "./http.js";
 
 export function expectStatus(response, expected, label = null) {
@@ -122,6 +126,32 @@ export function expectJsonPath(response, path, predicate, label = null) {
   );
 }
 
+export function expectErrorShape(response, label = "response has standard error shape") {
+  return expectJson(response, hasStandardErrorShape, label);
+}
+
+export function expectErrorMessage(response, label = "response includes extractable error message") {
+  return expectJson(response, (body) => extractErrorMessageFromBody(body) !== null, label);
+}
+
+export function expectResponse(response, predicate, label) {
+  return check(response, {
+    [normalizeLabel(label, "response matches expectation")]: predicate,
+  });
+}
+
+export function expectValue(value, predicate, label) {
+  return check(value, {
+    [normalizeLabel(label, "value matches expectation")]: predicate,
+  });
+}
+
+export function expectCondition(predicate, label) {
+  return check(null, {
+    [normalizeLabel(label, "condition holds")]: () => Boolean(predicate()),
+  });
+}
+
 function buildHttpAssertionDetail({ kind, title, trace, expected, actual, response, message }) {
   return {
     kind,

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

@@ -0,0 +1,120 @@
+import { group } from "./checks.js";
+import {
+  expectErrorShape,
+  expectNotStatus,
+  expectResponse,
+  expectStatus,
+  expectStatusOneOf,
+} from "./http-assertions.js";
+
+const DEFAULT_PAGINATION_CASES = [
+  { qs: "limit=0", label: "limit=0", expect400: false },
+  { qs: "limit=-1", label: "limit=-1", expect400: true },
+  { qs: "limit=999999", label: "limit=999999", expect400: false },
+  { qs: "limit=abc", label: "limit=abc", expect400: true },
+  { qs: "offset=-1", label: "offset=-1", expect400: true },
+  { qs: "offset=1.5", label: "offset=1.5", expect400: true },
+];
+
+const AUDIT_LOGS_PAGINATION_CASES = [
+  { qs: "limit=1e3", label: "limit=1e3 (scientific notation)" },
+  { qs: "limit=Infinity", label: "limit=Infinity" },
+  { qs: "limit=NaN", label: "limit=NaN" },
+  { qs: "offset=NaN", label: "offset=NaN" },
+  { qs: "limit=", label: "limit= (empty)" },
+  { qs: "offset=", label: "offset= (empty)" },
+  { qs: "limit=0x10", label: "limit=0x10 (hex)" },
+];
+
+export function runAuthGateChecks(rawReq, scope, descriptors = {}) {
+  const {
+    get = [],
+    post = [],
+    patch = [],
+    delete: deleteCases = [],
+    put = [],
+    validateGetErrorShape = false,
+  } = descriptors;
+
+  runMethodAuthGateChecks(rawReq, scope, "GET", get, validateGetErrorShape);
+  runMethodAuthGateChecks(rawReq, scope, "POST", post);
+  runMethodAuthGateChecks(rawReq, scope, "PATCH", patch);
+  runMethodAuthGateChecks(rawReq, scope, "DELETE", deleteCases);
+  runMethodAuthGateChecks(rawReq, scope, "PUT", put);
+}
+
+export function runPaginationChecks(req, endpoint, options = {}) {
+  group(`${endpoint} — pagination abuse`, () => {
+    for (const { qs, label, expect400 } of DEFAULT_PAGINATION_CASES) {
+      const url = `${endpoint}?${qs}`;
+      const response = req.get(url);
+
+      expectNotStatus(response, 500, `${label} → not 500`);
+      if (response.status === 500) {
+        expectResponse(response, () => true, `BUG: ${endpoint} crashes on ${label}`);
+      }
+
+      if (expect400) {
+        expectStatus(response, 400, `${label} → 400`);
+        if (response.status === 200) {
+          expectResponse(response, () => true, `BUG: ${endpoint} accepts ${label}`);
+        }
+      }
+
+      if (label === "limit=abc" && response.body) {
+        expectResponse(response, (value) => !value.body.includes("NaN"), `${label} → no NaN in response`);
+      }
+    }
+
+    if (!options.auditLogsExtra) {
+      return;
+    }
+
+    for (const { qs, label } of AUDIT_LOGS_PAGINATION_CASES) {
+      const url = `${endpoint}?${qs}`;
+      const response = req.get(url);
+
+      expectNotStatus(response, 500, `audit-logs ${label} → not 500`);
+      if (response.status === 500) {
+        expectResponse(response, () => true, `BUG: audit-logs crashes on ${label}`);
+      }
+
+      expectStatusOneOf(response, [400, 200], `audit-logs ${label} → 400 (not silently accepted)`);
+      if (response.status === 200 && response.body) {
+        expectResponse(response, (value) => !value.body.includes("NaN"), `audit-logs ${label} → no NaN in response`);
+      }
+    }
+  });
+}
+
+function runMethodAuthGateChecks(rawReq, scope, method, cases, validateErrorShape = false) {
+  if (!Array.isArray(cases) || cases.length === 0) {
+    return;
+  }
+
+  group(`${scope} ${method} endpoints return 401 without auth`, () => {
+    for (const entry of cases) {
+      const { path, body } = normalizeRequestCase(entry);
+      const response = rawReq(method, path, body);
+
+      expectStatus(response, 401, `${method} ${path} → 401`);
+      if (validateErrorShape && method === "GET" && response.status === 401) {
+        expectErrorShape(response, `${method} ${path} error shape`);
+      }
+    }
+  });
+}
+
+function normalizeRequestCase(entry) {
+  if (Array.isArray(entry)) {
+    return {
+      path: entry[0],
+      body: entry[1],
+    };
+  }
+
+  return {
+    path: entry,
+    body: undefined,
+  };
+}

package/lib/runtime-src/k6/http-checks.test.mjs

@@ -0,0 +1,120 @@
+import { beforeEach, describe, expect, it, vi } from "vitest";
+
+const mockCheck = vi.fn((value, checks) =>
+  Object.values(checks).every((predicate) => predicate(value))
+);
+const mockGroup = vi.fn((name, fn) => fn());
+
+vi.mock("k6", () => ({
+  check: mockCheck,
+  group: mockGroup,
+}));
+
+vi.mock("k6/http", () => ({
+  default: {
+    del: vi.fn(),
+    file: vi.fn(),
+    get: vi.fn(),
+    patch: vi.fn(),
+    post: vi.fn(),
+    put: vi.fn(),
+  },
+}));
+
+vi.mock("k6/metrics", () => ({
+  Rate: class {
+    add() {}
+  },
+}));
+
+const { runAuthGateChecks, runPaginationChecks } = await import("./http-checks.js");
+
+function makeJsonResponse(status, body) {
+  return {
+    status,
+    body: JSON.stringify(body),
+    headers: { "content-type": "application/json" },
+  };
+}
+
+describe("runtime http checks", () => {
+  beforeEach(() => {
+    mockCheck.mockClear();
+    mockGroup.mockClear();
+  });
+
+  it("executes auth-gate checks across configured methods", () => {
+    const rawReq = vi.fn((method, path, body) => {
+      return makeJsonResponse(401, {
+        error: {
+          code: "UNAUTHORIZED",
+          message: `${method} ${path} requires auth`,
+        },
+        body,
+      });
+    });
+
+    runAuthGateChecks(rawReq, "sessions", {
+      get: ["/api/v1/sessions"],
+      post: [["/api/v1/sessions", { name: "draft" }]],
+      validateGetErrorShape: true,
+    });
+
+    expect(rawReq.mock.calls).toEqual([
+      ["GET", "/api/v1/sessions", undefined],
+      ["POST", "/api/v1/sessions", { name: "draft" }],
+    ]);
+    expect(mockGroup).toHaveBeenCalledWith(
+      "sessions GET endpoints return 401 without auth",
+      expect.any(Function)
+    );
+    expect(mockGroup).toHaveBeenCalledWith(
+      "sessions POST endpoints return 401 without auth",
+      expect.any(Function)
+    );
+  });
+
+  it("executes default and audit-log pagination abuse cases", () => {
+    const requested = [];
+    const req = {
+      get: vi.fn((url) => {
+        requested.push(url);
+        const expects400 =
+          url.includes("limit=-1") ||
+          url.includes("limit=abc") ||
+          url.includes("offset=-1") ||
+          url.includes("offset=1.5") ||
+          url.includes("limit=Infinity") ||
+          url.includes("limit=NaN") ||
+          url.includes("offset=NaN") ||
+          url.endsWith("limit=") ||
+          url.endsWith("offset=");
+
+        if (expects400) {
+          return makeJsonResponse(400, {
+            error: {
+              code: "VALIDATION_ERROR",
+              message: "invalid pagination",
+            },
+          });
+        }
+
+        return makeJsonResponse(200, {
+          data: [],
+          pagination: {
+            limit: 25,
+            offset: 0,
+          },
+        });
+      }),
+    };
+
+    runPaginationChecks(req, "/api/v1/audit-logs", { auditLogsExtra: true });
+
+    expect(requested).toHaveLength(13);
+    expect(requested).toContain("/api/v1/audit-logs?limit=-1");
+    expect(requested).toContain("/api/v1/audit-logs?offset=1.5");
+    expect(requested).toContain("/api/v1/audit-logs?limit=Infinity");
+    expect(requested).toContain("/api/v1/audit-logs?limit=0x10");
+  });
+});