@elench/testkit 0.1.69 → 0.1.71

package/lib/package.test.mjs

@@ -14,14 +14,30 @@ describe("package metadata", () => {
       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["./config"]).toEqual({
+      types: "./lib/config-api/index.d.ts",
+      default: "./lib/config-api/index.mjs",
+    });
+    expect(packageJson.exports["./drizzle"]).toEqual({
+      types: "./lib/drizzle/index.d.ts",
+      default: "./lib/drizzle/index.mjs",
+    });
+    expect(packageJson.exports["./env"]).toEqual({
+      types: "./lib/env/index.d.ts",
+      default: "./lib/env/index.mjs",
+    });
+    expect(packageJson.exports["./playwright"]).toEqual({
+      types: "./lib/playwright/index.d.ts",
+      default: "./lib/playwright/index.mjs",
     });
     expect(packageJson.exports["./runtime"]).toEqual({
       types: "./lib/runtime/index.d.ts",
       default: "./lib/runtime/index.mjs",
     });
+    expect(packageJson.exports["./vitest"]).toEqual({
+      types: "./lib/vitest/index.d.ts",
+      default: "./lib/vitest/index.mjs",
+    });
     expect(packageJson.exports["./discovery"]).toEqual({
       types: "./lib/discovery/index.d.ts",
       default: "./lib/discovery/index.mjs",
@@ -31,8 +47,12 @@ describe("package metadata", () => {
       default: "./lib/known-failures/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", "config-api", "index.d.ts"))).toBe(true);
+    expect(fs.existsSync(path.join(rootDir, "lib", "drizzle", "index.d.ts"))).toBe(true);
+    expect(fs.existsSync(path.join(rootDir, "lib", "env", "index.d.ts"))).toBe(true);
+    expect(fs.existsSync(path.join(rootDir, "lib", "playwright", "index.d.ts"))).toBe(true);
     expect(fs.existsSync(path.join(rootDir, "lib", "runtime", "index.d.ts"))).toBe(true);
+    expect(fs.existsSync(path.join(rootDir, "lib", "vitest", "index.d.ts"))).toBe(true);
     expect(fs.existsSync(path.join(rootDir, "lib", "discovery", "index.d.ts"))).toBe(true);
     expect(fs.existsSync(path.join(rootDir, "lib", "known-failures", "index.d.ts"))).toBe(true);
   });

package/lib/playwright/index.d.ts

@@ -0,0 +1,21 @@
+export interface PlaywrightConfigOptions {
+  cwd?: string;
+  defaultFileTimeoutSeconds?: number;
+  dotenvFiles?: string[];
+  env?: NodeJS.ProcessEnv;
+  onlyWhenAllowed?: boolean;
+  override?: boolean;
+}
+
+export declare function defineConfig<T extends Record<string, unknown>>(
+  config: T,
+  options?: PlaywrightConfigOptions
+): T & {
+  timeout: number;
+  expect: Record<string, unknown> & { timeout: number };
+  use: Record<string, unknown> & {
+    actionTimeout: number;
+    navigationTimeout: number;
+  };
+  webServer?: unknown;
+};

package/lib/playwright/index.mjs

@@ -0,0 +1,53 @@
+import {
+  DEFAULT_FILE_TIMEOUT_SECONDS,
+  INTERNAL_FILE_TIMEOUT_SECONDS_ENV,
+} from "../shared/file-timeout.mjs";
+import { loadDotenvFiles } from "../env/index.mjs";
+
+export function defineConfig(config = {}, options = {}) {
+  const env = options.env || process.env;
+  loadDotenvFiles({
+    cwd: options.cwd,
+    env,
+    files: options.dotenvFiles || [".env.local"],
+    onlyWhenAllowed: options.onlyWhenAllowed,
+    override: options.override,
+  });
+
+  const timeoutSeconds = readTimeoutSeconds(env, options.defaultFileTimeoutSeconds);
+  const timeoutMs = timeoutSeconds * 1000;
+  const managed = env?.TESTKIT_MANAGED_SERVERS === "1";
+  const baseURL = env.BASE_URL || config.use?.baseURL;
+  const use = {
+    ...(config.use || {}),
+    ...(baseURL ? { baseURL } : {}),
+    actionTimeout: timeoutMs,
+    navigationTimeout: timeoutMs,
+  };
+
+  return {
+    ...config,
+    timeout: timeoutMs,
+    expect: {
+      ...(config.expect || {}),
+      timeout: timeoutMs,
+    },
+    use,
+    ...(managed ? { webServer: undefined } : {}),
+  };
+}
+
+function readTimeoutSeconds(env, fallbackSeconds) {
+  const rawValue = env?.[INTERNAL_FILE_TIMEOUT_SECONDS_ENV];
+  const normalizedFallback = normalizeTimeoutSeconds(fallbackSeconds ?? DEFAULT_FILE_TIMEOUT_SECONDS);
+  if (rawValue == null) return normalizedFallback;
+  return normalizeTimeoutSeconds(rawValue);
+}
+
+function normalizeTimeoutSeconds(value) {
+  const normalized = Number(value);
+  if (!Number.isInteger(normalized) || normalized <= 0) {
+    throw new Error("Playwright file timeout seconds must be a positive integer.");
+  }
+  return normalized;
+}

package/lib/playwright/index.test.mjs

@@ -0,0 +1,43 @@
+import { describe, expect, it } from "vitest";
+import { defineConfig } from "./index.mjs";
+
+describe("testkit playwright defineConfig", () => {
+  it("derives timeouts from the managed file-timeout env", () => {
+    const config = defineConfig(
+      {
+        use: {
+          trace: "on-first-retry",
+        },
+      },
+      {
+        env: {
+          TESTKIT_INTERNAL_FILE_TIMEOUT_SECONDS: "45",
+        },
+      }
+    );
+
+    expect(config.timeout).toBe(45_000);
+    expect(config.expect.timeout).toBe(45_000);
+    expect(config.use.actionTimeout).toBe(45_000);
+    expect(config.use.trace).toBe("on-first-retry");
+  });
+
+  it("disables webServer during managed runs and respects BASE_URL", () => {
+    const config = defineConfig(
+      {
+        webServer: [{ command: "npm run dev" }],
+        use: {},
+      },
+      {
+        env: {
+          TESTKIT_ACTIVE: "1",
+          TESTKIT_MANAGED_SERVERS: "1",
+          BASE_URL: "http://127.0.0.1:3000",
+        },
+      }
+    );
+
+    expect(config.webServer).toBeUndefined();
+    expect(config.use.baseURL).toBe("http://127.0.0.1:3000");
+  });
+});

package/lib/runner/template-steps.mjs

@@ -22,11 +22,11 @@ import {
 
 const PACKAGE_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..", "..");
 const ROOT_ENTRY = path.join(PACKAGE_ROOT, "lib", "index.mjs");
-const SETUP_ENTRY = path.join(PACKAGE_ROOT, "lib", "setup", "index.mjs");
-const SETUP_NEXT_TSCONFIG_ENTRY = path.join(
+const CONFIG_ENTRY = path.join(PACKAGE_ROOT, "lib", "config-api", "index.mjs");
+const CONFIG_NEXT_TSCONFIG_ENTRY = path.join(
   PACKAGE_ROOT,
   "lib",
-  "setup",
+  "config-api",
   "next-runtime-tsconfig.mjs"
 );
 const RUNTIME_ENTRY = path.join(PACKAGE_ROOT, "lib", "runtime", "index.mjs");
@@ -250,8 +250,8 @@ function testkitAliasPlugin() {
 function resolvePackageSubpath(specifier) {
   const subpath = specifier.slice("@elench/testkit".length);
   if (!subpath) return ROOT_ENTRY;
-  if (subpath === "/setup") return SETUP_ENTRY;
-  if (subpath === "/setup/next-runtime-tsconfig") return SETUP_NEXT_TSCONFIG_ENTRY;
+  if (subpath === "/config") return CONFIG_ENTRY;
+  if (subpath === "/config/next-runtime-tsconfig") return CONFIG_NEXT_TSCONFIG_ENTRY;
   if (subpath === "/runtime") return RUNTIME_ENTRY;
   if (subpath === "/known-failures") return KNOWN_FAILURES_ENTRY;
 

package/lib/runner/template.mjs

@@ -85,14 +85,14 @@ export function buildPortMap(runtimeConfigs, runtimeId, namespace = {}) {
     if (actualPort > 65_535) {
       throw new Error(
         `Runtime port resolution exceeded 65535 for service "${config.name}" (${actualPort}). ` +
-          `Reduce runtime instances or choose lower local.port/baseUrl ports in testkit.setup.ts.`
+          `Reduce runtime instances or choose lower local.port/baseUrl ports in testkit.config.ts.`
       );
     }
     const existing = seen.get(actualPort);
     if (existing) {
       throw new Error(
         `Runtime port collision: services "${existing}" and "${config.name}" both resolve to ${actualPort}. ` +
-          `Assign distinct local.port/baseUrl ports in testkit.setup.ts.`
+          `Assign distinct local.port/baseUrl ports in testkit.config.ts.`
       );
     }
     seen.set(actualPort, config.name);

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

@@ -16,7 +16,7 @@ import {
   clearRuntimeContext,
   registerRuntimeContext,
   resolveHttpProfile,
-} from "../../setup/runtime.mjs";
+} from "../../config-api/runtime.mjs";
 import { createScenarioRuntime } from "./scenario-runtime.js";
 
 export function defineScenarioSuite(configOrRun, maybeRun) {

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

@@ -16,7 +16,7 @@ import {
   clearRuntimeContext,
   registerRuntimeContext,
   resolveHttpProfile,
-} from "../../setup/runtime.mjs";
+} from "../../config-api/runtime.mjs";
 
 export function defineHttpSuite(configOrRun, maybeRun) {
   const { config, run } = normalizeSuiteArgs(configOrRun, maybeRun);

package/lib/shared/build-config.mjs

@@ -130,7 +130,7 @@ export function buildConfigToPrepare(build) {
       steps: [
         {
           kind: "module",
-          specifier: "@elench/testkit/setup/next-runtime-tsconfig#writeNextRuntimeTsconfig",
+          specifier: "@elench/testkit/config/next-runtime-tsconfig#writeNextRuntimeTsconfig",
           cwd: build.cwd || undefined,
           inputs: [],
         },

package/lib/shared/build-config.test.mjs

@@ -116,7 +116,7 @@ describe("shared build config helpers", () => {
       steps: [
         {
           kind: "module",
-          specifier: "@elench/testkit/setup/next-runtime-tsconfig#writeNextRuntimeTsconfig",
+          specifier: "@elench/testkit/config/next-runtime-tsconfig#writeNextRuntimeTsconfig",
           cwd: "frontend",
           inputs: [],
         },

package/lib/shared/configured-steps.test.mjs

@@ -82,14 +82,14 @@ describe("shared configured steps", () => {
       steps: [
         {
           kind: "module",
-          specifier: "@elench/testkit/setup/next-runtime-tsconfig#writeNextRuntimeTsconfig",
+          specifier: "@elench/testkit/config/next-runtime-tsconfig#writeNextRuntimeTsconfig",
           cwd: "frontend",
           inputs: [],
         },
       ],
     };
 
-    expect(isBareModuleSpecifier("@elench/testkit/setup/next-runtime-tsconfig")).toBe(true);
+    expect(isBareModuleSpecifier("@elench/testkit/config/next-runtime-tsconfig")).toBe(true);
     expect(collectConfiguredInputs(productDir, collection)).toEqual([]);
     expect(() =>
       validateConfiguredCollection({

package/lib/toolchains/index.mjs

@@ -29,12 +29,12 @@ export function nodeToolchain(options = {}) {
 export function normalizeToolchainRegistry(value) {
   if (value == null) return {};
   if (!value || typeof value !== "object" || Array.isArray(value)) {
-    throw new Error("testkit.setup.ts toolchains must be an object");
+    throw new Error("testkit.config.ts toolchains must be an object");
   }
 
   const normalized = {};
   for (const [name, config] of Object.entries(value)) {
-    normalized[name] = normalizeToolchainConfig(config, `testkit.setup.ts toolchains.${name}`);
+    normalized[name] = normalizeToolchainConfig(config, `testkit.config.ts toolchains.${name}`);
   }
   return normalized;
 }

package/lib/vitest/index.d.ts

@@ -0,0 +1,12 @@
+export interface VitestConfigOptions {
+  exclude?: string[];
+}
+
+export declare function defineConfig<T extends Record<string, unknown>>(
+  config: T,
+  options?: VitestConfigOptions
+): T & {
+  test: Record<string, unknown> & { exclude: string[] };
+};
+
+export declare function testkitExcludes(): string[];

package/lib/vitest/index.mjs

@@ -0,0 +1,31 @@
+const TESTKIT_SUITE_GLOBS = [
+  "**/*.int.testkit.ts",
+  "**/*.e2e.testkit.ts",
+  "**/*.scenario.testkit.ts",
+  "**/*.dal.testkit.ts",
+  "**/*.load.testkit.ts",
+  "**/*.pw.testkit.ts",
+];
+
+export function defineConfig(config = {}, options = {}) {
+  const test = {
+    ...(config.test || {}),
+  };
+  const exclude = new Set([
+    ...(Array.isArray(test.exclude) ? test.exclude : []),
+    ...(Array.isArray(options.exclude) ? options.exclude : []),
+    ...TESTKIT_SUITE_GLOBS,
+  ]);
+
+  return {
+    ...config,
+    test: {
+      ...test,
+      exclude: [...exclude],
+    },
+  };
+}
+
+export function testkitExcludes() {
+  return [...TESTKIT_SUITE_GLOBS];
+}

package/lib/vitest/index.test.mjs

@@ -0,0 +1,20 @@
+import { describe, expect, it } from "vitest";
+import { defineConfig, testkitExcludes } from "./index.mjs";
+
+describe("testkit vitest defineConfig", () => {
+  it("appends testkit suite excludes", () => {
+    const config = defineConfig({
+      test: {
+        exclude: ["dist"],
+      },
+    });
+
+    expect(config.test.exclude).toEqual(
+      expect.arrayContaining(["dist", "**/*.int.testkit.ts", "**/*.pw.testkit.ts"])
+    );
+  });
+
+  it("exports the default testkit excludes", () => {
+    expect(testkitExcludes()).toContain("**/*.scenario.testkit.ts");
+  });
+});

package/node_modules/@elench/next-analysis/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@elench/next-analysis",
-  "version": "0.1.69",
+  "version": "0.1.71",
   "description": "SWC-backed Next.js source analysis primitives for Erench tools",
   "type": "module",
   "exports": {

package/node_modules/@elench/testkit-bridge/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@elench/testkit-bridge",
-  "version": "0.1.69",
+  "version": "0.1.71",
   "description": "Browser bridge helpers for testkit",
   "type": "module",
   "main": "./dist/index.js",
@@ -22,7 +22,7 @@
     "typecheck": "tsc -p tsconfig.json --noEmit"
   },
   "dependencies": {
-    "@elench/testkit-protocol": "0.1.69"
+    "@elench/testkit-protocol": "0.1.71"
   },
   "private": false
 }

package/node_modules/@elench/testkit-protocol/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@elench/testkit-protocol",
-  "version": "0.1.69",
+  "version": "0.1.71",
   "description": "Shared browser protocol for testkit bridge and extension consumers",
   "type": "module",
   "main": "./dist/index.js",

package/node_modules/@elench/ts-analysis/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@elench/ts-analysis",
-  "version": "0.1.69",
+  "version": "0.1.71",
   "description": "TypeScript compiler-backed source analysis primitives for Erench tools",
   "type": "module",
   "exports": {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@elench/testkit",
-  "version": "0.1.69",
+  "version": "0.1.71",
   "description": "CLI for discovering and running local HTTP, DAL, and Playwright test suites",
   "type": "module",
   "workspaces": [
@@ -12,9 +12,25 @@
       "types": "./lib/index.d.ts",
       "default": "./lib/index.mjs"
     },
-    "./setup": {
-      "types": "./lib/setup/index.d.ts",
-      "default": "./lib/setup/index.mjs"
+    "./config": {
+      "types": "./lib/config-api/index.d.ts",
+      "default": "./lib/config-api/index.mjs"
+    },
+    "./drizzle": {
+      "types": "./lib/drizzle/index.d.ts",
+      "default": "./lib/drizzle/index.mjs"
+    },
+    "./env": {
+      "types": "./lib/env/index.d.ts",
+      "default": "./lib/env/index.mjs"
+    },
+    "./playwright": {
+      "types": "./lib/playwright/index.d.ts",
+      "default": "./lib/playwright/index.mjs"
+    },
+    "./vitest": {
+      "types": "./lib/vitest/index.d.ts",
+      "default": "./lib/vitest/index.mjs"
     },
     "./runtime": {
       "types": "./lib/runtime/index.d.ts",
@@ -64,10 +80,10 @@
     "vitest": "^3.2.4"
   },
   "dependencies": {
-    "@elench/next-analysis": "0.1.69",
-    "@elench/ts-analysis": "0.1.69",
-    "@elench/testkit-bridge": "0.1.69",
-    "@elench/testkit-protocol": "0.1.69",
+    "@elench/next-analysis": "0.1.71",
+    "@elench/ts-analysis": "0.1.71",
+    "@elench/testkit-bridge": "0.1.71",
+    "@elench/testkit-protocol": "0.1.71",
     "@babel/code-frame": "^7.29.0",
     "@oclif/core": "^4.10.6",
     "esbuild": "^0.25.11",