@elench/testkit 0.1.55 → 0.1.56

package/README.md

@@ -341,6 +341,27 @@ const suite = defineDalSuite(({ db }) => {
 export default suite;
 ```
 
+Scenario suites:
+
+```ts
+import { defineScenarioSuite } from "@elench/testkit";
+
+const suite = defineScenarioSuite(({ rawReq, scenario }) => {
+  const plan = scenario.choose("journey", {
+    endpoint: scenario.pick("endpoint", ["/health", "/message"]),
+    includeHealthCheck: scenario.maybe("includeHealthCheck", 1),
+  });
+
+  const selected = scenario.resource("selected-endpoint", () => rawReq("GET", plan.endpoint));
+
+  scenario.step("fetch selected endpoint", () => {
+    selected.get();
+  });
+});
+
+export default suite;
+```
+
 Low-level runtime primitives remain available:
 
 ```ts
@@ -375,6 +396,7 @@ Example layouts:
 
 - `*.int.testkit.ts`
 - `*.e2e.testkit.ts`
+- `*.scenario.testkit.ts`
 - `*.dal.testkit.ts`
 - `*.load.testkit.ts`
 - `*.pw.testkit.ts`

package/lib/bundler/index.mjs

@@ -132,7 +132,7 @@ function normalizeTestkitSuite(module) {
   const candidate = module?.default;
   if (!candidate || typeof candidate !== "object") {
     throw new Error(
-      "testkit suite files must default-export the suite object returned by defineHttpSuite(...) or defineDalSuite(...). Example: export default defineHttpSuite(...) or const suite = defineHttpSuite(...); export default suite;"
+      "testkit suite files must default-export the suite object returned by defineHttpSuite(...), defineScenarioSuite(...), or defineDalSuite(...). Example: export default defineHttpSuite(...) or const suite = defineScenarioSuite(...); export default suite;"
     );
   }
   if (typeof candidate.exec !== "function") {

package/lib/bundler/index.test.mjs

@@ -75,6 +75,35 @@ describe("runtime bundler", () => {
     expect(bundled).toContain('import sql from "k6/x/sql"');
   });
 
+  it("bundles scenario execution through the public package surface", async () => {
+    const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), "testkit-bundle-"));
+    cleanups.push(() => fs.rmSync(tmpDir, { force: true, recursive: true }));
+
+    const sourceFile = path.join(tmpDir, "scenario.js");
+    fs.writeFileSync(
+      sourceFile,
+      [
+        'import { defineScenarioSuite } from "@elench/testkit";',
+        "const suite = defineScenarioSuite(({ scenario }) => {",
+        "  const plan = scenario.choose('journey', { endpoint: scenario.pick('endpoint', ['/a', '/b']) });",
+        "  scenario.step('record choice', () => plan.endpoint);",
+        "});",
+        "export default suite;",
+        "",
+      ].join("\n")
+    );
+
+    const bundledFile = await bundleK6File({
+      productDir: tmpDir,
+      serviceName: "api",
+      sourceFile,
+    });
+
+    const bundled = fs.readFileSync(bundledFile, "utf8");
+    expect(bundled).toContain("defineScenarioSuite");
+    expect(bundled).toContain("createScenarioRuntime");
+  });
+
   it("normalizes a default-exported suite object with no setup override", async () => {
     const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), "testkit-bundle-"));
     cleanups.push(() => fs.rmSync(tmpDir, { force: true, recursive: true }));

package/lib/cli/args.mjs

@@ -5,7 +5,7 @@ import {
   parseWorkersOption,
 } from "../runner/execution-config.mjs";
 
-export const POSITIONAL_TYPES = new Set(["int", "e2e", "dal", "load", "pw", "all"]);
+export const POSITIONAL_TYPES = new Set(["int", "e2e", "scenario", "dal", "load", "pw", "all"]);
 export const LIFECYCLE = new Set(["status", "destroy", "cleanup"]);
 export const KNOWN_FAILURES_ACTIONS = new Set(["render", "validate"]);
 export const RESERVED = new Set([...POSITIONAL_TYPES, ...LIFECYCLE]);
@@ -45,7 +45,7 @@ export function resolveCliSelection({ first, second, third }) {
   } else if (first) {
     throw new Error(
       `Unknown argument "${first}". Expected a lifecycle command (status, destroy, cleanup) ` +
-      `or suite type (int, e2e, dal, load, pw, all).`
+      `or suite type (int, e2e, scenario, dal, load, pw, all).`
     );
   }
 

package/lib/cli/args.test.mjs

@@ -79,11 +79,17 @@ describe("cli-args", () => {
   });
 
   it("parses types and suite selectors", () => {
-    expect(parseTypeOption(["e2e,dal"], "int")).toEqual(["int", "e2e", "dal"]);
+    expect(parseTypeOption(["e2e,scenario,dal"], "int")).toEqual([
+      "int",
+      "e2e",
+      "scenario",
+      "dal",
+    ]);
     expect(() => parseTypeOption(["all", "int"])).toThrow("cannot be combined");
 
-    expect(parseSuiteOption(["auth,dal:queries"])).toEqual([
+    expect(parseSuiteOption(["auth,scenario:journeys,dal:queries"])).toEqual([
       { kind: "plain", name: "auth", raw: "auth" },
+      { kind: "typed", type: "scenario", name: "journeys", raw: "scenario:journeys" },
       { kind: "typed", type: "dal", name: "queries", raw: "dal:queries" },
     ]);
   });

package/lib/cli/command-helpers.mjs

@@ -26,7 +26,7 @@ export const runFlags = {
   type: Flags.string({
     char: "t",
     multiple: true,
-    description: "Run specific suite type(s): int, e2e, dal, load, pw, all",
+    description: "Run specific suite type(s): int, e2e, scenario, dal, load, pw, all",
   }),
   suite: Flags.string({
     char: "s",
@@ -47,6 +47,9 @@ export const runFlags = {
   shard: Flags.string({
     description: "Run only shard i of n at suite granularity",
   }),
+  seed: Flags.string({
+    description: "Deterministic seed for scenario suites",
+  }),
   "write-status": Flags.boolean({
     description: "Write a deterministic testkit.status.json snapshot",
     default: false,
@@ -111,6 +114,7 @@ export async function executeRunCommand(command, flags, positionalType = null) {
       workers,
       fileTimeoutSeconds,
       shard,
+      scenarioSeed: flags.seed || null,
       serviceFilter: flags.service || null,
       reporter,
       writeStatus: flags["write-status"],

package/lib/cli/commands/run.mjs

@@ -8,9 +8,9 @@ export default class RunCommand extends Command {
 
   static args = {
     type: Args.string({
-      description: "Optional suite type shortcut: int, e2e, dal, load, pw, all",
+      description: "Optional suite type shortcut: int, e2e, scenario, dal, load, pw, all",
       required: false,
-      options: ["int", "e2e", "dal", "load", "pw", "all"],
+      options: ["int", "e2e", "scenario", "dal", "load", "pw", "all"],
     }),
   };
 

package/lib/cli/entrypoint.mjs

@@ -16,7 +16,7 @@ export function normalizeCliArgs(argv) {
     "--version",
     "-v",
   ]);
-  const runTypeShortcuts = new Set(["int", "e2e", "dal", "load", "pw", "all"]);
+  const runTypeShortcuts = new Set(["int", "e2e", "scenario", "dal", "load", "pw", "all"]);
   const valueFlags = new Set([
     "--dir",
     "--service",
@@ -26,6 +26,7 @@ export function normalizeCliArgs(argv) {
     "--workers",
     "--file-timeout-seconds",
     "--shard",
+    "--seed",
     "--input",
     "--output",
     "--status",

package/lib/cli/viewer.mjs

@@ -190,6 +190,9 @@ export function formatArtifactPreview(payload, maxLines = 6) {
   if (payload.kind === "agentic-query") {
     return formatAgenticArtifact(payload, maxLines);
   }
+  if (payload.kind === "testkit.scenario") {
+    return formatScenarioArtifact(payload, maxLines);
+  }
   if (payload.kind === "testkit.http-traces") {
     return formatHttpTraceArtifact(payload, maxLines);
   }
@@ -230,12 +233,39 @@ function formatHttpTraceArtifact(payload, maxLines) {
   return lines;
 }
 
+function formatScenarioArtifact(payload, maxLines) {
+  const artifact = payload.data || {};
+  const lines = [];
+  if (artifact.scenarioName) lines.push(`Scenario: ${artifact.scenarioName}`);
+  if (artifact.seed) lines.push(`Seed: ${artifact.seed}`);
+  const choiceEntries = Object.entries(artifact.choices || {});
+  if (choiceEntries.length > 0) {
+    lines.push(
+      `Choices: ${choiceEntries
+        .map(([key, value]) => `${key}=${formatScenarioChoiceValue(value)}`)
+        .join(", ")}`
+    );
+  }
+  const failedStep = (artifact.steps || []).find((step) => step.status === "failed");
+  if (failedStep) {
+    lines.push(`Failed Step: ${failedStep.name}`);
+  } else if (Array.isArray(artifact.steps) && artifact.steps.length > 0) {
+    lines.push(`Steps: ${artifact.steps.map((step) => step.name).join(" -> ")}`);
+  }
+  return lines.slice(0, maxLines);
+}
+
 function rankFailureDetails(details) {
   return [...(Array.isArray(details) ? details : [])].sort((left, right) => {
     return failureDetailRank(left) - failureDetailRank(right) || String(left?.key || "").localeCompare(String(right?.key || ""));
   });
 }
 
+function formatScenarioChoiceValue(value) {
+  if (typeof value === "string") return value;
+  return JSON.stringify(value);
+}
+
 function failureDetailRank(detail) {
   if (detail?.kind === "http-assertion") return 1;
   if (detail?.request && detail?.response) return 2;

package/lib/config/discovery.mjs

@@ -5,6 +5,7 @@ const TESTKIT_DIRNAME = "__testkit__";
 const DISCOVERY_RULES = [
   { suffix: ".int.testkit.ts", type: "integration", framework: "k6" },
   { suffix: ".e2e.testkit.ts", type: "e2e", framework: "k6" },
+  { suffix: ".scenario.testkit.ts", type: "scenario", framework: "k6" },
   { suffix: ".dal.testkit.ts", type: "dal", framework: "k6" },
   { suffix: ".load.testkit.ts", type: "load", framework: "k6" },
   { suffix: ".pw.testkit.ts", type: "e2e", framework: "playwright" },

package/lib/config/discovery.test.mjs

@@ -19,6 +19,7 @@ describe("filesystem-discovery", () => {
 
     writeFile(productDir, "src/api/routes/__testkit__/auth/me.int.testkit.ts");
     writeFile(productDir, "src/api/routes/__testkit__/health/ready.int.testkit.ts");
+    writeFile(productDir, "src/api/routes/__testkit__/journeys/smoke.scenario.testkit.ts");
     writeFile(productDir, "frontend/app/__testkit__/homepage/homepage.pw.testkit.ts");
 
     const suites = discoverSuites(productDir, {
@@ -46,6 +47,13 @@ describe("filesystem-discovery", () => {
         framework: "k6",
       },
     ]);
+    expect(suites.api.scenario).toEqual([
+      {
+        name: "journeys",
+        files: ["src/api/routes/__testkit__/journeys/smoke.scenario.testkit.ts"],
+        framework: "k6",
+      },
+    ]);
     expect(suites.frontend.e2e).toEqual([
       {
         name: "homepage",

package/lib/index.d.ts

@@ -38,6 +38,55 @@ export interface HttpSuiteContext<TSetup = unknown> {
   session: TSetup | null;
 }
 
+export interface ScenarioStepResult {
+  name: string;
+  status: "passed" | "failed";
+  startedAt?: string;
+  finishedAt?: string;
+  durationMs?: number;
+  failureCount?: number;
+  error?: string;
+}
+
+export interface ScenarioResource<TValue = unknown> {
+  get(): TValue;
+}
+
+export interface ScenarioRuntime {
+  readonly seed: string;
+  readonly scenarioName: string | null;
+  choose<TChoice extends unknown[]>(
+    name: string,
+    choices: TChoice
+  ): TChoice[number];
+  choose<TShape extends Record<string, unknown>>(
+    name: string,
+    shape: TShape
+  ): TShape;
+  maybe(name: string, probability?: number): boolean;
+  note<TValue = unknown>(name: string, value: TValue): TValue;
+  pick<TChoice extends unknown[]>(name: string, choices: TChoice): TChoice[number];
+  resource<TValue = unknown>(
+    name: string,
+    factory: () => TValue,
+    options?: { scope?: "file" | "scenario" | "step" }
+  ): ScenarioResource<TValue>;
+  step<TValue = unknown>(name: string, fn: () => TValue): TValue;
+  snapshot(): {
+    schemaVersion: number;
+    seed: string;
+    scenarioName: string | null;
+    choices: Record<string, unknown>;
+    notes: Record<string, unknown>;
+    resources: Array<{ name: string; scope: "file" | "scenario" | "step" }>;
+    steps: ScenarioStepResult[];
+  };
+}
+
+export interface ScenarioSuiteContext<TSetup = unknown> extends HttpSuiteContext<TSetup> {
+  scenario: ScenarioRuntime;
+}
+
 export interface HttpSuiteConfig<TSetup = unknown> {
   auth?: AuthAdapter<TSetup> | null;
   env?: RuntimeEnv;
@@ -68,6 +117,15 @@ export declare function defineHttpSuite<TSetup = unknown>(
   run: (context: HttpSuiteContext<TSetup>) => unknown
 ): TestkitSuite<TSetup>;
 
+export declare function defineScenarioSuite<TSetup = unknown>(
+  run: (context: ScenarioSuiteContext<TSetup>) => unknown
+): TestkitSuite<TSetup>;
+
+export declare function defineScenarioSuite<TSetup = unknown>(
+  config: HttpSuiteConfig<TSetup>,
+  run: (context: ScenarioSuiteContext<TSetup>) => unknown
+): TestkitSuite<TSetup>;
+
 export declare function defineDalSuite<TSetup = unknown>(
   run: (context: DalSuiteContext<TSetup>) => unknown
 ): TestkitSuite<TSetup>;

package/lib/index.mjs

@@ -4,6 +4,9 @@ export {
 export {
   defineHttpSuite,
 } from "./runtime-src/k6/suite.js";
+export {
+  defineScenarioSuite,
+} from "./runtime-src/k6/scenario-suite.js";
 
 export function createAuthAdapter({ setup, headers } = {}) {
   return {

package/lib/runner/default-runtime-runner.mjs

@@ -95,7 +95,10 @@ export async function runDefaultRuntimeTask(
       env: buildTaskExecutionEnv(
         targetConfig,
         lease,
-        buildFileTimeoutEnv(fileTimeoutSeconds, startedAt),
+        {
+          ...buildFileTimeoutEnv(fileTimeoutSeconds, startedAt),
+          ...(task.scenarioSeed ? { TESTKIT_SCENARIO_SEED: task.scenarioSeed } : {}),
+        },
         process.env
       ),
       reject: false,

package/lib/runner/orchestrator.mjs

@@ -146,6 +146,7 @@ export async function runAll(configs, typeValues, suiteSelectors, opts, allConfi
         fileNames: requestedFiles,
         shard: opts.shard || null,
         serviceFilter: opts.serviceFilter || null,
+        scenarioSeed: opts.scenarioSeed || null,
         metadata,
         summarizeDbBackend,
         serviceLogs: logRegistry.listServiceLogs(),
@@ -173,6 +174,9 @@ export async function runAll(configs, typeValues, suiteSelectors, opts, allConfi
       const timings = loadTimings(productDir);
       const graphs = buildRuntimeGraphs(executedPlans);
       const queue = buildTaskQueue(executedPlans, graphs, timings);
+      for (const task of queue) {
+        task.scenarioSeed = opts.scenarioSeed || null;
+      }
       workerCount = Math.max(1, Math.min(execution.workers, queue.length));
       runtimeInstanceCount = graphs.reduce((sum, graph) => sum + graph.instanceCount, 0);
       const workers = Array.from({ length: workerCount }, (_unused, index) =>
@@ -247,10 +251,11 @@ export async function runAll(configs, typeValues, suiteSelectors, opts, allConfi
       runtimeStats,
       typeValues,
       suiteSelectors,
-      fileNames: requestedFiles,
-      shard: opts.shard || null,
-      serviceFilter: opts.serviceFilter || null,
-      metadata,
+            fileNames: requestedFiles,
+            shard: opts.shard || null,
+            serviceFilter: opts.serviceFilter || null,
+            scenarioSeed: opts.scenarioSeed || null,
+            metadata,
       summarizeDbBackend,
       serviceLogs: logRegistry.listServiceLogs(),
       setupLogs: logRegistry.listSetupLogs(),
@@ -262,10 +267,11 @@ export async function runAll(configs, typeValues, suiteSelectors, opts, allConfi
           results,
           typeValues,
           suiteSelectors,
-          fileNames: requestedFiles,
-          shard: opts.shard || null,
-          serviceFilter: opts.serviceFilter || null,
-          metadata,
+      fileNames: requestedFiles,
+      shard: opts.shard || null,
+      serviceFilter: opts.serviceFilter || null,
+      scenarioSeed: opts.scenarioSeed || null,
+      metadata,
         })
       : null;
     const enrichedArtifacts = applyKnownFailuresToArtifacts(

package/lib/runner/planning.mjs

@@ -5,7 +5,7 @@ import {
   suiteSelectionType,
 } from "./suite-selection.mjs";
 
-const TYPE_ORDER = ["dal", "integration", "e2e", "load"];
+const TYPE_ORDER = ["dal", "integration", "e2e", "scenario", "load"];
 
 export function taskNeedsLocalRuntime(task) {
   return task.type !== "dal";

package/lib/runner/reporting.mjs

@@ -8,6 +8,7 @@ export function buildStatusArtifact({
   fileNames,
   shard,
   serviceFilter,
+  scenarioSeed,
   metadata,
 }) {
   const executedResults = results.filter((result) => !result.skipped);
@@ -68,6 +69,7 @@ export function buildStatusArtifact({
     fileNames: [...(fileNames || [])].sort(),
     shard: shard || null,
     serviceFilter: serviceFilter || null,
+    scenarioSeed: scenarioSeed || null,
   };
   scope.isFullRun =
     scope.types.length === 1 &&
@@ -109,6 +111,7 @@ export function buildRunArtifact({
   fileNames,
   shard,
   serviceFilter,
+  scenarioSeed,
   metadata,
   summarizeDbBackend,
   serviceLogs = [],
@@ -156,6 +159,7 @@ export function buildRunArtifact({
       fileNames,
       shard,
       serviceFilter,
+      scenarioSeed: scenarioSeed || null,
       testkitVersion: metadata.testkitVersion,
     },
     summary: {
@@ -224,6 +228,7 @@ export function buildLiveRunArtifact({
   fileNames,
   shard,
   serviceFilter,
+  scenarioSeed,
   metadata,
   summarizeDbBackend,
   serviceLogs = [],
@@ -244,6 +249,7 @@ export function buildLiveRunArtifact({
     fileNames,
     shard,
     serviceFilter,
+    scenarioSeed,
     metadata,
     summarizeDbBackend,
     serviceLogs,

package/lib/runner/reporting.test.mjs

@@ -62,6 +62,7 @@ describe("runner reporting", () => {
       fileNames: [],
       shard: null,
       serviceFilter: null,
+      scenarioSeed: "demo-seed",
       metadata: {
         git: {
           branch: "main",
@@ -84,6 +85,7 @@ describe("runner reporting", () => {
       fileTimeoutSeconds: 60,
       workerCount: 1,
       runtimeInstanceCount: 2,
+      scenarioSeed: "demo-seed",
     });
     expect(artifact.summary.services).toEqual({
       total: 1,
@@ -220,6 +222,7 @@ describe("runner reporting", () => {
       fileNames: ["tests/api/integration/b.int.testkit.ts"],
       shard: null,
       serviceFilter: "api",
+      scenarioSeed: "demo-seed",
       metadata: {
         git: {
           branch: "main",
@@ -247,6 +250,7 @@ describe("runner reporting", () => {
         fileNames: ["tests/api/integration/b.int.testkit.ts"],
         shard: null,
         serviceFilter: "api",
+        scenarioSeed: "demo-seed",
         isFullRun: false,
       },
       summary: {
@@ -291,6 +295,7 @@ describe("runner reporting", () => {
       fileNames: [],
       shard: null,
       serviceFilter: null,
+      scenarioSeed: null,
       metadata: {
         git: {
           branch: "main",

package/lib/runner/suite-selection.mjs

@@ -1,4 +1,4 @@
-const USER_TYPES = new Set(["int", "e2e", "dal", "load", "pw", "all"]);
+const USER_TYPES = new Set(["int", "e2e", "scenario", "dal", "load", "pw", "all"]);
 
 export function normalizeTypeValues(values = []) {
   const expanded = [];
@@ -9,7 +9,7 @@ export function normalizeTypeValues(values = []) {
       if (!value) continue;
       if (!USER_TYPES.has(value)) {
         throw new Error(
-          `Unknown type "${value}". Expected one of: int, e2e, dal, load, pw, all.`
+          `Unknown type "${value}". Expected one of: int, e2e, scenario, dal, load, pw, all.`
         );
       }
       expanded.push(value);
@@ -25,7 +25,7 @@ export function normalizeTypeValues(values = []) {
     throw new Error(`"--type all" cannot be combined with other types.`);
   }
 
-  const order = ["int", "e2e", "dal", "load", "pw", "all"];
+  const order = ["int", "e2e", "scenario", "dal", "load", "pw", "all"];
   return deduped.sort((left, right) => order.indexOf(left) - order.indexOf(right));
 }
 
@@ -52,7 +52,7 @@ export function parseSuiteSelectors(values = []) {
       const name = typeMatch[2].trim();
       if (!USER_TYPES.has(type) || type === "all") {
         throw new Error(
-          `Unknown suite selector type "${type}". Expected one of: int, e2e, dal, load, pw.`
+          `Unknown suite selector type "${type}". Expected one of: int, e2e, scenario, dal, load, pw.`
         );
       }
       if (!name) {

package/lib/runner/suite-selection.test.mjs

@@ -11,14 +11,20 @@ import {
 describe("runner suite selection", () => {
   it("normalizes selected type values", () => {
     expect(normalizeTypeValues([])).toEqual(["all"]);
-    expect(normalizeTypeValues(["int,e2e", "dal"])).toEqual(["int", "e2e", "dal"]);
+    expect(normalizeTypeValues(["int,e2e,scenario", "dal"])).toEqual([
+      "int",
+      "e2e",
+      "scenario",
+      "dal",
+    ]);
     expect(() => normalizeTypeValues(["all", "int"])).toThrow("cannot be combined");
     expect(() => normalizeTypeValues(["jest"])).toThrow("Unknown type");
   });
 
   it("parses suite selectors", () => {
-    expect(parseSuiteSelectors(["auth,dal:queries"])).toEqual([
+    expect(parseSuiteSelectors(["auth,scenario:journeys,dal:queries"])).toEqual([
       { kind: "plain", name: "auth", raw: "auth" },
+      { kind: "typed", type: "scenario", name: "journeys", raw: "scenario:journeys" },
       { kind: "typed", type: "dal", name: "queries", raw: "dal:queries" },
     ]);
     expect(() => parseSuiteSelectors(["all:auth"])).toThrow("Unknown suite selector type");
@@ -36,6 +42,7 @@ describe("runner suite selection", () => {
 
   it("maps discovered suites to user-facing selection types", () => {
     expect(suiteSelectionType("integration", "k6")).toBe("int");
+    expect(suiteSelectionType("scenario", "k6")).toBe("scenario");
     expect(suiteSelectionType("e2e", "playwright")).toBe("pw");
     expect(suiteSelectionType("dal", "k6")).toBe("dal");
   });

package/lib/runner/worker-loop.mjs

@@ -2,7 +2,7 @@ import { formatError } from "./formatting.mjs";
 import { runDalTask, runHttpK6Task } from "./default-runtime-runner.mjs";
 import { runPlaywrightTask } from "./playwright-runner.mjs";
 
-const HTTP_K6_TYPES = new Set(["integration", "e2e", "load"]);
+const HTTP_K6_TYPES = new Set(["integration", "e2e", "scenario", "load"]);
 
 export function createWorker(workerId, productDir) {
   return {

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

@@ -136,6 +136,15 @@ export function recordFailureDetail(detail) {
   existing.count += normalized.count;
 }
 
+export function getFailureCollectionSnapshot() {
+  return {
+    phase: failureState.phase,
+    groupStack: [...failureState.groupStack],
+    failureCount: failureState.detailsByKey.size,
+    keys: [...failureState.detailsByKey.keys()].sort(),
+  };
+}
+
 function createFailureState() {
   return {
     phase: "exec",

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

@@ -0,0 +1,234 @@
+import { emitArtifact } from "./artifacts.js";
+import { getFailureCollectionSnapshot, group } from "./checks.js";
+
+const DEFAULT_SCENARIO_SEED = "default";
+
+export function createScenarioRuntime(options = {}) {
+  const suiteSeed = normalizeSeed(options.seed);
+  const state = {
+    seed: suiteSeed,
+    scenarioName: null,
+    choices: {},
+    notes: {},
+    resources: [],
+    resourceState: new Map(),
+    steps: [],
+  };
+
+  return {
+    get seed() {
+      return state.seed;
+    },
+    get scenarioName() {
+      return state.scenarioName;
+    },
+    resource(name, factory, options = {}) {
+      return createScenarioResource(state, name, factory, options);
+    },
+    pick(name, choices) {
+      return pickChoice(state, name, choices);
+    },
+    maybe(name, probability = 0.5) {
+      return maybeChoice(state, name, probability);
+    },
+    choose(name, shapeOrChoices) {
+      return chooseScenario(state, name, shapeOrChoices);
+    },
+    note(name, value) {
+      const normalizedName = normalizeLabel(name, "note");
+      state.notes[normalizedName] = cloneForArtifact(value);
+      return value;
+    },
+    step(name, fn) {
+      return runScenarioStep(state, name, fn);
+    },
+    emitArtifact() {
+      emitScenarioArtifact(state);
+    },
+    snapshot() {
+      return buildScenarioArtifactPayload(state);
+    },
+  };
+}
+
+function createScenarioResource(state, name, factory, options = {}) {
+  const normalizedName = normalizeLabel(name, "resource");
+  if (typeof factory !== "function") {
+    throw new Error(`scenario.resource("${normalizedName}") requires a factory function`);
+  }
+
+  const scope = normalizeResourceScope(options.scope);
+  if (!state.resources.some((entry) => entry.name === normalizedName)) {
+    state.resources.push({ name: normalizedName, scope });
+  }
+
+  return {
+    get() {
+      if (scope === "step") {
+        return factory();
+      }
+
+      if (state.resourceState.has(normalizedName)) {
+        return state.resourceState.get(normalizedName);
+      }
+
+      const value = factory();
+      state.resourceState.set(normalizedName, value);
+      return value;
+    },
+  };
+}
+
+function pickChoice(state, name, choices) {
+  const normalizedName = normalizeLabel(name, "choice");
+  const values = Array.isArray(choices) ? choices : [];
+  if (values.length === 0) {
+    throw new Error(`scenario.pick("${normalizedName}") requires at least one choice`);
+  }
+
+  const index = chooseIndex(state.seed, state.scenarioName || "scenario", normalizedName, values.length);
+  const value = values[index];
+  state.choices[normalizedName] = cloneForArtifact(value);
+  return value;
+}
+
+function maybeChoice(state, name, probability = 0.5) {
+  const normalizedName = normalizeLabel(name, "choice");
+  const numericProbability = Number(probability);
+  if (!Number.isFinite(numericProbability) || numericProbability < 0 || numericProbability > 1) {
+    throw new Error(
+      `scenario.maybe("${normalizedName}") probability must be between 0 and 1`
+    );
+  }
+
+  const ratio = chooseRatio(state.seed, state.scenarioName || "scenario", normalizedName);
+  const value = ratio < numericProbability;
+  state.choices[normalizedName] = value;
+  return value;
+}
+
+function chooseScenario(state, name, shapeOrChoices) {
+  const normalizedName = normalizeLabel(name, "scenario");
+  state.scenarioName = normalizedName;
+
+  if (Array.isArray(shapeOrChoices)) {
+    const selected = pickChoice(state, `${normalizedName}:variant`, shapeOrChoices);
+    return selected;
+  }
+
+  if (!shapeOrChoices || typeof shapeOrChoices !== "object") {
+    throw new Error(`scenario.choose("${normalizedName}") requires an object or array`);
+  }
+
+  return shapeOrChoices;
+}
+
+function runScenarioStep(state, name, fn) {
+  const stepName = normalizeLabel(name, "unnamed step");
+  if (typeof fn !== "function") {
+    throw new Error(`scenario.step("${stepName}") requires a function`);
+  }
+
+  const entry = {
+    name: stepName,
+    startedAt: new Date().toISOString(),
+    durationMs: 0,
+    status: "passed",
+  };
+  state.steps.push(entry);
+
+  const startedAt = Date.now();
+  const before = getFailureCollectionSnapshot();
+
+  try {
+    return group(stepName, () => fn());
+  } catch (error) {
+    entry.status = "failed";
+    entry.error = error instanceof Error ? error.message : String(error);
+    throw error;
+  } finally {
+    const after = getFailureCollectionSnapshot();
+    entry.durationMs = Date.now() - startedAt;
+    entry.finishedAt = new Date().toISOString();
+    if (entry.status !== "failed" && after.failureCount > before.failureCount) {
+      entry.status = "failed";
+      entry.failureCount = after.failureCount - before.failureCount;
+    } else if (after.failureCount > before.failureCount) {
+      entry.failureCount = after.failureCount - before.failureCount;
+    }
+  }
+}
+
+function emitScenarioArtifact(state) {
+  const payload = buildScenarioArtifactPayload(state);
+  emitArtifact("scenario", payload, {
+    kind: "testkit.scenario",
+    summary: buildScenarioSummary(payload),
+  });
+}
+
+function buildScenarioArtifactPayload(state) {
+  return {
+    schemaVersion: 1,
+    seed: state.seed,
+    scenarioName: state.scenarioName,
+    choices: cloneForArtifact(state.choices),
+    notes: cloneForArtifact(state.notes),
+    resources: state.resources.map((entry) => ({ ...entry })),
+    steps: state.steps.map((entry) => ({ ...entry })),
+  };
+}
+
+function buildScenarioSummary(payload) {
+  const failedStep = payload.steps.find((entry) => entry.status === "failed");
+  if (failedStep) {
+    return `${payload.scenarioName || "scenario"} seed=${payload.seed} failed at ${failedStep.name}`;
+  }
+  return `${payload.scenarioName || "scenario"} seed=${payload.seed} (${payload.steps.length} steps)`;
+}
+
+function chooseIndex(seed, scenarioName, choiceName, length) {
+  if (length <= 1) return 0;
+  const value = hashString(`${seed}:${scenarioName}:${choiceName}`);
+  return value % length;
+}
+
+function chooseRatio(seed, scenarioName, choiceName) {
+  const value = hashString(`${seed}:${scenarioName}:${choiceName}`);
+  return value / 0xffffffff;
+}
+
+function hashString(input) {
+  let hash = 2166136261;
+  const source = String(input);
+  for (let index = 0; index < source.length; index += 1) {
+    hash ^= source.charCodeAt(index);
+    hash = Math.imul(hash, 16777619);
+  }
+  return hash >>> 0;
+}
+
+function normalizeSeed(value) {
+  if (value === undefined || value === null) return DEFAULT_SCENARIO_SEED;
+  const normalized = String(value).trim();
+  return normalized.length > 0 ? normalized : DEFAULT_SCENARIO_SEED;
+}
+
+function normalizeLabel(value, fallback) {
+  if (typeof value !== "string") return fallback;
+  const normalized = value.trim();
+  return normalized.length > 0 ? normalized : fallback;
+}
+
+function normalizeResourceScope(value) {
+  const normalized = normalizeLabel(value, "scenario");
+  if (normalized === "file") return "file";
+  if (normalized === "scenario") return "scenario";
+  if (normalized === "step") return "step";
+  throw new Error(`Unsupported scenario resource scope "${value}"`);
+}
+
+function cloneForArtifact(value) {
+  if (value === undefined) return null;
+  return JSON.parse(JSON.stringify(value));
+}

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

@@ -0,0 +1,179 @@
+import { fail } from "k6";
+import {
+  defaultOptions,
+  emitFailureCollectionArtifact,
+  recordFailureDetail,
+  recordRuntimeFailure,
+  startFailureCollection,
+} from "./checks.js";
+import {
+  createHttpClient,
+  emitHttpTraceCollectionArtifact,
+  getEnv,
+  startHttpTraceCollection,
+} from "./http.js";
+import {
+  clearRuntimeContext,
+  registerRuntimeContext,
+  resolveHttpProfile,
+} from "../../setup/runtime.mjs";
+import { createScenarioRuntime } from "./scenario-runtime.js";
+
+export function defineScenarioSuite(configOrRun, maybeRun) {
+  const { config, run } = normalizeSuiteArgs(configOrRun, maybeRun);
+
+  return {
+    get options() {
+      return mergeProfileConfig(config).options || defaultOptions;
+    },
+    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);
+      const scenario = createScenarioRuntime({
+        seed: resolved.env.rawEnv.TESTKIT_SCENARIO_SEED,
+      });
+      startFailureCollection("exec");
+      startHttpTraceCollection("exec");
+      try {
+        registerRuntimeContext({ env: resolved.env, http: resolved.client.rawHttp || null });
+        return run({
+          env: resolved.env,
+          req: resolved.client.request,
+          rawReq: resolved.client.raw,
+          getWithHeaders: resolved.client.getWithHeaders,
+          setupData,
+          session: setupData,
+          scenario,
+        });
+      } catch (error) {
+        recordFailureDetail(buildRuntimeExceptionDetail("exec", error));
+        recordRuntimeFailure();
+        fail(formatFatalSuiteError("exec", error));
+      } finally {
+        scenario.emitArtifact();
+        emitFailureCollectionArtifact();
+        emitHttpTraceCollectionArtifact();
+        clearRuntimeContext();
+      }
+    },
+  };
+}
+
+function normalizeSuiteArgs(configOrRun, maybeRun) {
+  if (typeof configOrRun === "function") {
+    return { config: {}, run: configOrRun };
+  }
+  if (typeof maybeRun !== "function") {
+    throw new Error("suite factory requires a run callback");
+  }
+  return { config: configOrRun || {}, run: maybeRun };
+}
+
+function callHeaders(builder, setupData, env) {
+  if (typeof builder !== "function") return {};
+  return builder(setupData, { env }) || {};
+}
+
+function mergeProfileConfig(config) {
+  if (!config?.profile) return config || {};
+
+  const profile = resolveHttpProfile(config.profile) || {};
+  return {
+    ...profile,
+    ...config,
+    auth: config.auth ?? profile.auth ?? null,
+    headers: config.headers ?? profile.headers,
+    rawHeaders: config.rawHeaders ?? profile.rawHeaders,
+    options: config.options ?? profile.options,
+    env: config.env ?? profile.env,
+  };
+}
+
+function resolveRuntimeConfig(config) {
+  const resolvedConfig = mergeProfileConfig(config);
+  const env = {
+    ...(resolvedConfig.env || getEnv()),
+    rawEnv: __ENV,
+  };
+  const auth = resolvedConfig.auth || null;
+  const client = createHttpClient({
+    baseUrl: env.BASE,
+    routeHeaders: env.routeParams,
+    getHeaders(setupData) {
+      return {
+        ...callHeaders(auth?.headers, setupData, env),
+        ...callHeaders(resolvedConfig.headers, setupData, env),
+      };
+    },
+    getRawHeaders(setupData) {
+      return callHeaders(resolvedConfig.rawHeaders, setupData, env);
+    },
+  });
+
+  return {
+    resolvedConfig,
+    env,
+    auth,
+    client,
+  };
+}
+
+function formatFatalSuiteError(phase, error) {
+  if (error instanceof Error) {
+    return `Uncaught testkit suite error during ${phase}: ${error.message}`;
+  }
+  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.55",
+  "version": "0.1.56",
   "description": "CLI for discovering and running local HTTP, DAL, and Playwright test suites",
   "type": "module",
   "types": "./lib/index.d.ts",