@elench/testkit 0.1.25 → 0.1.27

package/lib/index.d.ts

@@ -0,0 +1,93 @@
+import type {
+  HttpClient,
+  HttpClientConfig,
+  RuntimeDb,
+  RuntimeDalContext,
+  RuntimeEnv,
+  RuntimeHeaders,
+  RuntimeOptions,
+  RuntimeResponse,
+} from "./runtime/index";
+
+export interface TestkitSuite<TSetup = unknown> {
+  options: RuntimeOptions;
+  setup: () => TSetup | null;
+  exec: (setupData: TSetup | null) => unknown;
+}
+
+export interface HeaderBuilderContext {
+  env: RuntimeEnv;
+}
+
+export type HeaderBuilder<TSetup = unknown> = (
+  setupData?: TSetup | null,
+  context?: HeaderBuilderContext
+) => RuntimeHeaders | void;
+
+export interface AuthAdapter<TSetup = unknown> {
+  setup?: (context: { env: RuntimeEnv }) => TSetup;
+  headers?: HeaderBuilder<TSetup>;
+}
+
+export interface HttpSuiteContext<TSetup = unknown> {
+  env: RuntimeEnv;
+  req: HttpClient<TSetup>["request"];
+  rawReq: HttpClient["raw"];
+  getWithHeaders: HttpClient<TSetup>["getWithHeaders"];
+  setupData: TSetup | null;
+  session: TSetup | null;
+}
+
+export interface HttpSuiteConfig<TSetup = unknown> {
+  auth?: AuthAdapter<TSetup> | null;
+  env?: RuntimeEnv;
+  headers?: HeaderBuilder<TSetup>;
+  profile?: string;
+  rawHeaders?: HeaderBuilder<never>;
+  options?: RuntimeOptions;
+}
+
+export interface DalSuiteContext<TSetup = unknown> {
+  db: RuntimeDb;
+  dal: RuntimeDalContext;
+  setupData: TSetup | null;
+}
+
+export interface DalSuiteConfig<TSetup = unknown> {
+  db?: RuntimeDb;
+  options?: RuntimeOptions;
+  setup?: (context: { db: RuntimeDb; dal: RuntimeDalContext }) => TSetup;
+}
+
+export declare function defineHttpSuite<TSetup = unknown>(
+  run: (context: HttpSuiteContext<TSetup>) => unknown
+): TestkitSuite<TSetup>;
+
+export declare function defineHttpSuite<TSetup = unknown>(
+  config: HttpSuiteConfig<TSetup>,
+  run: (context: HttpSuiteContext<TSetup>) => unknown
+): TestkitSuite<TSetup>;
+
+export declare function defineDalSuite<TSetup = unknown>(
+  run: (context: DalSuiteContext<TSetup>) => unknown
+): TestkitSuite<TSetup>;
+
+export declare function defineDalSuite<TSetup = unknown>(
+  config: DalSuiteConfig<TSetup>,
+  run: (context: DalSuiteContext<TSetup>) => unknown
+): TestkitSuite<TSetup>;
+
+export declare function createAuthAdapter<TSetup = unknown>(
+  adapter?: AuthAdapter<TSetup>
+): AuthAdapter<TSetup>;
+
+export type {
+  HttpClient,
+  HttpClientConfig,
+  RuntimeDb,
+  RuntimeDalContext,
+  RuntimeEnv,
+  RuntimeHeaders,
+  RuntimeOptions,
+  RuntimeResponse,
+};

package/lib/package.test.mjs

@@ -0,0 +1,29 @@
+import fs from "fs";
+import path from "path";
+import { fileURLToPath } from "url";
+import { describe, expect, it } from "vitest";
+
+const rootDir = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
+const packageJsonPath = path.join(rootDir, "package.json");
+const packageJson = JSON.parse(fs.readFileSync(packageJsonPath, "utf8"));
+
+describe("package metadata", () => {
+  it("ships first-party type declarations for the public exports", () => {
+    expect(packageJson.types).toBe("./lib/index.d.ts");
+    expect(packageJson.exports["."]).toEqual({
+      types: "./lib/index.d.ts",
+      default: "./lib/index.mjs",
+    });
+    expect(packageJson.exports["./setup"]).toEqual({
+      types: "./lib/setup/index.d.ts",
+      default: "./lib/setup/index.mjs",
+    });
+    expect(packageJson.exports["./runtime"]).toEqual({
+      types: "./lib/runtime/index.d.ts",
+      default: "./lib/runtime/index.mjs",
+    });
+    expect(fs.existsSync(path.join(rootDir, "lib", "index.d.ts"))).toBe(true);
+    expect(fs.existsSync(path.join(rootDir, "lib", "setup", "index.d.ts"))).toBe(true);
+    expect(fs.existsSync(path.join(rootDir, "lib", "runtime", "index.d.ts"))).toBe(true);
+  });
+});

package/lib/runner/index.mjs

@@ -832,12 +832,15 @@ function printRunSummary(results, durationMs) {
   );
   const failedSuites = executedServices.reduce((sum, result) => sum + result.failedSuiteCount, 0);
   const passedSuites = completedSuites - failedSuites;
+  const totalFiles = executedServices.reduce((sum, result) => sum + (result.totalFileCount || 0), 0);
+  const passedFiles = executedServices.reduce((sum, result) => sum + (result.passedFileCount || 0), 0);
 
   console.log("\n══ Summary ══");
   console.log(
     [
       `services ${passedServices.length}/${executedServices.length} passed`,
       `suites ${passedSuites}/${totalSuites} passed`,
+      totalFiles > 0 ? `files ${passedFiles}/${totalFiles} passed` : null,
       skippedServices.length > 0 ? `${skippedServices.length} skipped` : null,
       `duration ${formatDuration(durationMs)}`,
     ]

package/lib/runner/results.mjs

@@ -156,6 +156,19 @@ export function finalizeServiceResult(tracker, startedAt, finishedAt) {
     (suite) => suite.completedFileCount === suite.fileCount
   ).length;
   const failedSuiteCount = suites.filter((suite) => suite.failedFiles.length > 0).length;
+  const totalFileCount = suites.reduce((sum, suite) => sum + suite.fileCount, 0);
+  const completedFileCount = suites.reduce(
+    (sum, suite) => sum + suite.completedFileCount,
+    0
+  );
+  const failedFileCount = suites.reduce((sum, suite) => sum + suite.failedFiles.length, 0);
+  const passedFileCount = suites.reduce(
+    (sum, suite) =>
+      sum +
+      suite.fileResults.filter((file) => file.status === "passed").length,
+    0
+  );
+  const notRunFileCount = totalFileCount - completedFileCount;
   const accumulatedDurationMs = suites.reduce((sum, suite) => sum + suite.durationMs, 0);
   const durationMs =
     tracker.firstTaskAt && tracker.lastTaskAt
@@ -173,6 +186,11 @@ export function finalizeServiceResult(tracker, startedAt, finishedAt) {
     suiteCount: tracker.suiteCount,
     completedSuiteCount,
     failedSuiteCount,
+    totalFileCount,
+    completedFileCount,
+    passedFileCount,
+    failedFileCount,
+    notRunFileCount,
     durationMs,
     suites: suites.map((suite) => ({
       name: suite.name,
@@ -180,6 +198,10 @@ export function finalizeServiceResult(tracker, startedAt, finishedAt) {
       framework: formatFrameworkForArtifact(suite.framework),
       failed: suite.failedFiles.length > 0,
       fileCount: suite.fileCount,
+      completedFileCount: suite.completedFileCount,
+      passedFileCount: suite.fileResults.filter((file) => file.status === "passed").length,
+      failedFileCount: suite.failedFiles.length,
+      notRunFileCount: suite.fileCount - suite.completedFileCount,
       failedFiles: suite.failedFiles,
       durationMs: suite.durationMs,
       error: suite.error,
@@ -299,6 +321,10 @@ export function buildRunArtifact({
   const totalSuites = executed.reduce((sum, result) => sum + result.suiteCount, 0);
   const completedSuites = executed.reduce((sum, result) => sum + result.completedSuiteCount, 0);
   const failedSuites = executed.reduce((sum, result) => sum + result.failedSuiteCount, 0);
+  const totalFiles = executed.reduce((sum, result) => sum + (result.totalFileCount || 0), 0);
+  const passedFiles = executed.reduce((sum, result) => sum + (result.passedFileCount || 0), 0);
+  const failedFiles = executed.reduce((sum, result) => sum + (result.failedFileCount || 0), 0);
+  const notRunFiles = executed.reduce((sum, result) => sum + (result.notRunFileCount || 0), 0);
   const dbBackend = summarizeDbBackend(results);
 
   return {
@@ -339,6 +365,12 @@ export function buildRunArtifact({
         passed: completedSuites - failedSuites,
         failed: failedSuites,
       },
+      files: {
+        total: totalFiles,
+        passed: passedFiles,
+        failed: failedFiles,
+        notRun: notRunFiles,
+      },
     },
     services: results.map((result) => ({
       name: result.name,
@@ -347,6 +379,11 @@ export function buildRunArtifact({
       suiteCount: result.suiteCount,
       completedSuiteCount: result.completedSuiteCount,
       failedSuiteCount: result.failedSuiteCount,
+      totalFileCount: result.totalFileCount,
+      completedFileCount: result.completedFileCount,
+      passedFileCount: result.passedFileCount,
+      failedFileCount: result.failedFileCount,
+      notRunFileCount: result.notRunFileCount,
       durationMs: result.durationMs,
       dbBackend: result.dbBackend,
       suites: result.suites,
@@ -372,10 +409,15 @@ export function formatDuration(durationMs) {
 
 export function formatServiceSummary(result) {
   const passedSuites = result.completedSuiteCount - result.failedSuiteCount;
-  const notRun = result.suiteCount - result.completedSuiteCount;
+  const notRunSuites = result.suiteCount - result.completedSuiteCount;
   let detail = `${passedSuites}/${result.suiteCount} suites passed`;
-  if (notRun > 0) {
-    detail += `, ${notRun} not run`;
+  if ((result.totalFileCount || 0) > 0) {
+    detail += `, ${result.passedFileCount}/${result.totalFileCount} files passed`;
+  }
+  if (notRunSuites > 0) {
+    detail += `, ${notRunSuites} ${pluralize(notRunSuites, "suite", "suites")} not run`;
+  } else if ((result.notRunFileCount || 0) > 0) {
+    detail += `, ${result.notRunFileCount} ${pluralize(result.notRunFileCount, "file", "files")} not run`;
   }
   return detail;
 }
@@ -404,3 +446,7 @@ function sanitizeErrorMessage(message) {
     .replace(/Command failed with exit code (\d+): k6 run\b/g, "Default runtime failed with exit code $1:")
     .replace(/[\\/]vendor[\\/]k6\b/g, "default-runtime");
 }
+
+function pluralize(value, singular, plural) {
+  return value === 1 ? singular : plural;
+}

package/lib/runner/results.test.mjs

@@ -64,8 +64,12 @@ describe("runner-results", () => {
     const result = finalizeServiceResult(tracker, 1000, 1500);
     expect(result.failed).toBe(true);
     expect(result.failedSuiteCount).toBe(1);
+    expect(result.totalFileCount).toBe(1);
+    expect(result.failedFileCount).toBe(1);
+    expect(result.passedFileCount).toBe(0);
     expect(result.errors).toEqual(["worker failed", "graph failed"]);
     expect(result.suites[0].framework).toBe("default");
+    expect(result.suites[0].failedFileCount).toBe(1);
     expect(result.suites[0].files).toEqual([
       {
         path: "tests/health.js",
@@ -86,6 +90,11 @@ describe("runner-results", () => {
         suiteCount: 1,
         completedSuiteCount: 1,
         failedSuiteCount: 0,
+        totalFileCount: 3,
+        completedFileCount: 3,
+        passedFileCount: 3,
+        failedFileCount: 0,
+        notRunFileCount: 0,
         durationMs: 1200,
         dbBackend: "local",
         suites: [],
@@ -98,6 +107,11 @@ describe("runner-results", () => {
         suiteCount: 0,
         completedSuiteCount: 0,
         failedSuiteCount: 0,
+        totalFileCount: 0,
+        completedFileCount: 0,
+        passedFileCount: 0,
+        failedFileCount: 0,
+        notRunFileCount: 0,
         durationMs: 0,
         dbBackend: null,
         suites: [],
@@ -134,6 +148,12 @@ describe("runner-results", () => {
 
     expect(artifact.product.name).toBe("my-product");
     expect(artifact.summary.services.total).toBe(1);
+    expect(artifact.summary.files).toEqual({
+      total: 3,
+      passed: 3,
+      failed: 0,
+      notRun: 0,
+    });
     expect(summarizeDbBackend(results)).toBe("local");
     expect(formatDuration(65_000)).toBe("1m 05s");
     expect(
@@ -141,8 +161,11 @@ describe("runner-results", () => {
         completedSuiteCount: 2,
         failedSuiteCount: 1,
         suiteCount: 3,
+        totalFileCount: 6,
+        passedFileCount: 5,
+        notRunFileCount: 1,
       })
-    ).toBe("1/3 suites passed, 1 not run");
+    ).toBe("1/3 suites passed, 5/6 files passed, 1 suite not run");
     expect(formatError(new Error("boom"))).toBe("boom");
   });
 

package/lib/runner/template.mjs

@@ -72,7 +72,7 @@ export function buildPortMap(runtimeConfigs, workerId) {
     if (existing) {
       throw new Error(
         `Worker port collision: services "${existing}" and "${config.name}" both resolve to ${actualPort}. ` +
-          `Assign distinct local.port/baseUrl ports in testkit.config.json.`
+          `Assign distinct local.port/baseUrl ports in testkit.setup.ts.`
       );
     }
     seen.set(actualPort, config.name);

package/lib/runtime/index.d.ts

@@ -0,0 +1,183 @@
+export type RuntimeMethod = "GET" | "POST" | "PUT" | "PATCH" | "DELETE";
+
+export interface RuntimeHeaders {
+  [key: string]: string;
+}
+
+export interface RuntimeCookie {
+  value: string;
+}
+
+export interface RuntimeResponse {
+  body: string;
+  cookies?: Record<string, RuntimeCookie[]>;
+  headers?: Record<string, string | string[] | undefined>;
+  status: number;
+  timings?: {
+    duration: number;
+  };
+}
+
+export interface RuntimeOptions {
+  [key: string]: unknown;
+  thresholds?: Record<string, unknown>;
+}
+
+export interface RuntimeEnv {
+  BASE: string;
+  MACHINE_ID?: string;
+  routeParams: RuntimeHeaders;
+}
+
+export interface RuntimeDb {
+  exec(sql: string): unknown;
+  query<T = Record<string, unknown>>(sql: string): T[];
+}
+
+export interface RuntimeDalContext {
+  db: RuntimeDb;
+  truncate(...tables: string[]): void;
+}
+
+export interface HttpRequestParams {
+  headers?: RuntimeHeaders;
+  redirects?: number;
+}
+
+export interface RuntimeHttpClient {
+  del(url: string, body?: unknown, params?: HttpRequestParams): RuntimeResponse;
+  file(data: unknown, filename?: string, contentType?: string): unknown;
+  get(url: string, params?: HttpRequestParams): RuntimeResponse;
+  patch(url: string, body?: unknown, params?: HttpRequestParams): RuntimeResponse;
+  post(url: string, body?: unknown, params?: HttpRequestParams): RuntimeResponse;
+  put(url: string, body?: unknown, params?: HttpRequestParams): RuntimeResponse;
+}
+
+export interface Metric {
+  add(value: number): void;
+}
+
+export declare class Rate implements Metric {
+  constructor(name: string, isTime?: boolean);
+  add(value: number): void;
+}
+
+export declare class Trend implements Metric {
+  constructor(name: string, isTime?: boolean);
+  add(value: number): void;
+}
+
+export interface HttpClientConfig<TSetup = unknown> {
+  baseUrl: string;
+  defaultHeaders?: RuntimeHeaders;
+  getHeaders?: (setupData?: TSetup | null) => RuntimeHeaders | void;
+  getRawHeaders?: (setupData?: TSetup | null) => RuntimeHeaders | void;
+  routeHeaders?: RuntimeHeaders;
+}
+
+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(
+    path: string,
+    setupData?: TSetup | null,
+    body?: unknown,
+    extraHeaders?: RuntimeHeaders
+  ): RuntimeResponse;
+  post(
+    path: string,
+    setupData?: TSetup | null,
+    body?: unknown,
+    extraHeaders?: RuntimeHeaders
+  ): RuntimeResponse;
+  put(
+    path: string,
+    setupData?: TSetup | null,
+    body?: unknown,
+    extraHeaders?: RuntimeHeaders
+  ): RuntimeResponse;
+  raw(
+    method: RuntimeMethod,
+    path: string,
+    body?: unknown,
+    extraHeaders?: RuntimeHeaders
+  ): RuntimeResponse;
+  rawDelete(path: string, extraHeaders?: RuntimeHeaders): RuntimeResponse;
+  rawGet(path: string, extraHeaders?: RuntimeHeaders): RuntimeResponse;
+  rawPatch(path: string, body?: unknown, extraHeaders?: RuntimeHeaders): RuntimeResponse;
+  rawPost(path: string, body?: unknown, extraHeaders?: RuntimeHeaders): RuntimeResponse;
+  rawPut(path: string, body?: unknown, extraHeaders?: RuntimeHeaders): RuntimeResponse;
+  request(
+    method: RuntimeMethod,
+    path: string,
+    setupData?: TSetup | null,
+    body?: unknown,
+    extraHeaders?: RuntimeHeaders
+  ): RuntimeResponse;
+}
+
+export declare const check: <T>(
+  value: T,
+  checks: Record<string, (value: T) => boolean>
+) => boolean;
+export declare const fail: (message: string) => never;
+export declare const group: (name: string, fn: () => void) => void;
+export declare const sleep: (seconds?: number) => void;
+
+export declare const http: RuntimeHttpClient;
+
+export declare function file(data: unknown, filename?: string, contentType?: string): unknown;
+export declare function json<T = unknown>(response: Pick<RuntimeResponse, "body">): T;
+export declare function contains<T extends Record<string, unknown>>(
+  rows: T[],
+  field: keyof T | string,
+  value: unknown
+): boolean;
+export declare function allMatch<T>(
+  rows: T[],
+  predicate: (row: T) => boolean
+): boolean;
+export declare function isSorted<T extends Record<string, unknown>>(
+  rows: T[],
+  field: keyof T | string,
+  direction?: "asc" | "desc"
+): boolean;
+
+export declare function singleIterationOptions(overrides?: RuntimeOptions): RuntimeOptions;
+export declare const defaultOptions: RuntimeOptions;
+export declare const httpDefaultOptions: RuntimeOptions;
+
+export declare function createDalContext(db?: RuntimeDb): RuntimeDalContext;
+export declare function openDb(): RuntimeDb;
+export declare function truncate(db: RuntimeDb, ...tables: string[]): void;
+
+export declare function getEnv(): RuntimeEnv;
+export declare function createHttpClient<TSetup = unknown>(
+  config: HttpClientConfig<TSetup>
+): HttpClient<TSetup>;
+export declare function makeReq<TSetup = unknown>(
+  baseUrl: string,
+  routeHeaders?: RuntimeHeaders,
+  getHeaders?: (setupData?: TSetup | null) => RuntimeHeaders | void
+): HttpClient<TSetup>["request"];
+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"];
+
+declare global {
+  const __ENV: Record<string, string | undefined>;
+}
+
+export {};

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

@@ -56,6 +56,7 @@ export function createHttpClient(config) {
   }
 
   return {
+    rawHttp: http,
     request,
     raw,
     get(path, setupData, extraHeaders = {}) {

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

@@ -1,50 +1,49 @@
 import { fail } from "k6";
 import { defaultOptions, recordRuntimeFailure } from "./checks.js";
 import { createHttpClient, getEnv } from "./http.js";
+import {
+  clearRuntimeContext,
+  registerRuntimeContext,
+  resolveHttpProfile,
+} from "../../setup/runtime.mjs";
 
 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,
+    get options() {
+      return mergeProfileConfig(config).options || defaultOptions;
+    },
     setup() {
-      if (typeof auth?.setup !== "function") return null;
+      const resolved = resolveRuntimeConfig(config);
       try {
-        return auth.setup({ env });
+        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) {
         recordRuntimeFailure();
         fail(formatFatalSuiteError("setup", error));
+      } finally {
+        clearRuntimeContext();
       }
     },
     exec(setupData) {
+      const resolved = resolveRuntimeConfig(config);
       try {
+        registerRuntimeContext({ env: resolved.env, http: resolved.client.rawHttp || null });
         return run({
-          env,
-          req: client.request,
-          rawReq: client.raw,
-          getWithHeaders: client.getWithHeaders,
+          env: resolved.env,
+          req: resolved.client.request,
+          rawReq: resolved.client.raw,
+          getWithHeaders: resolved.client.getWithHeaders,
           setupData,
           session: setupData,
         });
       } catch (error) {
         recordRuntimeFailure();
         fail(formatFatalSuiteError("exec", error));
+      } finally {
+        clearRuntimeContext();
       }
     },
   };
@@ -65,6 +64,50 @@ function callHeaders(builder, setupData, env) {
   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}`;