@elench/testkit 0.1.35 → 0.1.36

package/README.md

@@ -35,6 +35,9 @@ npx @elench/testkit --type int,e2e,dal -s dal:queries
 # Exact file
 npx @elench/testkit --type int --file __testkit__/health/health.int.testkit.ts
 
+# Temporarily ignore repo-declared skip rules
+npx @elench/testkit --ignore-skip-rules --file __testkit__/billing/billing.int.testkit.ts
+
 # Deterministic git-trackable status snapshot
 npx @elench/testkit --type int --write-status
 
@@ -83,6 +86,22 @@ export default defineTestkitSetup({
       dependsOn: ["api"],
       envFiles: ["frontend/.env.testkit"],
     }),
+    billing: service({
+      skip: {
+        files: [
+          {
+            path: "__testkit__/invoices/invoices.int.testkit.ts",
+            reason: "Billing is still stubbed locally",
+          },
+        ],
+        suites: [
+          {
+            selector: "pw:lifecycle",
+            reason: "End-to-end billing lifecycle is not implemented yet",
+          },
+        ],
+      },
+    }),
   },
 });
 ```
@@ -95,6 +114,7 @@ for:
 - migrate / seed commands
 - test-local migrate / seed overrides
 - named HTTP suite profiles
+- repo-declared suite/file skip policies with explicit reasons
 - telemetry upload configuration
 
 ## Authoring

package/lib/cli/index.mjs

@@ -28,6 +28,10 @@ export function run() {
     .option("--shard <i/n>", "Run only shard i of n at suite granularity")
     .option("--write-status", "Write a deterministic testkit.status.json snapshot")
     .option("--allow-partial-status", "Allow --write-status for filtered runs")
+    .option(
+      "--ignore-skip-rules",
+      "Run files even if testkit.setup.ts marks them skipped"
+    )
     .action(async (first, second, third, options) => {
       const { lifecycle, positionalType } = resolveCliSelection({
         first,

package/lib/config/index.mjs

@@ -3,6 +3,11 @@ import path from "path";
 import { fileURLToPath } from "url";
 import { discoverProject } from "./discovery.mjs";
 import { loadTestkitSetup } from "./setup-loader.mjs";
+import {
+  matchesSuiteSelectors,
+  parseSuiteSelectors,
+  suiteSelectionType,
+} from "../runner/suite-selection.mjs";
 
 const TESTKIT_K6_BIN = "TESTKIT_K6_BIN";
 const DEFAULT_LOCAL_IMAGE = "pgvector/pgvector:pg16";
@@ -100,6 +105,11 @@ function normalizeServiceConfig({
   const database = normalizeDatabaseConfig(explicitService, name);
   const migrate = normalizeLifecycle(explicitService.migrate);
   const seed = normalizeLifecycle(explicitService.seed);
+  const skip = normalizeSkipConfig(explicitService.skip, {
+    name,
+    productDir,
+    suites,
+  });
 
   if (!explicitService.databaseFrom && !database && (migrate || seed)) {
     throw new Error(
@@ -134,6 +144,7 @@ function normalizeServiceConfig({
       serviceEnv,
       migrate,
       seed,
+      skip,
       local,
     },
   };
@@ -234,6 +245,96 @@ function normalizeLifecycle(value) {
   };
 }
 
+function normalizeSkipConfig(value, { name, productDir, suites }) {
+  if (!value) return undefined;
+
+  const discoveredFiles = new Set();
+  const discoveredSuites = [];
+  for (const [type, typedSuites] of Object.entries(suites || {})) {
+    for (const suite of typedSuites || []) {
+      const displayType = suiteSelectionType(type, suite.framework || "k6");
+      discoveredSuites.push({
+        type,
+        displayType,
+        name: suite.name,
+      });
+      for (const file of suite.files || []) {
+        discoveredFiles.add(normalizePath(file));
+      }
+    }
+  }
+
+  const seenFiles = new Set();
+  const files = [];
+  for (const rule of value.files || []) {
+    if (!rule || typeof rule !== "object") {
+      throw new Error(`Service "${name}" skip.files entries must be objects`);
+    }
+    const filePath = normalizePath(rule.path);
+    const reason = normalizeSkipReason(rule.reason, `Service "${name}" skip.files["${filePath}"]`);
+    if (!filePath) {
+      throw new Error(`Service "${name}" skip.files entries require a non-empty path`);
+    }
+    if (seenFiles.has(filePath)) {
+      throw new Error(`Service "${name}" defines duplicate skip.files path "${filePath}"`);
+    }
+    if (!discoveredFiles.has(filePath)) {
+      throw new Error(
+        `Service "${name}" skip.files path "${filePath}" did not match any discovered suite file`
+      );
+    }
+    seenFiles.add(filePath);
+    files.push({ path: filePath, reason });
+  }
+
+  const parsedSelectors = (value.suites || []).flatMap((rule, index) => {
+    if (!rule || typeof rule !== "object") {
+      throw new Error(`Service "${name}" skip.suites entries must be objects`);
+    }
+    const selector = String(rule.selector || "").trim();
+    if (!selector) {
+      throw new Error(`Service "${name}" skip.suites[${index}] requires a non-empty selector`);
+    }
+    const reason = normalizeSkipReason(
+      rule.reason,
+      `Service "${name}" skip.suites["${selector}"]`
+    );
+    const parsed = parseSuiteSelectors([selector]);
+    if (parsed.length !== 1) {
+      throw new Error(`Service "${name}" skip.suites["${selector}"] is invalid`);
+    }
+    return [{ selector: parsed[0], reason }];
+  });
+
+  const seenSelectors = new Set();
+  const suitesWithReasons = [];
+  for (const rule of parsedSelectors) {
+    if (seenSelectors.has(rule.selector.raw)) {
+      throw new Error(
+        `Service "${name}" defines duplicate skip.suites selector "${rule.selector.raw}"`
+      );
+    }
+    const matched = discoveredSuites.some((suite) =>
+      matchesSuiteSelectors(suite.displayType, suite.name, [rule.selector])
+    );
+    if (!matched) {
+      throw new Error(
+        `Service "${name}" skip.suites selector "${rule.selector.raw}" did not match any discovered suite`
+      );
+    }
+    seenSelectors.add(rule.selector.raw);
+    suitesWithReasons.push(rule);
+  }
+
+  if (files.length === 0 && suitesWithReasons.length === 0) return undefined;
+
+  return {
+    files,
+    fileReasonByPath: new Map(files.map((rule) => [rule.path, rule.reason])),
+    suites: suitesWithReasons,
+  };
+}
+
 function inferEnvFiles(productDir, explicitService, local) {
   if (explicitService.envFile || explicitService.envFiles) {
     const files = [];
@@ -256,6 +357,14 @@ function inferEnvFiles(productDir, explicitService, local) {
     .filter((candidate) => fs.existsSync(resolveServiceCwd(productDir, candidate)));
 }
 
+function normalizeSkipReason(reason, label) {
+  const normalized = String(reason || "").trim();
+  if (!normalized) {
+    throw new Error(`${label} requires a non-empty reason`);
+  }
+  return normalized;
+}
+
 function loadServiceEnv(productDir, envFiles) {
   const env = {};
   for (const envFile of envFiles) {
@@ -361,6 +470,13 @@ function normalizeTelemetryConfig(telemetry) {
   };
 }
 
+function normalizePath(value) {
+  return String(value || "")
+    .split(path.sep)
+    .join("/")
+    .replace(/^\.\/+/, "");
+}
+
 function resolveProductDir(cwd, explicitDir) {
   const dir = explicitDir ? path.resolve(cwd, explicitDir) : cwd;
   if (!fs.existsSync(dir)) {

package/lib/reporters/playwright.mjs

@@ -18,7 +18,7 @@ export function parsePlaywrightJsonResults(stdout, cwd) {
   const fileResults = new Map();
   visitPlaywrightSuites(parsed.suites || [], null, fileResults, cwd);
   return {
-    fileResults,
+    fileResults: sanitizePlaywrightFileResults(fileResults),
     errors: (parsed.errors || []).map(formatPlaywrightReporterError).filter(Boolean),
   };
 }
@@ -41,8 +41,11 @@ export function collectPlaywrightSpec(spec, inheritedFile, fileResults, cwd) {
 
   const current = fileResults.get(file) || {
     failed: false,
+    status: "passed",
     error: null,
     durationMs: 0,
+    passedCount: 0,
+    skippedCount: 0,
   };
 
   for (const test of spec.tests || []) {
@@ -53,16 +56,26 @@ export function collectPlaywrightSpec(spec, inheritedFile, fileResults, cwd) {
     );
 
     const final = choosePlaywrightFinalResult(results);
-    const failed =
-      test.outcome === "unexpected" ||
-      !isPlaywrightPassingStatus(final?.status);
+    const status = classifyPlaywrightTestOutcome(test, final);
 
-    if (failed) {
+    if (status === "failed") {
       current.failed = true;
+      current.status = "failed";
       current.error ||= extractPlaywrightFailure(final, spec, test);
+      continue;
     }
+
+    if (status === "skipped") {
+      current.skippedCount += 1;
+      continue;
+    }
+
+    current.passedCount += 1;
   }
 
+  if (!current.failed) {
+    current.status = current.passedCount === 0 && current.skippedCount > 0 ? "skipped" : "passed";
+  }
   fileResults.set(file, current);
 }
 
@@ -75,6 +88,16 @@ export function isPlaywrightPassingStatus(status) {
   return !status || ["passed", "skipped", "expected"].includes(status);
 }
 
+export function classifyPlaywrightTestOutcome(test, finalResult) {
+  if (test?.outcome === "unexpected" || !isPlaywrightPassingStatus(finalResult?.status)) {
+    return "failed";
+  }
+  if (test?.outcome === "skipped" || finalResult?.status === "skipped") {
+    return "skipped";
+  }
+  return "passed";
+}
+
 export function extractPlaywrightFailure(finalResult, spec, test) {
   const fromResult =
     finalResult?.error?.message ||
@@ -123,3 +146,16 @@ function formatError(error) {
   if (error instanceof Error) return error.message;
   return String(error);
 }
+
+function sanitizePlaywrightFileResults(fileResults) {
+  const sanitized = new Map();
+  for (const [file, result] of fileResults.entries()) {
+    sanitized.set(file, {
+      failed: result.failed,
+      status: result.status,
+      error: result.error,
+      durationMs: result.durationMs,
+    });
+  }
+  return sanitized;
+}

package/lib/reporters/playwright.test.mjs

@@ -49,11 +49,94 @@ describe("playwright-report", () => {
     expect(parsed.errors).toEqual(["reporter failure"]);
     expect(parsed.fileResults.get("tests/auth.spec.js")).toEqual({
       failed: true,
+      status: "failed",
       error: "boom",
       durationMs: 15,
     });
   });
 
+  it("marks files as skipped when every Playwright test is skipped", () => {
+    const stdout = JSON.stringify({
+      suites: [
+        {
+          file: "/tmp/tests/billing.spec.js",
+          specs: [
+            {
+              title: "billing is stubbed",
+              tests: [
+                {
+                  outcome: "skipped",
+                  results: [
+                    {
+                      status: "skipped",
+                      duration: 7,
+                    },
+                  ],
+                },
+              ],
+            },
+          ],
+        },
+      ],
+    });
+
+    const parsed = parsePlaywrightJsonResults(stdout, "/tmp");
+    expect(parsed.fileResults.get("tests/billing.spec.js")).toEqual({
+      failed: false,
+      status: "skipped",
+      error: null,
+      durationMs: 7,
+    });
+  });
+
+  it("keeps file status passed when one spec passes and another is skipped", () => {
+    const stdout = JSON.stringify({
+      suites: [
+        {
+          file: "/tmp/tests/mixed.spec.js",
+          specs: [
+            {
+              title: "passes",
+              tests: [
+                {
+                  outcome: "expected",
+                  results: [
+                    {
+                      status: "passed",
+                      duration: 5,
+                    },
+                  ],
+                },
+              ],
+            },
+            {
+              title: "skips",
+              tests: [
+                {
+                  outcome: "skipped",
+                  results: [
+                    {
+                      status: "skipped",
+                      duration: 3,
+                    },
+                  ],
+                },
+              ],
+            },
+          ],
+        },
+      ],
+    });
+
+    const parsed = parsePlaywrightJsonResults(stdout, "/tmp");
+    expect(parsed.fileResults.get("tests/mixed.spec.js")).toEqual({
+      failed: false,
+      status: "passed",
+      error: null,
+      durationMs: 8,
+    });
+  });
+
   it("chooses the final result and extracts failures", () => {
     expect(
       choosePlaywrightFinalResult([

package/lib/runner/formatting.mjs

@@ -7,12 +7,18 @@ export function formatDuration(durationMs) {
 }
 
 export function formatServiceSummary(result) {
-  const passedSuites = result.completedSuiteCount - result.failedSuiteCount;
+  const skippedSuites = result.skippedSuiteCount || 0;
+  const passedSuites = result.completedSuiteCount - result.failedSuiteCount - skippedSuites;
   const notRunSuites = result.suiteCount - result.completedSuiteCount;
   let detail = `${passedSuites}/${result.suiteCount} suites passed`;
   if ((result.totalFileCount || 0) > 0) {
     detail += `, ${result.passedFileCount}/${result.totalFileCount} files passed`;
   }
+  if (skippedSuites > 0) {
+    detail += `, ${skippedSuites} ${pluralize(skippedSuites, "suite", "suites")} skipped`;
+  } else if ((result.skippedFileCount || 0) > 0) {
+    detail += `, ${result.skippedFileCount} ${pluralize(result.skippedFileCount, "file", "files")} skipped`;
+  }
   if (notRunSuites > 0) {
     detail += `, ${notRunSuites} ${pluralize(notRunSuites, "suite", "suites")} not run`;
   } else if ((result.notRunFileCount || 0) > 0) {
@@ -66,10 +72,18 @@ export function buildRunSummaryLines(results, durationMs) {
     (sum, result) => sum + result.completedSuiteCount,
     0
   );
+  const skippedSuites = executedServices.reduce(
+    (sum, result) => sum + (result.skippedSuiteCount || 0),
+    0
+  );
   const failedSuites = executedServices.reduce((sum, result) => sum + result.failedSuiteCount, 0);
-  const passedSuites = completedSuites - failedSuites;
+  const passedSuites = completedSuites - failedSuites - skippedSuites;
   const totalFiles = executedServices.reduce((sum, result) => sum + (result.totalFileCount || 0), 0);
   const passedFiles = executedServices.reduce((sum, result) => sum + (result.passedFileCount || 0), 0);
+  const skippedFiles = executedServices.reduce(
+    (sum, result) => sum + (result.skippedFileCount || 0),
+    0
+  );
   const lines = [
     "",
     "══ Summary ══",
@@ -77,6 +91,8 @@ export function buildRunSummaryLines(results, durationMs) {
       `services ${passedServices.length}/${executedServices.length} passed`,
       `suites ${passedSuites}/${totalSuites} passed`,
       totalFiles > 0 ? `files ${passedFiles}/${totalFiles} passed` : null,
+      skippedSuites > 0 ? `suites ${skippedSuites} skipped` : null,
+      skippedFiles > 0 ? `files ${skippedFiles} skipped` : null,
       skippedServices.length > 0 ? `${skippedServices.length} skipped` : null,
       `duration ${formatDuration(durationMs)}`,
     ]
@@ -85,8 +101,14 @@ export function buildRunSummaryLines(results, durationMs) {
   ];
 
   for (const result of results) {
-    const status = result.skipped ? "SKIP" : result.failed ? "FAIL" : "PASS";
-    const detail = result.skipped ? "no matching suites" : formatServiceSummary(result);
+    const status = isServiceEffectivelySkipped(result)
+      ? "SKIP"
+      : result.failed
+        ? "FAIL"
+        : "PASS";
+    const detail = result.skipped
+      ? "no matching suites"
+      : formatServiceSummary(result);
     lines.push(
       `${status.padEnd(4)} ${result.name.padEnd(longestServiceName(results))}  ${detail}  ·  ${formatDuration(result.durationMs)}`
     );
@@ -127,3 +149,13 @@ function sanitizeErrorMessage(message) {
 function pluralize(value, singular, plural) {
   return value === 1 ? singular : plural;
 }
+
+function isServiceEffectivelySkipped(result) {
+  if (result.skipped) return true;
+  return (
+    !result.failed &&
+    (result.skippedSuiteCount || 0) > 0 &&
+    (result.skippedSuiteCount || 0) === result.suiteCount &&
+    (result.notRunFileCount || 0) === 0
+  );
+}

package/lib/runner/formatting.test.mjs

@@ -28,14 +28,31 @@ describe("runner formatting", () => {
       formatServiceSummary({
         completedSuiteCount: 2,
         failedSuiteCount: 1,
+        skippedSuiteCount: 0,
         suiteCount: 3,
         totalFileCount: 5,
         passedFileCount: 3,
+        skippedFileCount: 0,
         notRunFileCount: 1,
       })
     ).toBe("1/3 suites passed, 3/5 files passed, 1 suite not run");
   });
 
+  it("formats skipped suites distinctly from passed suites", () => {
+    expect(
+      formatServiceSummary({
+        completedSuiteCount: 2,
+        failedSuiteCount: 0,
+        skippedSuiteCount: 1,
+        suiteCount: 2,
+        totalFileCount: 3,
+        passedFileCount: 1,
+        skippedFileCount: 2,
+        notRunFileCount: 0,
+      })
+    ).toBe("1/2 suites passed, 1/3 files passed, 1 suite skipped");
+  });
+
   it("formats batch descriptors", () => {
     expect(formatBatchDescriptor({ framework: "k6", tasks: [{}, {}] })).toBe(" (2 files)");
     expect(formatBatchDescriptor({ framework: "playwright", tasks: [{}] })).toBe(
@@ -71,9 +88,12 @@ describe("runner formatting", () => {
           failed: true,
           suiteCount: 2,
           completedSuiteCount: 2,
+          skippedSuiteCount: 0,
           failedSuiteCount: 1,
           totalFileCount: 3,
           passedFileCount: 2,
+          skippedFileCount: 0,
+          notRunFileCount: 0,
           durationMs: 20_000,
           suites: [
             {
@@ -97,4 +117,33 @@ describe("runner formatting", () => {
     expect(lines.join("\n")).toContain("worker error: worker broke");
     expect(lines.at(-1)).toBe("Result: FAILED (1/1 services failed)");
   });
+
+  it("marks services with only skipped suites as SKIP", () => {
+    const lines = buildRunSummaryLines(
+      [
+        {
+          name: "api",
+          skipped: false,
+          failed: false,
+          suiteCount: 1,
+          completedSuiteCount: 1,
+          skippedSuiteCount: 1,
+          failedSuiteCount: 0,
+          totalFileCount: 1,
+          passedFileCount: 0,
+          skippedFileCount: 1,
+          notRunFileCount: 0,
+          durationMs: 0,
+          suites: [],
+          errors: [],
+        },
+      ],
+      0
+    );
+
+    expect(lines.join("\n")).toContain("suites 1 skipped");
+    expect(lines.join("\n")).toContain("files 1 skipped");
+    expect(lines.join("\n")).toContain("SKIP api");
+    expect(lines.at(-1)).toBe("Result: PASSED");
+  });
 });

package/lib/runner/orchestrator.mjs

@@ -189,7 +189,7 @@ function collectServicePlans(configs, configMap, typeValues, suiteSelectors, opt
   return configs.map((config) => {
     console.log(`\n══ ${config.name} ══`);
     const suites = applyShard(
-      collectSuites(config, typeValues, suiteSelectors, opts.fileNames || []),
+      collectSuites(config, typeValues, suiteSelectors, opts.fileNames || [], opts),
       opts.shard
     );
 

package/lib/runner/planning.mjs

@@ -39,7 +39,7 @@ export function resolveRuntimeConfigs(targetConfig, configMap) {
   return ordered;
 }
 
-export function collectSuites(config, typeValues, suiteSelectors, fileNames = []) {
+export function collectSuites(config, typeValues, suiteSelectors, fileNames = [], opts = {}) {
   const selectedFiles = new Set(fileNames.map(normalizePathSeparators));
   const suites = [];
   let orderIndex = 0;
@@ -48,17 +48,26 @@ export function collectSuites(config, typeValues, suiteSelectors, fileNames = []
     for (const suite of config.suites[type] || []) {
       const framework = suite.framework || "k6";
       const displayType = suiteSelectionType(type, framework);
-      const files =
+      const selectedSuiteFiles =
         selectedFiles.size === 0
           ? suite.files
           : suite.files.filter((file) => selectedFiles.has(normalizePathSeparators(file)));
       if (!matchesSelectedTypes(displayType, typeValues)) continue;
       if (!matchesSuiteSelectors(displayType, suite.name, suiteSelectors)) continue;
-      if (files.length === 0) continue;
+      if (selectedSuiteFiles.length === 0) continue;
+
+      const { files, skippedFiles } = applySkipRules(
+        config,
+        displayType,
+        suite.name,
+        selectedSuiteFiles,
+        opts
+      );
 
       suites.push({
         ...suite,
         files,
+        skippedFiles,
         framework,
         type,
         displayType,
@@ -67,12 +76,13 @@ export function collectSuites(config, typeValues, suiteSelectors, fileNames = []
         weight:
           suite.testkit?.weight ||
           (framework === "playwright"
-            ? Math.max(2, files.length)
+            ? Math.max(2, Math.max(1, files.length))
             : Math.max(1, files.length)),
         maxFileConcurrency:
           framework === "k6" || framework === "playwright"
             ? suite.testkit?.maxFileConcurrency || 1
             : 1,
+        totalFileCount: selectedSuiteFiles.length,
       });
       orderIndex += 1;
     }
@@ -262,6 +272,47 @@ function normalizePathSeparators(filePath) {
   return String(filePath).split("\\").join("/");
 }
 
+function applySkipRules(config, displayType, suiteName, files, opts = {}) {
+  if (opts.ignoreSkipRules) {
+    return {
+      files,
+      skippedFiles: [],
+    };
+  }
+  const skip = config.testkit?.skip;
+  if (!skip) {
+    return {
+      files,
+      skippedFiles: [],
+    };
+  }
+
+  const matchingSuiteRules = skip.suites.filter((rule) =>
+    matchesSuiteSelectors(displayType, suiteName, [rule.selector])
+  );
+  const suiteReason = matchingSuiteRules[0]?.reason || null;
+  const runnableFiles = [];
+  const skippedFiles = [];
+
+  for (const file of files) {
+    const normalizedFile = normalizePathSeparators(file);
+    const reason = skip.fileReasonByPath.get(normalizedFile) || suiteReason;
+    if (reason) {
+      skippedFiles.push({
+        path: normalizedFile,
+        reason,
+      });
+      continue;
+    }
+    runnableFiles.push(file);
+  }
+
+  return {
+    files: runnableFiles,
+    skippedFiles,
+  };
+}
+
 export function buildGraphDirName(runtimeNames) {
   const slug = runtimeNames.map(slugSegment).join("__");
   return slug.length > 0 ? slug : "graph";

package/lib/runner/planning.test.mjs

@@ -85,6 +85,57 @@ describe("runner-planning", () => {
     });
   });
 
+  it("keeps skipped files visible while removing them from runnable work", () => {
+    const config = makeConfig("api", {
+      suites: {
+        integration: [
+          {
+            name: "billing",
+            files: [
+              "__testkit__/billing/a.int.testkit.ts",
+              "__testkit__/billing/b.int.testkit.ts",
+            ],
+          },
+        ],
+      },
+      testkit: {
+        dependsOn: [],
+        skip: {
+          fileReasonByPath: new Map([
+            ["__testkit__/billing/a.int.testkit.ts", "Billing is stubbed"],
+          ]),
+          suites: [],
+        },
+      },
+    });
+
+    expect(collectSuites(config, ["int"], [], [])).toEqual([
+      expect.objectContaining({
+        name: "billing",
+        files: ["__testkit__/billing/b.int.testkit.ts"],
+        skippedFiles: [
+          {
+            path: "__testkit__/billing/a.int.testkit.ts",
+            reason: "Billing is stubbed",
+          },
+        ],
+        totalFileCount: 2,
+      }),
+    ]);
+
+    expect(collectSuites(config, ["int"], [], [], { ignoreSkipRules: true })).toEqual([
+      expect.objectContaining({
+        name: "billing",
+        files: [
+          "__testkit__/billing/a.int.testkit.ts",
+          "__testkit__/billing/b.int.testkit.ts",
+        ],
+        skippedFiles: [],
+        totalFileCount: 2,
+      }),
+    ]);
+  });
+
   it("applies shards, builds graphs, queues tasks, and claims batches", () => {
     const api = makeConfig("api");
     const frontend = makeConfig("frontend");

package/lib/runner/playwright-runner.mjs

@@ -62,7 +62,8 @@ export async function runPlaywrightBatch(targetConfig, batch, lifecycle) {
     if (fileResult) {
       return {
         task,
-        failed: fileResult.failed,
+        failed: fileResult.status === "failed",
+        status: fileResult.status,
         error: fileResult.error,
         durationMs:
           fileResult.durationMs > 0

package/lib/runner/reporting.mjs

@@ -11,17 +11,22 @@ export function buildStatusArtifact({
   metadata,
 }) {
   const executedResults = results.filter((result) => !result.skipped);
+  const effectivelySkippedResults = executedResults.filter(isEffectivelySkippedService);
   const tests = [];
 
   for (const result of executedResults) {
     for (const suite of result.suites) {
       for (const file of suite.files) {
-        tests.push({
+        const test = {
           service: result.name,
           type: suite.type,
           path: file.path,
           status: file.status,
-        });
+        };
+        if (file.reason) {
+          test.reason = file.reason;
+        }
+        tests.push(test);
       }
     }
   }
@@ -36,13 +41,17 @@ export function buildStatusArtifact({
   const summary = {
     services: {
       total: executedResults.length,
-      passed: executedResults.filter((result) => !result.failed).length,
+      passed: executedResults.filter(
+        (result) => !result.failed && !isEffectivelySkippedService(result)
+      ).length,
       failed: executedResults.filter((result) => result.failed).length,
+      skipped: effectivelySkippedResults.length,
     },
     tests: {
       total: tests.length,
       passed: tests.filter((test) => test.status === "passed").length,
       failed: tests.filter((test) => test.status === "failed").length,
+      skipped: tests.filter((test) => test.status === "skipped").length,
       notRun: tests.filter((test) => test.status === "not_run").length,
     },
   };
@@ -63,7 +72,7 @@ export function buildStatusArtifact({
     scope.serviceFilter === null;
 
   return {
-    schemaVersion: 2,
+    schemaVersion: 3,
     source: "testkit",
     notice: "Generated file. Do not edit manually.",
     product: {
@@ -96,18 +105,21 @@ export function buildRunArtifact({
   summarizeDbBackend,
 }) {
   const executed = results.filter((result) => !result.skipped);
+  const effectivelySkippedServices = executed.filter(isEffectivelySkippedService);
   const failedServices = executed.filter((result) => result.failed);
   const totalSuites = executed.reduce((sum, result) => sum + result.suiteCount, 0);
   const completedSuites = executed.reduce((sum, result) => sum + result.completedSuiteCount, 0);
+  const skippedSuites = executed.reduce((sum, result) => sum + (result.skippedSuiteCount || 0), 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 skippedFiles = executed.reduce((sum, result) => sum + (result.skippedFileCount || 0), 0);
   const notRunFiles = executed.reduce((sum, result) => sum + (result.notRunFileCount || 0), 0);
   const dbBackend = summarizeDbBackend(results);
 
   return {
-    schemaVersion: 2,
+    schemaVersion: 3,
     source: "testkit",
     generatedAt: new Date(finishedAt).toISOString(),
     product: {
@@ -134,19 +146,22 @@ export function buildRunArtifact({
     summary: {
       services: {
         total: executed.length,
-        passed: executed.length - failedServices.length,
+        passed: executed.length - failedServices.length - effectivelySkippedServices.length,
         failed: failedServices.length,
+        skipped: effectivelySkippedServices.length,
       },
       suites: {
         total: totalSuites,
         completed: completedSuites,
-        passed: completedSuites - failedSuites,
+        passed: completedSuites - failedSuites - skippedSuites,
         failed: failedSuites,
+        skipped: skippedSuites,
       },
       files: {
         total: totalFiles,
         passed: passedFiles,
         failed: failedFiles,
+        skipped: skippedFiles,
         notRun: notRunFiles,
       },
     },
@@ -156,11 +171,13 @@ export function buildRunArtifact({
       skipped: result.skipped,
       suiteCount: result.suiteCount,
       completedSuiteCount: result.completedSuiteCount,
+      skippedSuiteCount: result.skippedSuiteCount,
       failedSuiteCount: result.failedSuiteCount,
       totalFileCount: result.totalFileCount,
       completedFileCount: result.completedFileCount,
       passedFileCount: result.passedFileCount,
       failedFileCount: result.failedFileCount,
+      skippedFileCount: result.skippedFileCount,
       notRunFileCount: result.notRunFileCount,
       durationMs: result.durationMs,
       totalTaskDurationMs: result.totalTaskDurationMs,
@@ -170,3 +187,13 @@ export function buildRunArtifact({
     })),
   };
 }
+
+function isEffectivelySkippedService(result) {
+  return (
+    !result.skipped &&
+    !result.failed &&
+    (result.skippedSuiteCount || 0) > 0 &&
+    (result.skippedSuiteCount || 0) === result.suiteCount &&
+    (result.notRunFileCount || 0) === 0
+  );
+}

package/lib/runner/reporting.test.mjs

@@ -10,11 +10,13 @@ describe("runner reporting", () => {
         skipped: false,
         suiteCount: 1,
         completedSuiteCount: 1,
+        skippedSuiteCount: 0,
         failedSuiteCount: 0,
         totalFileCount: 3,
         completedFileCount: 3,
         passedFileCount: 3,
         failedFileCount: 0,
+        skippedFileCount: 0,
         notRunFileCount: 0,
         durationMs: 1200,
         totalTaskDurationMs: 2400,
@@ -28,11 +30,13 @@ describe("runner reporting", () => {
         skipped: true,
         suiteCount: 0,
         completedSuiteCount: 0,
+        skippedSuiteCount: 0,
         failedSuiteCount: 0,
         totalFileCount: 0,
         completedFileCount: 0,
         passedFileCount: 0,
         failedFileCount: 0,
+        skippedFileCount: 0,
         notRunFileCount: 0,
         durationMs: 0,
         totalTaskDurationMs: 0,
@@ -70,11 +74,25 @@ describe("runner reporting", () => {
     });
 
     expect(artifact.product.name).toBe("my-product");
-    expect(artifact.summary.services.total).toBe(1);
+    expect(artifact.schemaVersion).toBe(3);
+    expect(artifact.summary.services).toEqual({
+      total: 1,
+      passed: 1,
+      failed: 0,
+      skipped: 0,
+    });
+    expect(artifact.summary.suites).toEqual({
+      total: 1,
+      completed: 1,
+      passed: 1,
+      failed: 0,
+      skipped: 0,
+    });
     expect(artifact.summary.files).toEqual({
       total: 3,
       passed: 3,
       failed: 0,
+      skipped: 0,
       notRun: 0,
     });
     expect(artifact.services[0].durationMs).toBe(1200);
@@ -96,7 +114,11 @@ describe("runner reporting", () => {
               framework: "k6",
               files: [
                 { path: "tests/api/integration/a.int.testkit.ts", status: "passed" },
-                { path: "tests/api/integration/b.int.testkit.ts", status: "failed" },
+                {
+                  path: "tests/api/integration/b.int.testkit.ts",
+                  status: "skipped",
+                  reason: "Billing is stubbed",
+                },
               ],
             },
           ],
@@ -117,7 +139,7 @@ describe("runner reporting", () => {
     });
 
     expect(status).toEqual({
-      schemaVersion: 2,
+      schemaVersion: 3,
       source: "testkit",
       notice: "Generated file. Do not edit manually.",
       product: {
@@ -141,11 +163,13 @@ describe("runner reporting", () => {
           total: 1,
           passed: 0,
           failed: 1,
+          skipped: 0,
         },
         tests: {
           total: 2,
           passed: 1,
-          failed: 1,
+          failed: 0,
+          skipped: 1,
           notRun: 0,
         },
       },
@@ -160,7 +184,8 @@ describe("runner reporting", () => {
           service: "api",
           type: "int",
           path: "tests/api/integration/b.int.testkit.ts",
-          status: "failed",
+          status: "skipped",
+          reason: "Billing is stubbed",
         },
       ],
     });

package/lib/runner/results.mjs

@@ -29,12 +29,12 @@ export function buildServiceTrackers(servicePlans, startedAt) {
       displayType: suite.displayType || suite.type,
       framework: suite.framework,
       orderIndex: suite.orderIndex,
-      fileCount: suite.files.length,
+      fileCount: suite.totalFileCount ?? suite.files.length,
       completedFileCount: 0,
       failedFiles: [],
       failedFileSet: new Set(),
-      fileResultsByPath: new Map(
-        suite.files.map((file) => {
+      fileResultsByPath: new Map([
+        ...suite.files.map((file) => {
           const normalizedPath = normalizePathSeparators(file);
           return [
             normalizedPath,
@@ -43,11 +43,23 @@ export function buildServiceTrackers(servicePlans, startedAt) {
               failed: false,
               durationMs: 0,
               error: null,
+              reason: null,
               status: "not_run",
             },
           ];
-        })
-      ),
+        }),
+        ...(suite.skippedFiles || []).map((file) => [
+          file.path,
+          {
+            path: file.path,
+            failed: false,
+            durationMs: 0,
+            error: null,
+            reason: file.reason,
+            status: "skipped",
+          },
+        ]),
+      ]),
       durationMs: 0,
       error: null,
     }));
@@ -93,25 +105,30 @@ export function recordTaskOutcome(trackers, task, outcome, finishedAt = Date.now
       : Math.max(tracker.lastTaskAt, outcomeFinishedAt);
   tracker.totalTaskDurationMs += outcomeDurationMs;
 
-  suite.completedFileCount += 1;
   suite.durationMs += outcomeDurationMs;
   const normalizedPath = normalizePathSeparators(task.file);
   const existingFileResult = suite.fileResultsByPath.get(normalizedPath);
+  const status = normalizeOutcomeStatus(outcome);
+  if (status !== "skipped") {
+    suite.completedFileCount += 1;
+  }
   if (existingFileResult) {
-    existingFileResult.failed = outcome.failed;
+    existingFileResult.failed = status === "failed";
     existingFileResult.durationMs = outcomeDurationMs;
     existingFileResult.error = outcome.error;
-    existingFileResult.status = outcome.failed ? "failed" : "passed";
+    existingFileResult.reason = outcome.reason || null;
+    existingFileResult.status = status;
   } else {
     suite.fileResultsByPath.set(normalizedPath, {
       path: normalizedPath,
-      failed: outcome.failed,
+      failed: status === "failed",
       durationMs: outcomeDurationMs,
       error: outcome.error,
-      status: outcome.failed ? "failed" : "passed",
+      reason: outcome.reason || null,
+      status,
     });
   }
-  if (outcome.failed && !suite.failedFileSet.has(task.file)) {
+  if (status === "failed" && !suite.failedFileSet.has(task.file)) {
     suite.failedFileSet.add(task.file);
     suite.failedFiles.push(task.file);
   }
@@ -145,7 +162,14 @@ export function finalizeServiceResult(tracker, startedAt, finishedAt) {
       skipped: true,
       suiteCount: 0,
       completedSuiteCount: 0,
+      skippedSuiteCount: 0,
       failedSuiteCount: 0,
+      totalFileCount: 0,
+      completedFileCount: 0,
+      passedFileCount: 0,
+      failedFileCount: 0,
+      skippedFileCount: 0,
+      notRunFileCount: 0,
       durationMs: 0,
       totalTaskDurationMs: 0,
       suites: [],
@@ -158,14 +182,18 @@ export function finalizeServiceResult(tracker, startedAt, finishedAt) {
     .map((suite) => finalizeSuite(suite));
 
   const completedSuiteCount = suites.filter(
-    (suite) => suite.completedFileCount === suite.fileCount
+    (suite) => suite.completedFileCount + suite.skippedFileCount === suite.fileCount
+  ).length;
+  const skippedSuiteCount = suites.filter(
+    (suite) => suite.skippedFileCount === suite.fileCount && suite.fileCount > 0
   ).length;
   const failedSuiteCount = suites.filter((suite) => suite.failedFileCount > 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.failedFileCount, 0);
   const passedFileCount = suites.reduce((sum, suite) => sum + suite.passedFileCount, 0);
-  const notRunFileCount = totalFileCount - completedFileCount;
+  const skippedFileCount = suites.reduce((sum, suite) => sum + suite.skippedFileCount, 0);
+  const notRunFileCount = totalFileCount - completedFileCount - skippedFileCount;
   const totalTaskDurationMs =
     tracker.totalTaskDurationMs || suites.reduce((sum, suite) => sum + suite.durationMs, 0);
   const durationMs =
@@ -183,11 +211,13 @@ export function finalizeServiceResult(tracker, startedAt, finishedAt) {
     skipped: false,
     suiteCount: tracker.suiteCount,
     completedSuiteCount,
+    skippedSuiteCount,
     failedSuiteCount,
     totalFileCount,
     completedFileCount,
     passedFileCount,
     failedFileCount,
+    skippedFileCount,
     notRunFileCount,
     durationMs,
     totalTaskDurationMs,
@@ -212,6 +242,7 @@ function finalizeSuite(suite) {
       status: file.status,
       durationMs: file.durationMs,
       error: file.error,
+      reason: file.reason,
     }));
 
   return {
@@ -223,7 +254,11 @@ function finalizeSuite(suite) {
     completedFileCount: suite.completedFileCount,
     passedFileCount: files.filter((file) => file.status === "passed").length,
     failedFileCount: suite.failedFiles.length,
-    notRunFileCount: suite.fileCount - suite.completedFileCount,
+    skippedFileCount: files.filter((file) => file.status === "skipped").length,
+    notRunFileCount:
+      suite.fileCount -
+      suite.completedFileCount -
+      files.filter((file) => file.status === "skipped").length,
     failedFiles: suite.failedFiles,
     durationMs: suite.durationMs,
     error: suite.error,
@@ -239,3 +274,8 @@ function formatFrameworkForArtifact(framework) {
   if (framework === "k6") return "default";
   return framework;
 }
+
+function normalizeOutcomeStatus(outcome) {
+  if (outcome?.status === "skipped") return "skipped";
+  return outcome?.failed ? "failed" : "passed";
+}

package/lib/runner/results.test.mjs

@@ -72,6 +72,7 @@ describe("runner results", () => {
         status: "failed",
         durationMs: 250,
         error: "boom",
+        reason: null,
       },
     ]);
   });
@@ -193,6 +194,119 @@ describe("runner results", () => {
     expect(result.totalTaskDurationMs).toBe(3_000);
   });
 
+  it("counts config-skipped files and runtime-skipped files separately from passed work", () => {
+    const trackers = buildServiceTrackers(
+      [
+        {
+          skipped: false,
+          config: {
+            name: "api",
+            testkit: {
+              database: {
+                selectedBackend: null,
+              },
+            },
+          },
+          suites: [
+            {
+              name: "billing",
+              type: "integration",
+              framework: "k6",
+              files: ["tests/billing-live.int.testkit.ts"],
+              skippedFiles: [
+                {
+                  path: "tests/billing-stubbed.int.testkit.ts",
+                  reason: "Billing is stubbed",
+                },
+              ],
+              totalFileCount: 2,
+              orderIndex: 0,
+            },
+            {
+              name: "frontend-smoke",
+              type: "e2e",
+              framework: "playwright",
+              files: ["tests/frontend-smoke.pw.testkit.ts"],
+              orderIndex: 1,
+            },
+          ],
+        },
+      ],
+      1000
+    );
+
+    recordTaskOutcome(
+      trackers,
+      {
+        serviceName: "api",
+        suiteKey: "integration:billing",
+        file: "tests/billing-live.int.testkit.ts",
+      },
+      {
+        failed: false,
+        durationMs: 100,
+        error: null,
+      },
+      1100
+    );
+    recordTaskOutcome(
+      trackers,
+      {
+        serviceName: "api",
+        suiteKey: "e2e:frontend-smoke",
+        file: "tests/frontend-smoke.pw.testkit.ts",
+      },
+      {
+        failed: false,
+        status: "skipped",
+        reason: "Playwright test.skip()",
+        durationMs: 50,
+        error: null,
+      },
+      1150
+    );
+
+    const result = finalizeServiceResult(trackers.get("api"), 1000, 1200);
+
+    expect(result.failed).toBe(false);
+    expect(result.completedSuiteCount).toBe(2);
+    expect(result.skippedSuiteCount).toBe(1);
+    expect(result.totalFileCount).toBe(3);
+    expect(result.completedFileCount).toBe(1);
+    expect(result.passedFileCount).toBe(1);
+    expect(result.failedFileCount).toBe(0);
+    expect(result.skippedFileCount).toBe(2);
+    expect(result.notRunFileCount).toBe(0);
+    expect(result.suites[0].files).toEqual([
+      {
+        path: "tests/billing-live.int.testkit.ts",
+        failed: false,
+        status: "passed",
+        durationMs: 100,
+        error: null,
+        reason: null,
+      },
+      {
+        path: "tests/billing-stubbed.int.testkit.ts",
+        failed: false,
+        status: "skipped",
+        durationMs: 0,
+        error: null,
+        reason: "Billing is stubbed",
+      },
+    ]);
+    expect(result.suites[1].files).toEqual([
+      {
+        path: "tests/frontend-smoke.pw.testkit.ts",
+        failed: false,
+        status: "skipped",
+        durationMs: 50,
+        error: null,
+        reason: "Playwright test.skip()",
+      },
+    ]);
+  });
+
   it("summarizes mixed db backends", () => {
     expect(
       summarizeDbBackend([{ dbBackend: "local" }, { dbBackend: "neon" }])

package/lib/runner/selection.mjs

@@ -8,7 +8,9 @@ export function findUnmatchedRequestedFiles(
 ) {
   const matchedFiles = new Set();
   for (const config of configs) {
-    const suites = collectSuites(config, typeValues, suiteSelectors, []);
+    const suites = collectSuites(config, typeValues, suiteSelectors, [], {
+      ignoreSkipRules: true,
+    });
     for (const suite of suites) {
       for (const file of suite.files) {
         matchedFiles.add(normalizePathSeparators(file));

package/lib/setup/index.d.ts

@@ -18,6 +18,21 @@ export interface LifecycleConfig {
   testkitCwd?: string;
 }
 
+export interface SkipFileRule {
+  path: string;
+  reason: string;
+}
+
+export interface SkipSuiteRule {
+  selector: string;
+  reason: string;
+}
+
+export interface SkipConfig {
+  files?: SkipFileRule[];
+  suites?: SkipSuiteRule[];
+}
+
 export interface ServiceConfig {
   database?: LocalDatabaseConfig;
   databaseFrom?: string;
@@ -38,6 +53,7 @@ export interface ServiceConfig {
   };
   migrate?: LifecycleConfig;
   seed?: LifecycleConfig;
+  skip?: SkipConfig;
 }
 
 export interface TestkitSetup {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@elench/testkit",
-  "version": "0.1.35",
+  "version": "0.1.36",
   "description": "CLI for discovering and running local HTTP, DAL, and Playwright test suites",
   "type": "module",
   "types": "./lib/index.d.ts",