@elench/testkit 0.1.18 → 0.1.19

package/README.md

@@ -46,6 +46,45 @@ npx @elench/testkit status
 npx @elench/testkit destroy
 ```
 
+## K6 Authoring
+
+Consumer k6 tests can import the shared authoring API directly from the package:
+
+```js
+import { defineHttpSuite } from "@elench/testkit";
+
+const suite = defineHttpSuite(({ rawReq }) => {
+  const res = rawReq("GET", "/health");
+});
+
+export const options = suite.options;
+export const setup = suite.setup;
+export default suite.exec;
+```
+
+For auth or schema-specific behavior, keep a small consumer-owned adapter next
+to the tests and pass it into the generic suite factory:
+
+```js
+import { defineHttpSuite } from "@elench/testkit";
+import { clerkSessionAuth } from "../helpers/testkit-auth.js";
+
+const suite = defineHttpSuite({ auth: clerkSessionAuth }, ({ req, setupData }) => {
+  req("GET", "/api/auth/me", setupData);
+});
+```
+
+`testkit` bundles these imports before invoking k6, so tests do not need
+generated `_testkit` files or direct package-manager path imports.
+
+Legacy compatibility:
+
+- `testkit runtime install`
+- `testkit runtime status`
+- `testkit runtime update`
+
+still exist, but direct package imports are now the preferred model.
+
 From outside the product repo, use `--dir` explicitly:
 
 ```bash
@@ -61,7 +100,7 @@ npx @elench/testkit --dir my-product api int -s health
 3. **Database** — provisions Docker-managed local Postgres when a service declares one
 4. **Seed** — runs optional product seed commands against the provisioned database
 5. **Runtime** — starts required local services, waits for readiness, and injects test env
-6. **Execution** — schedules file-level execution tasks across a global worker pool, reuses warm dependency graphs when possible, runs `k6` file-by-file, and batches Playwright files per worker
+6. **Execution** — schedules file-level execution tasks across a global worker pool, reuses warm dependency graphs when possible, bundles `k6` files before execution so package imports resolve cleanly, and batches Playwright files per worker
 7. **Cleanup** — stops local processes and preserves `.testkit/` state for inspection or later destroy
 
 Each run ends with a compact summary that shows per-service pass/fail status, suite totals, failed suites, and total duration.

package/lib/bundler/index.mjs

@@ -0,0 +1,95 @@
+import fs from "fs";
+import os from "os";
+import path from "path";
+import crypto from "crypto";
+import { build } from "esbuild";
+import { fileURLToPath } from "url";
+
+const PACKAGE_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..", "..");
+const ROOT_ENTRY = path.join(PACKAGE_ROOT, "lib", "index.mjs");
+const K6_ENTRY = path.join(PACKAGE_ROOT, "lib", "k6", "index.mjs");
+const K6_DIR = path.join(PACKAGE_ROOT, "lib", "k6");
+const bundleCache = new Map();
+
+export async function bundleK6File({
+  productDir,
+  serviceName,
+  sourceFile,
+}) {
+  const absoluteSource = path.resolve(productDir, sourceFile);
+  const bundleDir = path.join(productDir, ".testkit", "_bundles", serviceName || "shared");
+  fs.mkdirSync(bundleDir, { recursive: true });
+
+  const cacheKey = await buildCacheKey(absoluteSource);
+  const cached = bundleCache.get(cacheKey);
+  if (cached && fs.existsSync(cached)) {
+    return cached;
+  }
+
+  const outputFile = path.join(
+    bundleDir,
+    `${path.basename(sourceFile, path.extname(sourceFile))}-${cacheKey.slice(0, 12)}.js`
+  );
+
+  await build({
+    absWorkingDir: path.dirname(absoluteSource),
+    bundle: true,
+    entryPoints: [absoluteSource],
+    format: "esm",
+    legalComments: "none",
+    outfile: outputFile,
+    platform: "neutral",
+    sourcemap: "inline",
+    target: "es2020",
+    plugins: [testkitPackageAliasPlugin()],
+    external: [
+      "k6",
+      "k6/*",
+    ],
+  });
+
+  bundleCache.set(cacheKey, outputFile);
+  return outputFile;
+}
+
+async function buildCacheKey(sourceFile) {
+  const source = await fs.promises.readFile(sourceFile, "utf8");
+  const packageJson = await fs.promises.readFile(path.join(PACKAGE_ROOT, "package.json"), "utf8");
+  return crypto
+    .createHash("sha256")
+    .update(sourceFile)
+    .update("\0")
+    .update(source)
+    .update("\0")
+    .update(packageJson)
+    .digest("hex");
+}
+
+function testkitPackageAliasPlugin() {
+  return {
+    name: "testkit-package-alias",
+    setup(buildApi) {
+      buildApi.onResolve({ filter: /^@elench\/testkit(?:\/.*)?$/ }, (args) => {
+        return {
+          namespace: "file",
+          path: resolvePackageSubpath(args.path),
+        };
+      });
+    },
+  };
+}
+
+function resolvePackageSubpath(specifier) {
+  const subpath = specifier.slice("@elench/testkit".length);
+  if (!subpath) return ROOT_ENTRY;
+  if (subpath === "/k6") return K6_ENTRY;
+  if (subpath.startsWith("/k6/")) {
+    const rel = subpath.slice("/k6/".length);
+    const candidate = path.join(K6_DIR, `${rel}.mjs`);
+    if (fs.existsSync(candidate)) {
+      return candidate;
+    }
+  }
+
+  throw new Error(`Unsupported @elench/testkit import "${specifier}" in ${os.platform()}`);
+}

package/lib/bundler/index.test.mjs

@@ -0,0 +1,79 @@
+import fs from "fs";
+import os from "os";
+import path from "path";
+import { afterEach, describe, expect, it } from "vitest";
+import { bundleK6File } from "./index.mjs";
+
+const cleanups = [];
+
+afterEach(() => {
+  while (cleanups.length > 0) {
+    cleanups.pop()();
+  }
+});
+
+describe("k6 bundler", () => {
+  it("bundles root package imports for k6 execution", 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, "health.js");
+    fs.writeFileSync(
+      sourceFile,
+      [
+        'import { defineHttpSuite, json } from "@elench/testkit";',
+        'import { check } from "k6";',
+        "const suite = defineHttpSuite(({ rawReq }) => {",
+        '  const res = rawReq("GET", "/health");',
+        "  check(json(res), {",
+        '    "has status": (body) => typeof body.status === "string",',
+        "  });",
+        "});",
+        "export const options = suite.options;",
+        "export const setup = suite.setup;",
+        "export default suite.exec;",
+        "",
+      ].join("\n")
+    );
+
+    const bundledFile = await bundleK6File({
+      productDir: tmpDir,
+      serviceName: "api",
+      sourceFile,
+    });
+
+    const bundled = fs.readFileSync(bundledFile, "utf8");
+    expect(bundled).toContain("defineHttpSuite");
+    expect(bundled).toContain('import { check } from "k6"');
+  });
+
+  it("bundles subpath package imports for DAL execution", 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, "dal.js");
+    fs.writeFileSync(
+      sourceFile,
+      [
+        'import { defineDalSuite } from "@elench/testkit/k6";',
+        "const suite = defineDalSuite(({ db }) => {",
+        '  db.query("SELECT 1");',
+        "});",
+        "export const options = suite.options;",
+        "export const setup = suite.setup;",
+        "export default suite.exec;",
+        "",
+      ].join("\n")
+    );
+
+    const bundledFile = await bundleK6File({
+      productDir: tmpDir,
+      serviceName: "api",
+      sourceFile,
+    });
+
+    const bundled = fs.readFileSync(bundledFile, "utf8");
+    expect(bundled).toContain("defineDalSuite");
+    expect(bundled).toContain('import sql from "k6/x/sql"');
+  });
+});

package/lib/cli/index.mjs

@@ -8,10 +8,36 @@ import {
   validateFrameworkOption,
 } from "./args.mjs";
 import * as runner from "../runner/index.mjs";
+import * as runtime from "../runtime/index.mjs";
 
 export function run() {
   const cli = cac("testkit");
 
+  cli
+    .command("runtime <action>", "Install or inspect the consumer runtime bundle")
+    .option("--dir <path>", "Explicit product directory")
+    .option("--path <path>", "Target runtime path relative to the product directory")
+    .option("--strict", "Exit non-zero when runtime status is missing or drifted")
+    .action((action, options) => {
+      if (!["install", "status", "update"].includes(action)) {
+        throw new Error('Unknown runtime action. Expected one of: install, status, update.');
+      }
+
+      if (action === "status") {
+        const status = runtime.getRuntimeStatus(options);
+        console.log(runtime.formatRuntimeStatus(status));
+        if (options.strict && status.status !== "installed") {
+          process.exitCode = 1;
+        }
+        return;
+      }
+
+      const result = runtime.installRuntime(options);
+      console.log(
+        `Installed testkit runtime to ${result.relativeRuntimeDir} (${result.files.length} file${result.files.length === 1 ? "" : "s"})`
+      );
+    });
+
   cli
     .command("[first] [second] [third]", "Run test suites (int, e2e, dal, all)")
     .option("-s, --suite <name>", "Run specific suite(s)", { default: [] })

package/lib/index.mjs

@@ -0,0 +1 @@
+export * from "./k6/index.mjs";

package/lib/k6/checks.mjs

@@ -0,0 +1 @@
+export * from "../runtime-src/k6/checks.js";

package/lib/k6/dal-suite.mjs

@@ -0,0 +1 @@
+export * from "../runtime-src/k6/dal-suite.js";

package/lib/k6/dal.mjs

@@ -0,0 +1 @@
+export * from "../runtime-src/k6/dal.js";

package/lib/k6/http.mjs

@@ -0,0 +1 @@
+export * from "../runtime-src/k6/http.js";

package/lib/k6/index.mjs

@@ -0,0 +1,30 @@
+export {
+  allMatch,
+  contains,
+  defaultOptions,
+  isSorted,
+  json,
+  singleIterationOptions,
+} from "../runtime-src/k6/checks.js";
+export {
+  createDalContext,
+  openDb,
+  truncate,
+} from "../runtime-src/k6/dal.js";
+export { defineDalSuite } from "../runtime-src/k6/dal-suite.js";
+export {
+  createHttpClient,
+  defaultOptions as httpDefaultOptions,
+  getEnv,
+  makeGetWithHeaders,
+  makeRawReq,
+  makeReq,
+} from "../runtime-src/k6/http.js";
+export { defineHttpSuite } from "../runtime-src/k6/suite.js";
+
+export function createAuthAdapter({ setup, headers } = {}) {
+  return {
+    setup,
+    headers,
+  };
+}

package/lib/k6/suite.mjs

@@ -0,0 +1 @@
+export * from "../runtime-src/k6/suite.js";

package/lib/runner/index.mjs

@@ -3,6 +3,7 @@ import path from "path";
 import { spawn } from "child_process";
 import net from "net";
 import { execa, execaCommand } from "execa";
+import { bundleK6File } from "../bundler/index.mjs";
 import { resolveDalBinary, resolveServiceCwd } from "../config/index.mjs";
 import {
   cleanupOrphanedLocalInfrastructure,
@@ -520,10 +521,15 @@ async function runHttpK6Batch(targetConfig, batch) {
 
 async function runHttpK6Task(targetConfig, task, baseUrl) {
   const absFile = path.join(targetConfig.productDir, task.file);
+  const bundledFile = await bundleK6File({
+    productDir: targetConfig.productDir,
+    serviceName: targetConfig.name,
+    sourceFile: absFile,
+  });
   console.log(`·· ${targetConfig.workerLabel}:${task.suiteName} → ${task.file}`);
   const startedAt = Date.now();
   try {
-    await execa("k6", ["run", "--address", "127.0.0.1:0", "-e", `BASE_URL=${baseUrl}`, absFile], {
+    await execa("k6", ["run", "--address", "127.0.0.1:0", "-e", `BASE_URL=${baseUrl}`, bundledFile], {
       cwd: targetConfig.productDir,
       env: buildExecutionEnv(targetConfig),
       stdio: "inherit",
@@ -562,12 +568,17 @@ async function runDalBatch(targetConfig, batch) {
 async function runDalTask(targetConfig, task, databaseUrl) {
   const absFile = path.join(targetConfig.productDir, task.file);
   const k6Binary = resolveDalBinary();
+  const bundledFile = await bundleK6File({
+    productDir: targetConfig.productDir,
+    serviceName: targetConfig.name,
+    sourceFile: absFile,
+  });
   console.log(`·· ${targetConfig.workerLabel}:${task.suiteName} → ${task.file}`);
   const startedAt = Date.now();
   try {
     await execa(
       k6Binary,
-      ["run", "--address", "127.0.0.1:0", "-e", `DATABASE_URL=${databaseUrl}`, absFile],
+      ["run", "--address", "127.0.0.1:0", "-e", `DATABASE_URL=${databaseUrl}`, bundledFile],
       {
       cwd: targetConfig.productDir,
       env: buildExecutionEnv(targetConfig),

package/lib/runtime/index.mjs

@@ -0,0 +1,191 @@
+import crypto from "crypto";
+import fs from "fs";
+import path from "path";
+import { fileURLToPath } from "url";
+
+const RUNNER_MANIFEST = "runner.manifest.json";
+const TESTKIT_CONFIG = "testkit.config.json";
+const DEFAULT_RUNTIME_DIR = path.join("tests", "_testkit");
+const METADATA_FILE = ".runtime-manifest.json";
+const RUNTIME_FORMAT = 1;
+
+export function installRuntime(options = {}) {
+  const productDir = resolveProductDir(process.cwd(), options.dir);
+  const runtimeDir = resolveRuntimeDir(productDir, options.path);
+  const sourceFiles = readBundledRuntimeFiles();
+
+  fs.mkdirSync(runtimeDir, { recursive: true });
+
+  for (const file of sourceFiles) {
+    const targetPath = path.join(runtimeDir, file.path);
+    fs.mkdirSync(path.dirname(targetPath), { recursive: true });
+    fs.writeFileSync(targetPath, file.content);
+  }
+
+  const metadata = {
+    format: RUNTIME_FORMAT,
+    package: "@elench/testkit",
+    version: readPackageVersion(),
+    files: sourceFiles.map((file) => ({
+      path: file.path,
+      sha256: hashContent(file.content),
+    })),
+  };
+  fs.writeFileSync(
+    path.join(runtimeDir, METADATA_FILE),
+    `${JSON.stringify(metadata, null, 2)}\n`
+  );
+
+  return {
+    productDir,
+    runtimeDir,
+    relativeRuntimeDir: relativeToProduct(productDir, runtimeDir),
+    files: metadata.files,
+  };
+}
+
+export function getRuntimeStatus(options = {}) {
+  const productDir = resolveProductDir(process.cwd(), options.dir);
+  const runtimeDir = resolveRuntimeDir(productDir, options.path);
+  const sourceFiles = readBundledRuntimeFiles();
+  const metadataPath = path.join(runtimeDir, METADATA_FILE);
+
+  if (!fs.existsSync(runtimeDir) || !fs.existsSync(metadataPath)) {
+    return {
+      status: "missing",
+      productDir,
+      runtimeDir,
+      relativeRuntimeDir: relativeToProduct(productDir, runtimeDir),
+      missingFiles: sourceFiles.map((file) => file.path),
+      driftedFiles: [],
+    };
+  }
+
+  const missingFiles = [];
+  const driftedFiles = [];
+
+  for (const file of sourceFiles) {
+    const targetPath = path.join(runtimeDir, file.path);
+    if (!fs.existsSync(targetPath)) {
+      missingFiles.push(file.path);
+      continue;
+    }
+
+    const installed = fs.readFileSync(targetPath, "utf8");
+    if (installed !== file.content) {
+      driftedFiles.push(file.path);
+    }
+  }
+
+  const metadata = JSON.parse(fs.readFileSync(metadataPath, "utf8"));
+  const versionMatches = metadata.version === readPackageVersion();
+
+  return {
+    status:
+      missingFiles.length === 0 && driftedFiles.length === 0 && versionMatches
+        ? "installed"
+        : "drifted",
+    productDir,
+    runtimeDir,
+    relativeRuntimeDir: relativeToProduct(productDir, runtimeDir),
+    versionMatches,
+    missingFiles,
+    driftedFiles,
+  };
+}
+
+export function formatRuntimeStatus(result) {
+  if (result.status === "missing") {
+    return `Runtime not installed at ${result.relativeRuntimeDir}`;
+  }
+
+  if (result.status === "installed") {
+    return `Runtime at ${result.relativeRuntimeDir} is up to date`;
+  }
+
+  const problems = [];
+  if (result.missingFiles.length > 0) {
+    problems.push(`missing: ${result.missingFiles.join(", ")}`);
+  }
+  if (result.driftedFiles.length > 0) {
+    problems.push(`drifted: ${result.driftedFiles.join(", ")}`);
+  }
+  if (result.versionMatches === false) {
+    problems.push("version drift");
+  }
+
+  return `Runtime at ${result.relativeRuntimeDir} is drifted (${problems.join("; ")})`;
+}
+
+function resolveProductDir(cwd, explicitDir) {
+  const dir = explicitDir ? path.resolve(cwd, explicitDir) : cwd;
+  ensureProductFiles(dir);
+  return dir;
+}
+
+function ensureProductFiles(dir) {
+  const missing = [RUNNER_MANIFEST, TESTKIT_CONFIG].filter(
+    (file) => !fs.existsSync(path.join(dir, file))
+  );
+
+  if (missing.length > 0) {
+    throw new Error(
+      `Expected ${missing.join(" and ")} in ${dir}. Either cd into a product directory or use --dir.`
+    );
+  }
+}
+
+function resolveRuntimeDir(productDir, explicitPath) {
+  return path.resolve(productDir, explicitPath || DEFAULT_RUNTIME_DIR);
+}
+
+function relativeToProduct(productDir, targetPath) {
+  return path.relative(productDir, targetPath) || ".";
+}
+
+function readBundledRuntimeFiles() {
+  const sourceDir = path.resolve(
+    path.dirname(fileURLToPath(import.meta.url)),
+    "..",
+    "runtime-src"
+  );
+
+  return walkRuntimeFiles(sourceDir);
+}
+
+function walkRuntimeFiles(rootDir, relativeDir = "") {
+  const entries = fs.readdirSync(path.join(rootDir, relativeDir), {
+    withFileTypes: true,
+  });
+  const files = [];
+
+  for (const entry of entries) {
+    const nextRelative = path.join(relativeDir, entry.name);
+    if (entry.isDirectory()) {
+      files.push(...walkRuntimeFiles(rootDir, nextRelative));
+      continue;
+    }
+
+    const absolute = path.join(rootDir, nextRelative);
+    files.push({
+      path: nextRelative.split(path.sep).join("/"),
+      content: fs.readFileSync(absolute, "utf8"),
+    });
+  }
+
+  return files.sort((left, right) => left.path.localeCompare(right.path));
+}
+
+function readPackageVersion() {
+  const packagePath = path.resolve(
+    path.dirname(fileURLToPath(import.meta.url)),
+    "..",
+    "..",
+    "package.json"
+  );
+  return JSON.parse(fs.readFileSync(packagePath, "utf8")).version;
+}
+
+function hashContent(content) {
+  return crypto.createHash("sha256").update(content).digest("hex");
+}

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

@@ -0,0 +1,39 @@
+export function singleIterationOptions(overrides = {}) {
+  return {
+    iterations: 1,
+    thresholds: {
+      checks: ["rate==1.0"],
+      ...(overrides.thresholds || {}),
+    },
+    ...overrides,
+  };
+}
+
+export const defaultOptions = singleIterationOptions();
+
+export function json(res) {
+  return JSON.parse(res.body);
+}
+
+export function contains(rows, field, value) {
+  return rows.some((row) => row[field] === value);
+}
+
+export function allMatch(rows, predicate) {
+  return rows.length > 0 && rows.every(predicate);
+}
+
+export function isSorted(rows, field, direction = "asc") {
+  if (rows.length <= 1) return true;
+
+  for (let index = 1; index < rows.length; index += 1) {
+    if (direction === "asc" && rows[index][field] < rows[index - 1][field]) {
+      return false;
+    }
+    if (direction === "desc" && rows[index][field] > rows[index - 1][field]) {
+      return false;
+    }
+  }
+
+  return true;
+}

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

@@ -0,0 +1,33 @@
+import { defaultOptions } from "./checks.js";
+import { createDalContext, openDb } from "./dal.js";
+
+export function defineDalSuite(configOrRun, maybeRun) {
+  const { config, run } = normalizeSuiteArgs(configOrRun, maybeRun);
+  const db = config.db || openDb();
+  const dal = createDalContext(db);
+
+  return {
+    options: config.options || defaultOptions,
+    setup() {
+      if (typeof config.setup !== "function") return null;
+      return config.setup({ db, dal });
+    },
+    exec(setupData) {
+      return run({
+        db,
+        dal,
+        setupData,
+      });
+    },
+  };
+}
+
+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 };
+}

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

@@ -0,0 +1,32 @@
+import sql from "k6/x/sql";
+import driver from "k6/x/sql/driver/postgres";
+import {
+  allMatch,
+  contains,
+  defaultOptions,
+  isSorted,
+} from "./checks.js";
+
+export { allMatch, contains, defaultOptions, isSorted };
+
+export function openDb() {
+  const url = __ENV.DATABASE_URL;
+  if (!url) {
+    throw new Error("DATABASE_URL env var required");
+  }
+  return sql.open(driver, url);
+}
+
+export function truncate(db, ...tables) {
+  if (tables.length === 0) return;
+  db.exec(`TRUNCATE ${tables.join(", ")} CASCADE`);
+}
+
+export function createDalContext(db = openDb()) {
+  return {
+    db,
+    truncate(...tables) {
+      return truncate(db, ...tables);
+    },
+  };
+}

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

@@ -0,0 +1,134 @@
+import http from "k6/http";
+import { defaultOptions } from "./checks.js";
+
+export { defaultOptions };
+
+export function getEnv() {
+  const BASE = __ENV.BASE_URL;
+  const MACHINE_ID = __ENV.MACHINE_ID;
+
+  if (!BASE) {
+    throw new Error("BASE_URL env var required");
+  }
+
+  const routeParams = MACHINE_ID ? { "fly-force-instance-id": MACHINE_ID } : {};
+  return { BASE, MACHINE_ID, routeParams };
+}
+
+export function createHttpClient(config) {
+  const {
+    baseUrl,
+    routeHeaders = {},
+    defaultHeaders = { "Content-Type": "application/json" },
+    getHeaders = null,
+    getRawHeaders = null,
+  } = config;
+
+  if (!baseUrl) {
+    throw new Error("baseUrl is required");
+  }
+
+  function buildHeaders(builder, setupData, extraHeaders = {}) {
+    return {
+      ...defaultHeaders,
+      ...safeHeaders(builder, setupData),
+      ...routeHeaders,
+      ...extraHeaders,
+    };
+  }
+
+  function request(method, path, setupData, body, extraHeaders = {}) {
+    const url = `${baseUrl}${path}`;
+    const headers = buildHeaders(getHeaders, setupData, extraHeaders);
+    return runHttpRequest(method, 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);
+  }
+
+  function getWithHeaders(path, setupData, extraHeaders = {}) {
+    return http.get(`${baseUrl}${path}`, {
+      headers: buildHeaders(getHeaders, setupData, extraHeaders),
+    });
+  }
+
+  return {
+    request,
+    raw,
+    get(path, setupData, extraHeaders = {}) {
+      return request("GET", path, setupData, null, extraHeaders);
+    },
+    put(path, setupData, body, extraHeaders = {}) {
+      return request("PUT", path, setupData, body, extraHeaders);
+    },
+    post(path, setupData, body, extraHeaders = {}) {
+      return request("POST", path, setupData, body, extraHeaders);
+    },
+    patch(path, setupData, body, extraHeaders = {}) {
+      return request("PATCH", path, setupData, body, extraHeaders);
+    },
+    delete(path, setupData, extraHeaders = {}) {
+      return request("DELETE", path, setupData, null, extraHeaders);
+    },
+    rawGet(path, extraHeaders = {}) {
+      return raw("GET", path, null, extraHeaders);
+    },
+    rawPost(path, body, extraHeaders = {}) {
+      return raw("POST", path, body, extraHeaders);
+    },
+    rawPut(path, body, extraHeaders = {}) {
+      return raw("PUT", path, body, extraHeaders);
+    },
+    rawPatch(path, body, extraHeaders = {}) {
+      return raw("PATCH", path, body, extraHeaders);
+    },
+    rawDelete(path, extraHeaders = {}) {
+      return raw("DELETE", path, null, extraHeaders);
+    },
+    getWithHeaders,
+  };
+}
+
+export function makeReq(baseUrl, routeHeaders = {}, getHeaders = null) {
+  return createHttpClient({
+    baseUrl,
+    routeHeaders,
+    getHeaders,
+  }).request;
+}
+
+export function makeRawReq(baseUrl, routeHeaders = {}, getRawHeaders = null) {
+  return createHttpClient({
+    baseUrl,
+    routeHeaders,
+    getRawHeaders,
+  }).raw;
+}
+
+export function makeGetWithHeaders(baseUrl, routeHeaders = {}, getHeaders = null) {
+  return createHttpClient({
+    baseUrl,
+    routeHeaders,
+    getHeaders,
+  }).getWithHeaders;
+}
+
+function runHttpRequest(method, url, body, headers) {
+  const options = { headers };
+
+  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);
+
+  throw new Error(`unsupported method: ${method}`);
+}
+
+function safeHeaders(builder, setupData) {
+  if (typeof builder !== "function") return {};
+  return builder(setupData) || {};
+}

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

@@ -0,0 +1,55 @@
+import { defaultOptions } from "./checks.js";
+import { createHttpClient, getEnv } from "./http.js";
+
+export function defineHttpSuite(configOrRun, maybeRun) {
+  const { config, run } = normalizeSuiteArgs(configOrRun, maybeRun);
+  const env = config.env || getEnv();
+  const auth = config.auth || null;
+
+  const client = createHttpClient({
+    baseUrl: env.BASE,
+    routeHeaders: env.routeParams,
+    getHeaders(setupData) {
+      return {
+        ...callHeaders(auth?.headers, setupData, env),
+        ...callHeaders(config.headers, setupData, env),
+      };
+    },
+    getRawHeaders(setupData) {
+      return callHeaders(config.rawHeaders, setupData, env);
+    },
+  });
+
+  return {
+    options: config.options || defaultOptions,
+    setup() {
+      if (typeof auth?.setup !== "function") return null;
+      return auth.setup({ env });
+    },
+    exec(setupData) {
+      return run({
+        env,
+        req: client.request,
+        rawReq: client.raw,
+        getWithHeaders: client.getWithHeaders,
+        setupData,
+        session: setupData,
+      });
+    },
+  };
+}
+
+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 }) || {};
+}

package/package.json

@@ -1,8 +1,14 @@
 {
   "name": "@elench/testkit",
-  "version": "0.1.18",
+  "version": "0.1.19",
   "description": "CLI for running manifest-defined local test suites across k6 and Playwright",
   "type": "module",
+  "exports": {
+    ".": "./lib/index.mjs",
+    "./k6": "./lib/k6/index.mjs",
+    "./k6/*": "./lib/k6/*.mjs",
+    "./package.json": "./package.json"
+  },
   "bin": {
     "testkit": "bin/testkit.mjs"
   },
@@ -23,6 +29,7 @@
   },
   "dependencies": {
     "cac": "^6.7.14",
+    "esbuild": "^0.25.11",
     "execa": "^9.5.0"
   },
   "engines": {