@elench/testkit 0.1.19 → 0.1.21

package/README.md

@@ -1,15 +1,11 @@
 # @elench/testkit
 
-CLI that reads `runner.manifest.json` plus `testkit.config.json` from a product repo, starts the required local services, provisions local Postgres isolation, and runs manifest-defined suites across `k6` and Playwright.
+CLI that reads `testkit.config.json` from a product repo, discovers `*.testkit.ts` files by convention, starts the required local services, provisions local Postgres isolation, and runs suites across `k6` and Playwright.
 
 ## Prerequisites
 
-```bash
-sudo snap install k6
-sudo apt-get install -y jq
-```
-
-For DAL suites, `@elench/testkit` ships its own `k6` SQL binary.
+`@elench/testkit` ships its own `k6` binary and uses it for both HTTP and DAL suites by default.
+If you need to force a different binary, set `TESTKIT_K6_BIN` to an absolute or relative path.
 
 Database isolation uses Docker-managed local Postgres containers. `testkit` creates and reuses template databases automatically, then clones per-worker databases from those templates for fast reruns. The default image is `pgvector/pgvector:pg16`.
 
@@ -41,6 +37,12 @@ npx @elench/testkit --jobs 2 --shard 2/3
 npx @elench/testkit frontend e2e -s auth
 npx @elench/testkit api int -s health
 
+# Exact file
+npx @elench/testkit int --file tests/api/integration/health.int.testkit.ts
+
+# Deterministic git-trackable status snapshot
+npx @elench/testkit int --write-status
+
 # Lifecycle
 npx @elench/testkit status
 npx @elench/testkit destroy
@@ -77,6 +79,12 @@ const suite = defineHttpSuite({ auth: clerkSessionAuth }, ({ req, setupData }) =
 `testkit` bundles these imports before invoking k6, so tests do not need
 generated `_testkit` files or direct package-manager path imports.
 
+If you need to override the packaged `k6` binary for local environment reasons:
+
+```bash
+TESTKIT_K6_BIN=/path/to/k6 npx @elench/testkit int
+```
+
 Legacy compatibility:
 
 - `testkit runtime install`
@@ -94,8 +102,9 @@ npx @elench/testkit --dir my-product api int -s health
 
 ## How it works
 
-1. **Discovery** — reads `runner.manifest.json` for services, suites, files, and frameworks
-2. **Config** — reads `testkit.config.json` for local runtime, migration, dependency, and database settings
+1. **Discovery** — reads `testkit.config.json` for services, then discovers files by suffix:
+   `*.int.testkit.ts`, `*.e2e.testkit.ts`, `*.dal.testkit.ts`, `*.load.testkit.ts`, `*.pw.testkit.ts`
+2. **Config** — reads `testkit.config.json` for local runtime, migration, dependency, database, and discovery settings
    Per-service `.env` files declared in config are loaded when present.
 3. **Database** — provisions Docker-managed local Postgres when a service declares one
 4. **Seed** — runs optional product seed commands against the provisioned database
@@ -105,16 +114,17 @@ npx @elench/testkit --dir my-product api int -s health
 
 Each run ends with a compact summary that shows per-service pass/fail status, suite totals, failed suites, and total duration.
 
-`testkit` also writes `.testkit/results/latest.json` for every run. When `testkit.config.json` includes a top-level `telemetry` block, it can best-effort upload that artifact to a configured HTTP endpoint with bearer auth.
+`testkit` also writes `.testkit/results/latest.json` for every run. With `--write-status`, it writes a deterministic `testkit.status.json` snapshot that is suitable for git tracking. When `testkit.config.json` includes a top-level `telemetry` block, it can best-effort upload the richer run artifact to a configured HTTP endpoint with bearer auth.
 
 ## File roles
 
-- `runner.manifest.json`: canonical test inventory
 - `testkit.config.json`: local execution and provisioning config
+- `testkit.status.json`: optional deterministic run snapshot written by `--write-status`
 
 `testkit.config.json` can also declare:
 
 - `telemetry` for optional generic HTTP result upload
+- `discovery.include` / `discovery.exclude` for per-service test discovery
 - `envFile` / `envFiles` for service-specific environment loading
 - `databaseFrom` for dependency services that must share another service's `DATABASE_URL`
 - `database.provider` for local Postgres settings
@@ -139,24 +149,6 @@ Use `--shard <i/n>` to split the selected suite set deterministically before wor
 
 `testkit` also writes `.testkit/timings.json` and uses those file timings on later runs for longest-first balancing.
 
-## Suite metadata
-
-`runner.manifest.json` remains the source of truth for suites. Optional per-suite `testkit` metadata can tune execution:
-
-```json
-{
-  "name": "health",
-  "files": ["tests/example.js"],
-  "testkit": {
-    "maxFileConcurrency": 2,
-    "weight": 3
-  }
-}
-```
-
-- `maxFileConcurrency`: k6-only opt-in for batching multiple files from the same suite onto one worker
-- `weight`: optional fallback scheduling weight when no file timing history exists yet
-
 ## Schema
 
 See [testkit-config-schema.md](testkit-config-schema.md).
@@ -173,5 +165,4 @@ npm run test:system
 `test:system` runs real end-to-end fixtures from `test/fixtures/system/`. It requires:
 
 - Docker with a running daemon
-- `k6` on `PATH`
 - Playwright Chromium browser assets available to `@playwright/test`

package/lib/cli/index.mjs

@@ -41,6 +41,7 @@ export function run() {
   cli
     .command("[first] [second] [third]", "Run test suites (int, e2e, dal, all)")
     .option("-s, --suite <name>", "Run specific suite(s)", { default: [] })
+    .option("-f, --file <path>", "Run specific file(s)", { default: [] })
     .option("--dir <path>", "Explicit product directory")
     .option("--jobs <n>", "Number of isolated worker stacks for the whole run", {
       default: "1",
@@ -49,6 +50,7 @@ export function run() {
     .option("--framework <name>", "Filter by framework (k6, playwright, all)", {
       default: "all",
     })
+    .option("--write-status", "Write a deterministic testkit.status.json snapshot")
     .action(async (first, second, third, options) => {
       // Resolve: service filter, suite type, and --dir.
       //
@@ -96,12 +98,14 @@ export function run() {
 
       const suiteType = type || "all";
       const suiteNames = Array.isArray(options.suite) ? options.suite : [options.suite].filter(Boolean);
+      const fileNames = Array.isArray(options.file) ? options.file : [options.file].filter(Boolean);
       await runner.runAll(
         configs,
         suiteType,
         suiteNames,
         {
           ...options,
+          fileNames,
           jobs,
           shard,
         },

package/lib/config/discovery.mjs

@@ -0,0 +1,156 @@
+import fs from "fs";
+import path from "path";
+
+const DISCOVERY_RULES = [
+  { suffix: ".int.testkit.ts", type: "integration", framework: "k6" },
+  { suffix: ".e2e.testkit.ts", type: "e2e", 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" },
+];
+
+export function discoverServiceSuites(productDir, serviceName, serviceConfig) {
+  const include = serviceConfig.discovery?.include || [];
+  const exclude = serviceConfig.discovery?.exclude || [];
+  const grouped = {};
+  const seen = new Set();
+
+  for (const pattern of include) {
+    const normalizedPattern = normalizePath(pattern);
+    const patternInfo = compilePattern(normalizedPattern);
+    const rootDir = path.resolve(productDir, patternInfo.baseDir);
+    if (!fs.existsSync(rootDir)) continue;
+
+    for (const relativeFile of walkFiles(productDir, rootDir)) {
+      const normalizedFile = normalizePath(relativeFile);
+      if (!patternInfo.regex.test(normalizedFile)) continue;
+      if (exclude.some((candidate) => compilePattern(normalizePath(candidate)).regex.test(normalizedFile))) {
+        continue;
+      }
+      if (seen.has(normalizedFile)) continue;
+
+      const rule = inferRule(normalizedFile);
+      if (!rule) continue;
+
+      const typeSuites = grouped[rule.type] || [];
+      typeSuites.push({
+        name: buildSuiteName(normalizedFile, rule.suffix, patternInfo.baseDir),
+        files: [normalizedFile],
+        framework: rule.framework,
+      });
+      grouped[rule.type] = typeSuites;
+      seen.add(normalizedFile);
+    }
+  }
+
+  for (const suites of Object.values(grouped)) {
+    suites.sort((left, right) => left.files[0].localeCompare(right.files[0]));
+  }
+
+  return grouped;
+}
+
+function inferRule(filePath) {
+  return DISCOVERY_RULES.find((rule) => filePath.endsWith(rule.suffix)) || null;
+}
+
+function buildSuiteName(filePath, suffix, baseDir) {
+  const normalizedBase = normalizePath(baseDir);
+  const relativeToBase =
+    normalizedBase === "." || normalizedBase.length === 0
+      ? filePath
+      : path.posix.relative(normalizedBase, filePath);
+  const candidate = relativeToBase.length > 0 ? relativeToBase : path.posix.basename(filePath);
+  return candidate.slice(0, -suffix.length);
+}
+
+function walkFiles(productDir, rootDir) {
+  const rootStats = fs.statSync(rootDir);
+  if (rootStats.isFile()) {
+    return [normalizePath(path.relative(productDir, rootDir))];
+  }
+
+  const files = [];
+  const queue = [rootDir];
+
+  while (queue.length > 0) {
+    const current = queue.pop();
+    for (const entry of fs.readdirSync(current, { withFileTypes: true })) {
+      const absolute = path.join(current, entry.name);
+      if (entry.isDirectory()) {
+        queue.push(absolute);
+        continue;
+      }
+      if (!entry.isFile()) continue;
+      files.push(normalizePath(path.relative(productDir, absolute)));
+    }
+  }
+
+  return files.sort((left, right) => left.localeCompare(right));
+}
+
+function compilePattern(pattern) {
+  const baseDir = patternBase(pattern);
+  return {
+    baseDir,
+    regex: globToRegExp(pattern),
+  };
+}
+
+function patternBase(pattern) {
+  const parts = pattern.split("/");
+  const baseParts = [];
+
+  for (const part of parts) {
+    if (/[?*\[]/.test(part)) break;
+    baseParts.push(part);
+  }
+
+  return baseParts.length > 0 ? baseParts.join("/") : ".";
+}
+
+function globToRegExp(pattern) {
+  let source = "^";
+
+  for (let index = 0; index < pattern.length; index += 1) {
+    const current = pattern[index];
+    const next = pattern[index + 1];
+    const afterNext = pattern[index + 2];
+
+    if (current === "*" && next === "*" && afterNext === "/") {
+      source += "(?:.*/)?";
+      index += 2;
+      continue;
+    }
+
+    if (current === "*" && next === "*") {
+      source += ".*";
+      index += 1;
+      continue;
+    }
+
+    if (current === "*") {
+      source += "[^/]*";
+      continue;
+    }
+
+    if (current === "?") {
+      source += "[^/]";
+      continue;
+    }
+
+    if ("\\.[]{}()+-^$|".includes(current)) {
+      source += `\\${current}`;
+      continue;
+    }
+
+    source += current;
+  }
+
+  source += "$";
+  return new RegExp(source);
+}
+
+function normalizePath(value) {
+  return value.split(path.sep).join("/");
+}

package/lib/config/discovery.test.mjs

@@ -0,0 +1,44 @@
+import fs from "fs";
+import os from "os";
+import path from "path";
+import { afterEach, describe, expect, it } from "vitest";
+import { discoverServiceSuites } from "./discovery.mjs";
+
+const cleanups = [];
+
+afterEach(() => {
+  while (cleanups.length > 0) {
+    cleanups.pop()();
+  }
+});
+
+describe("config-discovery", () => {
+  it("discovers exact-file includes with stable suite names", () => {
+    const productDir = fs.mkdtempSync(path.join(os.tmpdir(), "testkit-discovery-"));
+    cleanups.push(() => fs.rmSync(productDir, { recursive: true, force: true }));
+
+    const filePath = path.join(
+      productDir,
+      "tests",
+      "api",
+      "integration",
+      "health.int.testkit.ts"
+    );
+    fs.mkdirSync(path.dirname(filePath), { recursive: true });
+    fs.writeFileSync(filePath, "export {};\n");
+
+    const suites = discoverServiceSuites(productDir, "api", {
+      discovery: {
+        include: ["tests/api/integration/health.int.testkit.ts"],
+      },
+    });
+
+    expect(suites.integration).toEqual([
+      {
+        name: "health",
+        files: ["tests/api/integration/health.int.testkit.ts"],
+        framework: "k6",
+      },
+    ]);
+  });
+});

package/lib/config/index.mjs

@@ -1,28 +1,21 @@
 import fs from "fs";
 import path from "path";
 import { fileURLToPath } from "url";
+import { discoverServiceSuites } from "./discovery.mjs";
 import {
   getServiceEnvFiles as getServiceEnvFilesModel,
-  isDalSuiteType as isDalSuiteTypeModel,
   isObject as isObjectModel,
   normalizeTelemetryConfig as normalizeTelemetryConfigModel,
-  normalizeTemplateConfig as normalizeTemplateConfigModel,
   parseDotenvString,
-  requireString as requireStringModel,
   resolveLifecycleConfig as resolveLifecycleConfigModel,
   resolveSelectedDatabase as resolveSelectedDatabaseModel,
   validateConfigCoverage as validateConfigCoverageModel,
-  validateDatabaseProviderConfig as validateDatabaseProviderConfigModel,
-  validateHttpUrl as validateHttpUrlModel,
-  validateLifecycleConfig as validateLifecycleConfigModel,
-  validateRunnerManifest,
   validateServiceConfig as validateServiceConfigModel,
   validateTelemetryConfig as validateTelemetryConfigModel,
-  validateTemplateConfig as validateTemplateConfigModel,
 } from "./model.mjs";
 
-const RUNNER_MANIFEST = "runner.manifest.json";
 const TESTKIT_CONFIG = "testkit.config.json";
+const TESTKIT_K6_BIN = "TESTKIT_K6_BIN";
 export function parseDotenv(filePath) {
   if (!fs.existsSync(filePath)) return {};
   return parseDotenvString(fs.readFileSync(filePath, "utf8"));
@@ -30,20 +23,19 @@ export function parseDotenv(filePath) {
 
 export function getServiceNames(cwd) {
   const dir = cwd || process.cwd();
-  const runnerPath = path.join(dir, RUNNER_MANIFEST);
-  if (!fs.existsSync(runnerPath)) return [];
-  const runner = JSON.parse(fs.readFileSync(runnerPath, "utf8"));
-  if (!isObject(runner.services)) return [];
-  return Object.keys(runner.services);
+  const configPath = path.join(dir, TESTKIT_CONFIG);
+  if (!fs.existsSync(configPath)) return [];
+  const config = JSON.parse(fs.readFileSync(configPath, "utf8"));
+  if (!isObject(config.services)) return [];
+  return Object.keys(config.services);
 }
 
 export function loadConfigs(opts = {}) {
   const productDir = resolveProductDir(process.cwd(), opts.dir);
-  const runner = loadRunnerManifest(productDir);
   const config = loadTestkitConfig(productDir);
-  validateConfigCoverage(runner, config);
+  validateConfigCoverage(config);
 
-  const serviceEntries = Object.entries(runner.services);
+  const serviceEntries = Object.entries(config.services);
   const filtered = opts.service
     ? serviceEntries.filter(([name]) => name === opts.service)
     : serviceEntries;
@@ -53,14 +45,8 @@ export function loadConfigs(opts = {}) {
     throw new Error(`Service "${opts.service}" not found. Available: ${available}`);
   }
 
-  return filtered.map(([name, runnerService]) => {
-    const serviceConfig = config.services[name];
-    if (!serviceConfig) {
-      throw new Error(
-        `Service "${name}" exists in ${RUNNER_MANIFEST} but is missing from ${TESTKIT_CONFIG}`
-      );
-    }
-
+  return filtered.map(([name, serviceConfig]) => {
+    const suites = discoverServiceSuites(productDir, name, serviceConfig);
     const resolvedDatabase = resolveSelectedDatabase(name, serviceConfig);
     const serviceEnv = loadServiceEnv(productDir, serviceConfig);
     const selectedBackend = resolvedDatabase?.selectedBackend;
@@ -68,7 +54,7 @@ export function loadConfigs(opts = {}) {
     const resolvedSeed = resolveLifecycleConfig(serviceConfig.seed, selectedBackend);
     validateMergedService(
       name,
-      runnerService,
+      suites,
       serviceConfig,
       resolvedDatabase,
       resolvedMigrate,
@@ -81,7 +67,7 @@ export function loadConfigs(opts = {}) {
       productDir,
       stateDir: path.join(productDir, ".testkit", name),
       telemetry: normalizeTelemetryConfig(config.telemetry),
-      suites: runnerService.suites,
+      suites,
       testkit: {
         ...serviceConfig,
         database: resolvedDatabase,
@@ -94,24 +80,37 @@ export function loadConfigs(opts = {}) {
   });
 }
 
-export function resolveDalBinary() {
+export function resolveK6Binary() {
+  const override = process.env[TESTKIT_K6_BIN]?.trim();
+  if (override) {
+    const isPathLike =
+      path.isAbsolute(override) ||
+      override.includes(path.sep) ||
+      override.includes(path.posix.sep) ||
+      override.includes(path.win32.sep);
+    const overridePath = isPathLike ? path.resolve(process.cwd(), override) : override;
+
+    if (isPathLike && !fs.existsSync(overridePath)) {
+      throw new Error(`${TESTKIT_K6_BIN} points to a missing file: ${overridePath}`);
+    }
+
+    return overridePath;
+  }
+
   const thisFile = fileURLToPath(import.meta.url);
   const abs = path.resolve(path.dirname(thisFile), "..", "..", "vendor", "k6");
   if (!fs.existsSync(abs)) {
-    throw new Error(`Bundled DAL k6 binary not found: ${abs}`);
+    throw new Error(`Bundled k6 binary not found: ${abs}`);
   }
   return abs;
 }
 
-export function resolveServiceCwd(productDir, maybeRelative) {
-  return path.resolve(productDir, maybeRelative || ".");
+export function resolveDalBinary() {
+  return resolveK6Binary();
 }
 
-function loadRunnerManifest(productDir) {
-  const manifestPath = path.join(productDir, RUNNER_MANIFEST);
-  const raw = JSON.parse(fs.readFileSync(manifestPath, "utf8"));
-  validateRunnerManifest(raw, RUNNER_MANIFEST, manifestPath);
-  return raw;
+export function resolveServiceCwd(productDir, maybeRelative) {
+  return path.resolve(productDir, maybeRelative || ".");
 }
 
 function loadTestkitConfig(productDir) {
@@ -133,8 +132,8 @@ function loadTestkitConfig(productDir) {
   return raw;
 }
 
-function validateConfigCoverage(runner, config) {
-  return validateConfigCoverageModel(runner, config, TESTKIT_CONFIG, RUNNER_MANIFEST);
+function validateConfigCoverage(config) {
+  return validateConfigCoverageModel(config, TESTKIT_CONFIG);
 }
 
 function resolveProductDir(cwd, explicitDir) {
@@ -149,7 +148,7 @@ function resolveProductDir(cwd, explicitDir) {
 }
 
 function ensureProductFiles(dir) {
-  const missing = [RUNNER_MANIFEST, TESTKIT_CONFIG].filter(
+  const missing = [TESTKIT_CONFIG].filter(
     (file) => !fs.existsSync(path.join(dir, file))
   );
   if (missing.length > 0) {
@@ -161,18 +160,16 @@ function ensureProductFiles(dir) {
 
 function validateMergedService(
   name,
-  runnerService,
+  suites,
   serviceConfig,
   resolvedDatabase,
   resolvedMigrate,
   resolvedSeed,
   productDir
 ) {
-  const usesLocalExecution = Object.values(runnerService.suites).some((suites) =>
-    suites.some(
-      (suite) =>
-        (suite.framework && suite.framework !== "k6") ||
-        !isDalSuiteType(suite, runnerService, suites)
+  const usesLocalExecution = Object.entries(suites).some(([suiteType, discoveredSuites]) =>
+    discoveredSuites.some(
+      (suite) => (suite.framework && suite.framework !== "k6") || suiteType !== "dal"
     )
   );
 
@@ -228,15 +225,6 @@ function validateMergedService(
   }
 
 }
-
-function validateServiceConfig(name, service, configPath) {
-  return validateServiceConfigModel(name, service, configPath);
-}
-
-function validateTelemetryConfig(telemetry, configPath) {
-  return validateTelemetryConfigModel(telemetry, configPath, TESTKIT_CONFIG);
-}
-
 function loadServiceEnv(productDir, serviceConfig) {
   const env = {};
   for (const envFile of getServiceEnvFiles(serviceConfig)) {
@@ -253,34 +241,10 @@ function resolveSelectedDatabase(name, serviceConfig) {
   return resolveSelectedDatabaseModel(name, serviceConfig);
 }
 
-function validateDatabaseProviderConfig(name, db, label) {
-  return validateDatabaseProviderConfigModel(name, db, label);
-}
-
-function validateTemplateConfig(name, template, label) {
-  return validateTemplateConfigModel(name, template, label);
-}
-
-function normalizeTemplateConfig(template) {
-  return normalizeTemplateConfigModel(template);
-}
-
-function validateLifecycleConfig(name, value, label) {
-  return validateLifecycleConfigModel(name, value, label);
-}
-
 function resolveLifecycleConfig(value, selectedBackend) {
   return resolveLifecycleConfigModel(value, selectedBackend);
 }
 
-function requireString(obj, key, label) {
-  return requireStringModel(obj, key, label);
-}
-
-function isDalSuiteType(suite, runnerService, suitesForType) {
-  return isDalSuiteTypeModel(suite, runnerService, suitesForType);
-}
-
 function isObject(value) {
   return isObjectModel(value);
 }
@@ -288,7 +252,3 @@ function isObject(value) {
 function normalizeTelemetryConfig(telemetry) {
   return normalizeTelemetryConfigModel(telemetry);
 }
-
-function validateHttpUrl(value, label) {
-  return validateHttpUrlModel(value, label);
-}

package/lib/config/index.test.mjs

@@ -1,12 +1,44 @@
 import fs from "fs";
 import path from "path";
-import { describe, expect, it } from "vitest";
-import { resolveDalBinary } from "./index.mjs";
+import os from "os";
+import { afterEach, describe, expect, it } from "vitest";
+import { resolveDalBinary, resolveK6Binary } from "./index.mjs";
+
+const originalK6Bin = process.env.TESTKIT_K6_BIN;
+
+afterEach(() => {
+  if (originalK6Bin === undefined) {
+    delete process.env.TESTKIT_K6_BIN;
+  } else {
+    process.env.TESTKIT_K6_BIN = originalK6Bin;
+  }
+});
 
 describe("config-index", () => {
-  it("resolves the bundled DAL k6 binary from the package root", () => {
-    const binaryPath = resolveDalBinary();
+  it("resolves the bundled k6 binary from the package root", () => {
+    const binaryPath = resolveK6Binary();
     expect(path.basename(binaryPath)).toBe("k6");
     expect(fs.existsSync(binaryPath)).toBe(true);
   });
+
+  it("keeps resolveDalBinary aligned with the shared k6 resolver", () => {
+    expect(resolveDalBinary()).toBe(resolveK6Binary());
+  });
+
+  it("uses TESTKIT_K6_BIN when provided with a relative path", () => {
+    const tempDir = fs.mkdtempSync(path.join(os.tmpdir(), "testkit-k6-"));
+    const binPath = path.join(tempDir, "k6-custom");
+    fs.writeFileSync(binPath, "#!/usr/bin/env bash\nexit 0\n");
+    process.env.TESTKIT_K6_BIN = path.relative(process.cwd(), binPath);
+
+    expect(resolveK6Binary()).toBe(binPath);
+  });
+
+  it("throws a clear error when TESTKIT_K6_BIN points at a missing path", () => {
+    process.env.TESTKIT_K6_BIN = "./definitely-missing-k6-bin";
+
+    expect(() => resolveK6Binary()).toThrow(
+      /TESTKIT_K6_BIN points to a missing file/
+    );
+  });
 });

package/lib/config/model.mjs

@@ -110,43 +110,23 @@ export function validateRunnerManifest(raw, manifestName = "runner.manifest.json
 }
 
 export function validateConfigCoverage(
-  runner,
   config,
-  configName = "testkit.config.json",
-  manifestName = "runner.manifest.json"
+  configName = "testkit.config.json"
 ) {
   for (const serviceName of Object.keys(config.services || {})) {
-    if (!runner.services[serviceName]) {
-      throw new Error(
-        `Service "${serviceName}" exists in ${configName} but not in ${manifestName}`
-      );
-    }
-
     for (const depName of config.services[serviceName].dependsOn || []) {
       if (!config.services[depName]) {
         throw new Error(
           `Service "${serviceName}" depends on "${depName}", but ${depName} is missing from ${configName}`
         );
       }
-      if (!runner.services[depName]) {
-        throw new Error(
-          `Service "${serviceName}" depends on "${depName}", but ${depName} is missing from ${manifestName}`
-        );
-      }
     }
 
     const databaseFrom = config.services[serviceName].databaseFrom;
-    if (databaseFrom) {
-      if (!config.services[databaseFrom]) {
-        throw new Error(
-          `Service "${serviceName}" databaseFrom "${databaseFrom}" is missing from ${configName}`
-        );
-      }
-      if (!runner.services[databaseFrom]) {
-        throw new Error(
-          `Service "${serviceName}" databaseFrom "${databaseFrom}" is missing from ${manifestName}`
-        );
-      }
+    if (databaseFrom && !config.services[databaseFrom]) {
+      throw new Error(
+        `Service "${serviceName}" databaseFrom "${databaseFrom}" is missing from ${configName}`
+      );
     }
   }
 }
@@ -231,6 +211,26 @@ export function validateServiceConfig(name, service, configPath) {
       throw new Error(`Service "${name}" local.env must be an object`);
     }
   }
+
+  if (service.discovery !== undefined) {
+    if (!isObject(service.discovery)) {
+      throw new Error(`Service "${name}" discovery must be an object`);
+    }
+    if (
+      service.discovery.include !== undefined &&
+      (!Array.isArray(service.discovery.include) ||
+        service.discovery.include.some((value) => typeof value !== "string" || value.length === 0))
+    ) {
+      throw new Error(`Service "${name}" discovery.include must be an array of glob strings`);
+    }
+    if (
+      service.discovery.exclude !== undefined &&
+      (!Array.isArray(service.discovery.exclude) ||
+        service.discovery.exclude.some((value) => typeof value !== "string" || value.length === 0))
+    ) {
+      throw new Error(`Service "${name}" discovery.exclude must be an array of glob strings`);
+    }
+  }
 }
 
 export function validateTelemetryConfig(

package/lib/config/model.test.mjs

@@ -60,11 +60,6 @@ QUX='zap'
   });
 
   it("validates config coverage", () => {
-    const runner = {
-      services: {
-        api: { suites: {} },
-      },
-    };
     const config = {
       services: {
         frontend: {
@@ -73,8 +68,8 @@ QUX='zap'
       },
     };
 
-    expect(() => validateConfigCoverage(runner, config)).toThrow(
-      'Service "frontend" exists in testkit.config.json but not in runner.manifest.json'
+    expect(() => validateConfigCoverage(config)).toThrow(
+      'Service "frontend" depends on "api", but api is missing from testkit.config.json'
     );
   });
 
@@ -98,6 +93,14 @@ QUX='zap'
       }, "testkit.config.json")
     ).toThrow("database.backends is no longer supported");
 
+    expect(() =>
+      validateServiceConfig("api", {
+        discovery: {
+          include: "tests/**/*.int.testkit.ts",
+        },
+      }, "testkit.config.json")
+    ).toThrow("discovery.include must be an array of glob strings");
+
     expect(() =>
       validateTelemetryConfig(
         {

package/lib/runner/index.mjs

@@ -2,9 +2,10 @@ import fs from "fs";
 import path from "path";
 import { spawn } from "child_process";
 import net from "net";
+import { pathToFileURL } from "url";
 import { execa, execaCommand } from "execa";
 import { bundleK6File } from "../bundler/index.mjs";
-import { resolveDalBinary, resolveServiceCwd } from "../config/index.mjs";
+import { resolveK6Binary, resolveServiceCwd } from "../config/index.mjs";
 import {
   cleanupOrphanedLocalInfrastructure,
   destroyRuntimeDatabase,
@@ -45,6 +46,7 @@ import {
 import {
   addTrackerError as addTrackerErrorModel,
   buildRunArtifact as buildRunArtifactModel,
+  buildStatusArtifact as buildStatusArtifactModel,
   buildServiceTrackers as buildServiceTrackersModel,
   finalizeServiceResult as finalizeServiceResultModel,
   formatDuration as formatDurationModel,
@@ -97,13 +99,21 @@ export async function runAll(configs, suiteType, suiteNames, opts, allConfigs =
   const configMap = new Map(allConfigs.map((config) => [config.name, config]));
   const startedAt = Date.now();
   const telemetry = configs[0]?.telemetry || null;
+  const productDir = configs[0]?.productDir || process.cwd();
+  const metadata = {
+    git: collectGitMetadata(productDir),
+    host: {
+      hostname: safeHostname(),
+      username: safeUsername(),
+    },
+    testkitVersion: readPackageMetadata().version,
+  };
   const servicePlans = collectServicePlans(configs, configMap, suiteType, suiteNames, opts);
   const trackers = buildServiceTrackers(servicePlans, startedAt);
   const executedPlans = servicePlans.filter((plan) => !plan.skipped);
   let workerCount = 0;
 
   if (executedPlans.length > 0) {
-    const productDir = executedPlans[0].config.productDir;
     const timings = loadTimings(productDir);
     const graphs = buildRuntimeGraphs(executedPlans);
     const queue = buildTaskQueue(executedPlans, graphs, timings);
@@ -137,7 +147,7 @@ export async function runAll(configs, suiteType, suiteNames, opts, allConfigs =
     finalizeServiceResult(trackers.get(config.name), startedAt, finishedAt)
   );
   const artifact = buildRunArtifact({
-    productDir: configs[0]?.productDir || process.cwd(),
+    productDir,
     results,
     startedAt,
     finishedAt,
@@ -145,12 +155,30 @@ export async function runAll(configs, suiteType, suiteNames, opts, allConfigs =
     workerCount,
     suiteType,
     suiteNames,
+    fileNames: opts.fileNames || [],
     framework: opts.framework || "all",
     shard: opts.shard || null,
     serviceFilter: configs.length === 1 ? configs[0].name : null,
+    metadata,
   });
 
-  writeRunArtifact(configs[0]?.productDir || process.cwd(), artifact);
+  writeRunArtifact(productDir, artifact);
+  if (opts.writeStatus) {
+    writeStatusArtifact(
+      productDir,
+      buildStatusArtifact({
+        productDir,
+        results,
+        suiteType,
+        suiteNames,
+        fileNames: opts.fileNames || [],
+        framework: opts.framework || "all",
+        shard: opts.shard || null,
+        serviceFilter: configs.length === 1 ? configs[0].name : null,
+        metadata,
+      })
+    );
+  }
 
   printRunSummary(results, finishedAt - startedAt);
   await reportTelemetry(telemetry, artifact);
@@ -201,13 +229,13 @@ function collectServicePlans(configs, configMap, suiteType, suiteNames, opts) {
   return configs.map((config) => {
     console.log(`\n══ ${config.name} ══`);
     const suites = applyShard(
-      collectSuites(config, suiteType, suiteNames, opts.framework),
+      collectSuites(config, suiteType, suiteNames, opts.framework, opts.fileNames || []),
       opts.shard
     );
 
     if (suites.length === 0) {
       console.log(
-        `No test files for ${config.name} type="${suiteType}" suites=${suiteNames.join(",") || "all"} — skipping`
+        `No test files for ${config.name} type="${suiteType}" suites=${suiteNames.join(",") || "all"} files=${(opts.fileNames || []).join(",") || "all"} — skipping`
       );
       return {
         config,
@@ -521,6 +549,7 @@ async function runHttpK6Batch(targetConfig, batch) {
 
 async function runHttpK6Task(targetConfig, task, baseUrl) {
   const absFile = path.join(targetConfig.productDir, task.file);
+  const k6Binary = resolveK6Binary();
   const bundledFile = await bundleK6File({
     productDir: targetConfig.productDir,
     serviceName: targetConfig.name,
@@ -529,7 +558,7 @@ async function runHttpK6Task(targetConfig, task, baseUrl) {
   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}`, bundledFile], {
+    await execa(k6Binary, ["run", "--address", "127.0.0.1:0", "-e", `BASE_URL=${baseUrl}`, bundledFile], {
       cwd: targetConfig.productDir,
       env: buildExecutionEnv(targetConfig),
       stdio: "inherit",
@@ -567,7 +596,7 @@ async function runDalBatch(targetConfig, batch) {
 
 async function runDalTask(targetConfig, task, databaseUrl) {
   const absFile = path.join(targetConfig.productDir, task.file);
-  const k6Binary = resolveDalBinary();
+  const k6Binary = resolveK6Binary();
   const bundledFile = await bundleK6File({
     productDir: targetConfig.productDir,
     serviceName: targetConfig.name,
@@ -617,10 +646,11 @@ async function runPlaywrightBatch(targetConfig, batch) {
   const requestedFiles = batch.tasks.map((task) =>
     path.relative(cwd, path.join(targetConfig.productDir, task.file))
   );
+  const playwrightConfigPath = ensurePlaywrightTestConfig(targetConfig, cwd, requestedFiles);
   const startedAt = Date.now();
   const result = await execa(
     "npx",
-    ["playwright", "test", "--reporter=json", ...requestedFiles],
+    ["playwright", "test", "--config", playwrightConfigPath, "--reporter=json", ...requestedFiles],
     {
       cwd,
       env: buildPlaywrightEnv(targetConfig, local.baseUrl),
@@ -723,8 +753,8 @@ function resolveRuntimeConfigs(targetConfig, configMap) {
   return resolveRuntimeConfigsModel(targetConfig, configMap);
 }
 
-function collectSuites(config, suiteType, suiteNames, frameworkFilter) {
-  return collectSuitesModel(config, suiteType, suiteNames, frameworkFilter);
+function collectSuites(config, suiteType, suiteNames, frameworkFilter, fileNames = []) {
+  return collectSuitesModel(config, suiteType, suiteNames, frameworkFilter, fileNames);
 }
 
 function applyShard(suites, shard) {
@@ -890,9 +920,11 @@ function buildRunArtifact({
   workerCount,
   suiteType,
   suiteNames,
+  fileNames,
   framework,
   shard,
   serviceFilter,
+  metadata,
 }) {
   return buildRunArtifactModel({
     productDir,
@@ -903,17 +935,11 @@ function buildRunArtifact({
     workerCount,
     suiteType,
     suiteNames,
+    fileNames,
     framework,
     shard,
     serviceFilter,
-    metadata: {
-      git: collectGitMetadata(productDir),
-      host: {
-        hostname: safeHostname(),
-        username: safeUsername(),
-      },
-      testkitVersion: readPackageMetadata().version,
-    },
+    metadata,
   });
 }
 
@@ -923,6 +949,73 @@ function writeRunArtifact(productDir, artifact) {
   fs.writeFileSync(path.join(resultsDir, "latest.json"), JSON.stringify(artifact, null, 2));
 }
 
+function buildStatusArtifact({
+  productDir,
+  results,
+  metadata,
+}) {
+  return buildStatusArtifactModel({
+    productDir,
+    results,
+    metadata,
+  });
+}
+
+function writeStatusArtifact(productDir, artifact) {
+  fs.writeFileSync(
+    path.join(productDir, "testkit.status.json"),
+    `${JSON.stringify(artifact, null, 2)}\n`
+  );
+}
+
+function ensurePlaywrightTestConfig(targetConfig, cwd, requestedFiles) {
+  const stateDir = targetConfig.stateDir || path.join(targetConfig.productDir, ".testkit");
+  fs.mkdirSync(stateDir, { recursive: true });
+  const configPath = path.join(stateDir, "playwright.testkit.config.mjs");
+  const baseConfigPath = findPlaywrightConfig(cwd);
+  const normalizedFiles = requestedFiles.map(normalizePathSeparators);
+
+  let source = "";
+  if (baseConfigPath) {
+    source = `import baseConfig from ${JSON.stringify(pathToFileURL(baseConfigPath).href)};\n` +
+      `const resolvedBase = typeof baseConfig === "function" ? await baseConfig() : baseConfig;\n` +
+      `export default {\n` +
+      `  ...(resolvedBase || {}),\n` +
+      `  testDir: ${JSON.stringify(cwd)},\n` +
+      `  testMatch: ${JSON.stringify(normalizedFiles)},\n` +
+      `};\n`;
+  } else {
+    source =
+      `export default {\n` +
+      `  testDir: ${JSON.stringify(cwd)},\n` +
+      `  testMatch: ${JSON.stringify(normalizedFiles)},\n` +
+      `};\n`;
+  }
+
+  fs.writeFileSync(configPath, source);
+  return configPath;
+}
+
+function findPlaywrightConfig(cwd) {
+  const candidates = [
+    "playwright.config.ts",
+    "playwright.config.mts",
+    "playwright.config.js",
+    "playwright.config.mjs",
+    "playwright.config.cjs",
+    "playwright.config.cts",
+  ];
+
+  for (const candidate of candidates) {
+    const candidatePath = path.join(cwd, candidate);
+    if (fs.existsSync(candidatePath)) {
+      return candidatePath;
+    }
+  }
+
+  return null;
+}
+
 function summarizeDbBackend(results) {
   return summarizeDbBackendModel(results);
 }

package/lib/runner/planning.mjs

@@ -34,24 +34,31 @@ export function resolveRuntimeConfigs(targetConfig, configMap) {
   return ordered;
 }
 
-export function collectSuites(config, suiteType, suiteNames, frameworkFilter) {
+export function collectSuites(config, suiteType, suiteNames, frameworkFilter, fileNames = []) {
   const types =
     suiteType === "all"
       ? orderedTypes(Object.keys(config.suites))
       : [suiteType === "int" ? "integration" : suiteType];
 
   const selectedNames = new Set(suiteNames);
+  const selectedFiles = new Set(fileNames.map(normalizePathSeparators));
   const suites = [];
   let orderIndex = 0;
 
   for (const type of types) {
     for (const suite of config.suites[type] || []) {
       const framework = suite.framework || "k6";
+      const files =
+        selectedFiles.size === 0
+          ? suite.files
+          : suite.files.filter((file) => selectedFiles.has(normalizePathSeparators(file)));
       if (selectedNames.size > 0 && !selectedNames.has(suite.name)) continue;
       if (frameworkFilter && frameworkFilter !== "all" && framework !== frameworkFilter) continue;
+      if (files.length === 0) continue;
 
       suites.push({
         ...suite,
+        files,
         framework,
         type,
         orderIndex,
@@ -59,8 +66,8 @@ export function collectSuites(config, suiteType, suiteNames, frameworkFilter) {
         weight:
           suite.testkit?.weight ||
           (framework === "playwright"
-            ? Math.max(2, suite.files.length)
-            : Math.max(1, suite.files.length)),
+            ? Math.max(2, files.length)
+            : Math.max(1, files.length)),
         maxFileConcurrency:
           framework === "k6" ? suite.testkit?.maxFileConcurrency || 1 : 1,
       });
@@ -260,6 +267,10 @@ export function compareGraphsForAssignment(left, right) {
   return left.key.localeCompare(right.key);
 }
 
+function normalizePathSeparators(filePath) {
+  return String(filePath).split("\\").join("/");
+}
+
 export function buildGraphDirName(runtimeNames) {
   const slug = runtimeNames.map(slugSegment).join("__");
   return slug.length > 0 ? slug : "graph";

package/lib/runner/planning.test.mjs

@@ -42,10 +42,17 @@ describe("runner-planning", () => {
     const config = makeConfig("api", {
       suites: {
         integration: [
-          { name: "health", files: ["health.js"] },
+          { name: "health", files: ["tests/api/integration/health.int.testkit.ts"] },
         ],
         e2e: [
-          { name: "auth", framework: "playwright", files: ["auth.spec.js", "signup.spec.js"] },
+          {
+            name: "auth",
+            framework: "playwright",
+            files: [
+              "tests/frontend/e2e/auth.pw.testkit.ts",
+              "tests/frontend/e2e/signup.pw.testkit.ts",
+            ],
+          },
         ],
       },
     });
@@ -62,6 +69,19 @@ describe("runner-planning", () => {
       framework: "playwright",
       weight: 2,
     });
+
+    expect(
+      collectSuites(
+        config,
+        "all",
+        [],
+        "all",
+        ["tests/frontend/e2e/signup.pw.testkit.ts"]
+      )[0]
+    ).toMatchObject({
+      name: "auth",
+      files: ["tests/frontend/e2e/signup.pw.testkit.ts"],
+    });
   });
 
   it("applies shards, builds graphs, queues tasks, and claims batches", () => {

package/lib/runner/results.mjs

@@ -31,11 +31,34 @@ export function buildServiceTrackers(servicePlans, startedAt) {
       completedFileCount: 0,
       failedFiles: [],
       failedFileSet: new Set(),
-      fileResults: [],
-      fileResultsByPath: new Map(),
+      fileResults: suite.files.map((file) => ({
+        path: normalizePathSeparators(file),
+        failed: false,
+        durationMs: 0,
+        error: null,
+        status: "not_run",
+      })),
+      fileResultsByPath: new Map(
+        suite.files.map((file) => {
+          const normalizedPath = normalizePathSeparators(file);
+          return [
+            normalizedPath,
+            {
+              path: normalizedPath,
+              failed: false,
+              durationMs: 0,
+              error: null,
+              status: "not_run",
+            },
+          ];
+        })
+      ),
       durationMs: 0,
       error: null,
     }));
+    for (const suite of suites) {
+      suite.fileResults = [...suite.fileResultsByPath.values()];
+    }
 
     trackers.set(plan.config.name, {
       name: plan.config.name,
@@ -73,12 +96,14 @@ export function recordTaskOutcome(trackers, task, outcome, finishedAt = Date.now
     existingFileResult.failed = outcome.failed;
     existingFileResult.durationMs = outcome.durationMs;
     existingFileResult.error = outcome.error;
+    existingFileResult.status = outcome.failed ? "failed" : "passed";
   } else {
     const fileResult = {
       path: normalizedPath,
       failed: outcome.failed,
       durationMs: outcome.durationMs,
       error: outcome.error,
+      status: outcome.failed ? "failed" : "passed",
     };
     suite.fileResultsByPath.set(normalizedPath, fileResult);
     suite.fileResults.push(fileResult);
@@ -164,6 +189,7 @@ export function finalizeServiceResult(tracker, startedAt, finishedAt) {
         .map((file) => ({
           path: file.path,
           failed: file.failed,
+          status: file.status,
           durationMs: file.durationMs,
           error: file.error,
         })),
@@ -172,6 +198,66 @@ export function finalizeServiceResult(tracker, startedAt, finishedAt) {
   };
 }
 
+export function buildStatusArtifact({
+  productDir,
+  results,
+  metadata,
+}) {
+  const executedResults = results.filter((result) => !result.skipped);
+  const tests = [];
+
+  for (const result of executedResults) {
+    for (const suite of result.suites) {
+      for (const file of suite.files) {
+        tests.push({
+          service: result.name,
+          type: suite.type,
+          framework: suite.framework,
+          path: file.path,
+          status: file.status,
+        });
+      }
+    }
+  }
+
+  tests.sort(
+    (left, right) =>
+      left.service.localeCompare(right.service) ||
+      left.type.localeCompare(right.type) ||
+      left.path.localeCompare(right.path)
+  );
+
+  const summary = {
+    services: {
+      total: executedResults.length,
+      passed: executedResults.filter((result) => !result.failed).length,
+      failed: executedResults.filter((result) => result.failed).length,
+    },
+    tests: {
+      total: tests.length,
+      passed: tests.filter((test) => test.status === "passed").length,
+      failed: tests.filter((test) => test.status === "failed").length,
+      notRun: tests.filter((test) => test.status === "not_run").length,
+    },
+  };
+
+  return {
+    schemaVersion: 1,
+    source: "testkit",
+    notice: "Generated file. Do not edit manually.",
+    product: {
+      name: path.basename(productDir),
+    },
+    git: {
+      branch: metadata.git?.branch || null,
+      commitSha: metadata.git?.commitSha || null,
+    },
+    testkitVersion: metadata.testkitVersion,
+    summary,
+    tests,
+  };
+}
+
 export function buildRunArtifact({
   productDir,
   results,
@@ -181,6 +267,7 @@ export function buildRunArtifact({
   workerCount,
   suiteType,
   suiteNames,
+  fileNames,
   framework,
   shard,
   serviceFilter,
@@ -213,6 +300,7 @@ export function buildRunArtifact({
       dbBackend,
       suiteType,
       suiteNames,
+      fileNames,
       framework,
       shard,
       serviceFilter,

package/lib/runner/results.test.mjs

@@ -2,6 +2,7 @@ import { describe, expect, it } from "vitest";
 import {
   addTrackerError,
   buildRunArtifact,
+  buildStatusArtifact,
   buildServiceTrackers,
   finalizeServiceResult,
   formatDuration,
@@ -68,6 +69,7 @@ describe("runner-results", () => {
       {
         path: "tests/health.js",
         failed: true,
+        status: "failed",
         durationMs: 250,
         error: "boom",
       },
@@ -111,6 +113,7 @@ describe("runner-results", () => {
       workerCount: 1,
       suiteType: "all",
       suiteNames: [],
+      fileNames: [],
       framework: "all",
       shard: null,
       serviceFilter: null,
@@ -141,4 +144,84 @@ describe("runner-results", () => {
     ).toBe("1/3 suites passed, 1 not run");
     expect(formatError(new Error("boom"))).toBe("boom");
   });
+
+  it("builds deterministic status artifacts", () => {
+    const status = buildStatusArtifact({
+      productDir: "/tmp/my-product",
+      results: [
+        {
+          name: "api",
+          failed: true,
+          skipped: false,
+          suites: [
+            {
+              name: "health",
+              type: "integration",
+              framework: "k6",
+              files: [
+                { path: "tests/api/integration/a.int.testkit.ts", status: "passed" },
+                { path: "tests/api/integration/b.int.testkit.ts", status: "failed" },
+              ],
+            },
+          ],
+        },
+      ],
+      suiteType: "int",
+      suiteNames: ["health"],
+      fileNames: ["tests/api/integration/b.int.testkit.ts"],
+      framework: "k6",
+      shard: null,
+      serviceFilter: "api",
+      metadata: {
+        git: {
+          branch: "main",
+          commitSha: "abc123",
+        },
+        testkitVersion: "0.1.20",
+      },
+    });
+
+    expect(status).toEqual({
+      schemaVersion: 1,
+      source: "testkit",
+      notice: "Generated file. Do not edit manually.",
+      product: {
+        name: "my-product",
+      },
+      git: {
+        branch: "main",
+        commitSha: "abc123",
+      },
+      testkitVersion: "0.1.20",
+      summary: {
+        services: {
+          total: 1,
+          passed: 0,
+          failed: 1,
+        },
+        tests: {
+          total: 2,
+          passed: 1,
+          failed: 1,
+          notRun: 0,
+        },
+      },
+      tests: [
+        {
+          service: "api",
+          type: "integration",
+          framework: "k6",
+          path: "tests/api/integration/a.int.testkit.ts",
+          status: "passed",
+        },
+        {
+          service: "api",
+          type: "integration",
+          framework: "k6",
+          path: "tests/api/integration/b.int.testkit.ts",
+          status: "failed",
+        },
+      ],
+    });
+  });
 });

package/lib/runtime/index.mjs

@@ -3,7 +3,6 @@ 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";
@@ -124,7 +123,7 @@ function resolveProductDir(cwd, explicitDir) {
 }
 
 function ensureProductFiles(dir) {
-  const missing = [RUNNER_MANIFEST, TESTKIT_CONFIG].filter(
+  const missing = [TESTKIT_CONFIG].filter(
     (file) => !fs.existsSync(path.join(dir, file))
   );
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@elench/testkit",
-  "version": "0.1.19",
-  "description": "CLI for running manifest-defined local test suites across k6 and Playwright",
+  "version": "0.1.21",
+  "description": "CLI for discovering and running local test suites across k6 and Playwright",
   "type": "module",
   "exports": {
     ".": "./lib/index.mjs",