@appthrust/kest 0.10.0 → 0.12.0

package/README.md

@@ -1168,12 +1168,25 @@ await ns.assert<MyCustomResource>({
 });
 ```
 
+## Tips
+
+### Debugging failed tests
+
+By default, Kest cleans up all resources after every test -- even when the test fails. This keeps the cluster tidy but destroys the state you need for debugging. To preserve resources on failure, set `KEST_PRESERVE_ON_FAILURE=1`:
+
+```sh
+KEST_PRESERVE_ON_FAILURE=1 bun test
+```
+
+When active, Kest skips cleanup for failed scenarios so you can inspect the cluster with `kubectl`. The test report will show a "Cleanup (skipped)" notice instead of the usual cleanup table. Remember to delete the leftover resources manually once you're done investigating.
+
 ## Environment Variables
 
-| Variable           | Description                                                             |
-| ------------------ | ----------------------------------------------------------------------- |
-| `KEST_SHOW_REPORT` | Set to `"1"` to show Markdown reports for all tests (not just failures) |
-| `KEST_SHOW_EVENTS` | Set to `"1"` to dump raw recorder events for debugging                  |
+| Variable                    | Description                                                             |
+| --------------------------- | ----------------------------------------------------------------------- |
+| `KEST_SHOW_REPORT`          | Set to `"1"` to show Markdown reports for all tests (not just failures) |
+| `KEST_SHOW_EVENTS`          | Set to `"1"` to dump raw recorder events for debugging                  |
+| `KEST_PRESERVE_ON_FAILURE`  | Set to `"1"` to skip cleanup when a test fails, preserving cluster state for debugging |
 
 ## License
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@appthrust/kest",
-  "version": "0.10.0",
+  "version": "0.12.0",
   "description": "Kubernetes E2E testing framework designed for humans and AI alike",
   "type": "module",
   "module": "ts/index.ts",

package/ts/matchers/to-match-unordered.ts

@@ -1,40 +1,65 @@
-import type { MatcherResult } from "bun:test";
+import { expect, type MatcherResult } from "bun:test";
+import { stripAnsi } from "../reporter/markdown/strip-ansi";
+
+type EqualsFunction = (a: unknown, b: unknown) => boolean;
 
 /**
  * Deep partial match: checks that every key in `expected` exists in `actual`
  * with a matching value. For nested objects, recurses. For nested arrays,
  * checks index-by-index with ordered semantics.
+ *
+ * When an `equals` function is provided (from the matcher context), it is
+ * called first for every comparison. This lets Bun's native equality handle
+ * asymmetric matchers (`expect.stringMatching`, `expect.any`, etc.)
+ * transparently — no special detection needed.
  */
-export function deepPartialMatch(actual: unknown, expected: unknown): boolean {
+export function deepPartialMatch(
+  actual: unknown,
+  expected: unknown,
+  equals?: EqualsFunction
+): boolean {
   if (Object.is(actual, expected)) {
     return true;
   }
 
+  // Delegate to Bun's equals — handles asymmetric matchers and exact matches
+  if (equals?.(actual, expected)) {
+    return true;
+  }
+
   if (expected === null || actual === null) {
-    return actual === expected;
+    return false;
   }
 
   if (typeof expected !== "object" || typeof actual !== "object") {
-    return actual === expected;
+    return false;
   }
 
   if (Array.isArray(expected)) {
-    return deepPartialMatchArrays(actual, expected);
+    return deepPartialMatchArrays(actual, expected, equals);
   }
 
   if (Array.isArray(actual)) {
     return false;
   }
 
+  // Only partial-match plain objects; for non-plain objects (Bun asymmetric
+  // matchers, Date, RegExp, etc.) the equals() check above is authoritative.
+  if (Object.getPrototypeOf(expected) !== Object.prototype) {
+    return false;
+  }
+
   return deepPartialMatchObjects(
     actual as Record<string, unknown>,
-    expected as Record<string, unknown>
+    expected as Record<string, unknown>,
+    equals
   );
 }
 
 function deepPartialMatchArrays(
   actual: unknown,
-  expected: Array<unknown>
+  expected: Array<unknown>,
+  equals?: EqualsFunction
 ): boolean {
   if (!Array.isArray(actual)) {
     return false;
@@ -42,51 +67,58 @@ function deepPartialMatchArrays(
   if (actual.length !== expected.length) {
     return false;
   }
-  return expected.every((item, i) => deepPartialMatch(actual[i], item));
+  return expected.every((item, i) => deepPartialMatch(actual[i], item, equals));
 }
 
 function deepPartialMatchObjects(
   actual: Record<string, unknown>,
-  expected: Record<string, unknown>
+  expected: Record<string, unknown>,
+  equals?: EqualsFunction
 ): boolean {
   for (const key of Object.keys(expected)) {
     if (!(key in actual)) {
       return false;
     }
-    if (!deepPartialMatch(actual[key], expected[key])) {
+    if (!deepPartialMatch(actual[key], expected[key], equals)) {
       return false;
     }
   }
   return true;
 }
 
+interface MatchResult {
+  pass: boolean;
+  /** Maps each expected index to its matched actual index (or -1 if unmatched). */
+  pairing: Array<number>;
+  unmatchedActual: Array<number>;
+}
+
 /**
  * Find a one-to-one matching between expected and actual items using
- * deep partial match semantics. Returns the indices of unmatched expected
- * and unmatched actual items.
+ * deep partial match semantics. Returns a pairing array and unmatched
+ * actual indices.
  */
-function findUnmatched(
+function findMatching(
   actual: ReadonlyArray<unknown>,
-  expected: ReadonlyArray<unknown>
-): { unmatchedExpected: Array<number>; unmatchedActual: Array<number> } {
+  expected: ReadonlyArray<unknown>,
+  equals?: EqualsFunction
+): MatchResult {
   const usedActual = new Set<number>();
-  const unmatchedExpected: Array<number> = [];
+  const pairing: Array<number> = [];
 
-  for (let ei = 0; ei < expected.length; ei++) {
-    let found = false;
+  for (const [, expectedItem] of expected.entries()) {
+    let matched = -1;
     for (let ai = 0; ai < actual.length; ai++) {
       if (usedActual.has(ai)) {
         continue;
       }
-      if (deepPartialMatch(actual[ai], expected[ei])) {
+      if (deepPartialMatch(actual[ai], expectedItem, equals)) {
         usedActual.add(ai);
-        found = true;
+        matched = ai;
         break;
       }
     }
-    if (!found) {
-      unmatchedExpected.push(ei);
-    }
+    pairing.push(matched);
   }
 
   const unmatchedActual: Array<number> = [];
@@ -96,45 +128,145 @@ function findUnmatched(
     }
   }
 
-  return { unmatchedExpected, unmatchedActual };
+  return {
+    pass: pairing.every((ai) => ai !== -1),
+    pairing,
+    unmatchedActual,
+  };
+}
+
+/**
+ * Score how well an actual item matches an expected item by counting
+ * top-level keys in expected that have a matching value in actual.
+ */
+function matchScore(
+  actual: unknown,
+  expected: unknown,
+  equals?: EqualsFunction
+): number {
+  if (
+    typeof expected !== "object" ||
+    expected === null ||
+    typeof actual !== "object" ||
+    actual === null ||
+    Array.isArray(expected) ||
+    Array.isArray(actual)
+  ) {
+    return deepPartialMatch(actual, expected, equals) ? 1 : 0;
+  }
+  const expectedObj = expected as Record<string, unknown>;
+  const actualObj = actual as Record<string, unknown>;
+  let score = 0;
+  for (const key of Object.keys(expectedObj)) {
+    if (
+      key in actualObj &&
+      deepPartialMatch(actualObj[key], expectedObj[key], equals)
+    ) {
+      score++;
+    }
+  }
+  return score;
+}
+
+/**
+ * Find the closest actual item for an expected item by scoring all
+ * candidates and returning the one with the highest match score.
+ */
+function findClosestActual(
+  expectedItem: unknown,
+  candidates: ReadonlyArray<unknown>,
+  equals?: EqualsFunction
+): unknown {
+  let bestScore = -1;
+  let bestCandidate: unknown = candidates[0];
+  for (const candidate of candidates) {
+    const score = matchScore(candidate, expectedItem, equals);
+    if (score > bestScore) {
+      bestScore = score;
+      bestCandidate = candidate;
+    }
+  }
+  return bestCandidate;
+}
+
+/**
+ * Build a reordered actual array aligned with expected. Matched items
+ * keep their paired actual; unmatched expected items get their closest
+ * candidate from the unmatched actuals.
+ */
+function buildReorderedActual(
+  actual: ReadonlyArray<unknown>,
+  expected: ReadonlyArray<unknown>,
+  pairing: ReadonlyArray<number>,
+  unmatchedActual: ReadonlyArray<number>,
+  equals?: EqualsFunction
+): Array<unknown> {
+  const unmatchedActualItems = unmatchedActual.map((i) => actual[i]);
+  const reordered: Array<unknown> = [];
+
+  for (let ei = 0; ei < expected.length; ei++) {
+    const paired = pairing[ei] ?? -1;
+    if (paired !== -1) {
+      reordered.push(actual[paired]);
+    } else if (unmatchedActualItems.length > 0) {
+      reordered.push(
+        findClosestActual(expected[ei], unmatchedActualItems, equals)
+      );
+    } else {
+      reordered.push(undefined);
+    }
+  }
+
+  return reordered;
 }
 
 export function toMatchUnordered(
-  this: { isNot: boolean; utils: { stringify(v: unknown): string } },
+  this: {
+    isNot: boolean;
+    equals: EqualsFunction;
+    utils: { stringify(v: unknown): string };
+  },
   actual: unknown,
-  expected: unknown
+  expected: ReadonlyArray<unknown>
 ): MatcherResult {
   if (!Array.isArray(actual)) {
-    return {
-      pass: false,
-      message: () => `expected value to be an array, but got ${typeof actual}`,
-    };
-  }
-
-  if (!Array.isArray(expected)) {
     return {
       pass: false,
       message: () =>
-        `expected argument must be an array, but got ${typeof expected}`,
+        `expect(received).toMatchUnordered(expected)\n\nReceived value must be an array, but got ${typeof actual}`,
     };
   }
-
-  const { unmatchedExpected } = findUnmatched(actual, expected);
-  const pass = unmatchedExpected.length === 0;
+  const actualArray: ReadonlyArray<unknown> = actual;
+  const equals = this.equals.bind(this);
+  const { pass, pairing, unmatchedActual } = findMatching(
+    actualArray,
+    expected,
+    equals
+  );
 
   const message = (): string => {
     if (this.isNot) {
       return "expected arrays not to match (in any order), but every expected item had a match";
     }
-    const lines: Array<string> = [
-      "expected arrays to match (in any order), but some items did not match:",
-      "",
-      "Expected items without a match:",
-    ];
-    for (const i of unmatchedExpected) {
-      lines.push(`  [${i}]: ${this.utils.stringify(expected[i])}`);
+
+    const reordered = buildReorderedActual(
+      actualArray,
+      expected,
+      pairing,
+      unmatchedActual,
+      equals
+    );
+
+    try {
+      // biome-ignore lint: expect is used to generate diff output, not as a test assertion
+      expect(reordered).toMatchObject(expected as Array<unknown>);
+      return "expected arrays to match (in any order), but some items did not match";
+    } catch (e: unknown) {
+      return stripAnsi((e as Error).message).replace(
+        "expect(received).toMatchObject(expected)",
+        "expect(received).toMatchUnordered(expected)"
+      );
     }
-    return lines.join("\n");
   };
 
   return { pass, message };

package/ts/recording/index.ts

@@ -71,7 +71,8 @@ type RetryEvent =
 
 type RevertingsEvent =
   | BaseEvent<"RevertingsStart">
-  | BaseEvent<"RevertingsEnd">;
+  | BaseEvent<"RevertingsEnd">
+  | BaseEvent<"RevertingsSkipped">;
 
 type BDDEvent =
   | BaseEvent<"BDDGiven", { readonly description: string }>

package/ts/reporter/markdown/model.ts

@@ -7,6 +7,7 @@ export interface Scenario {
   overview: Array<OverviewItem>;
   details: Array<Tagged<"BDDSection", BDDSection> | Tagged<"Action", Action>>;
   cleanup: Array<CleanupItem>;
+  cleanupSkipped?: boolean;
 }
 
 type Tagged<Tag extends string, Target extends object> = Target & {

package/ts/reporter/markdown/parser/index.ts

@@ -75,6 +75,11 @@ function handleNonBDDEvent(state: ParseState, event: Event): void {
       state.inCleanup = false;
       clearCurrentActionState(state);
       return;
+    case "RevertingsSkipped": {
+      const scenario = ensureScenario(state.currentScenario, state.report);
+      scenario.cleanupSkipped = true;
+      return;
+    }
     case "ActionStart":
       handleActionStart(state, event);
       return;

package/ts/reporter/markdown/renderer/index.ts

@@ -157,7 +157,8 @@ export async function renderReport(
     const isEmpty =
       scenario.overview.length === 0 &&
       scenario.details.length === 0 &&
-      scenario.cleanup.length === 0;
+      scenario.cleanup.length === 0 &&
+      !scenario.cleanupSkipped;
     if (isEmpty) {
       continue;
     }
@@ -294,7 +295,19 @@ export async function renderReport(
     }
 
     // Cleanup
-    if (scenario.cleanup.length > 0) {
+    if (scenario.cleanupSkipped) {
+      lines.push("### Cleanup (skipped)");
+      lines.push("");
+      lines.push(
+        "Cleanup was skipped because `KEST_PRESERVE_ON_FAILURE=1` is set."
+      );
+      lines.push(
+        "Resources created during this scenario were **not** deleted."
+      );
+      lines.push(
+        "To clean up manually, run the revert commands from a passing test run."
+      );
+    } else if (scenario.cleanup.length > 0) {
       lines.push("### Cleanup");
       lines.push("");
       lines.push("| # | Action | Status |");

package/ts/reverting/index.ts

@@ -26,6 +26,9 @@ export function createReverting(deps: Deps) {
         recorder.record("RevertingsEnd", {});
       }
     },
+    skip(): void {
+      recorder.record("RevertingsSkipped", {});
+    },
   };
 }
 

package/ts/scenario/index.ts

@@ -32,7 +32,7 @@ import { retryUntil } from "../retry";
 import type { Reverting } from "../reverting";
 
 export interface InternalScenario extends Scenario {
-  cleanup(): Promise<void>;
+  cleanup(options?: { skip?: boolean }): Promise<void>;
   getReport(): Promise<string>;
 }
 
@@ -61,8 +61,12 @@ export function createScenario(deps: CreateScenarioOptions): InternalScenario {
     generateName: (prefix: string) => generateRandomName(prefix),
     newNamespace: createNewNamespaceFn(deps),
     useCluster: createUseClusterFn(deps),
-    async cleanup() {
-      await reverting.revert();
+    async cleanup(options?: { skip?: boolean }) {
+      if (options?.skip) {
+        reverting.skip();
+      } else {
+        await reverting.revert();
+      }
     },
     async getReport() {
       return await reporter.report(recorder.getEvents());

package/ts/test.ts

@@ -43,6 +43,7 @@ type BunTestRunner = (
 const workspaceRoot = await getWorkspaceRoot();
 const showReport = process.env["KEST_SHOW_REPORT"] === "1";
 const showEvents = process.env["KEST_SHOW_EVENTS"] === "1";
+const preserveOnFailure = process.env["KEST_PRESERVE_ON_FAILURE"] === "1";
 
 function makeScenarioTest(runner: BunTestRunner): TestFunction {
   return (label, fn, options) => {
@@ -66,7 +67,9 @@ function makeScenarioTest(runner: BunTestRunner): TestFunction {
       } catch (error) {
         testErr = error as Error;
       }
-      await scenario.cleanup();
+      await scenario.cleanup({
+        skip: preserveOnFailure && testErr !== undefined,
+      });
       recorder.record("ScenarioEnd", {});
       await report(recorder, scenario, testErr);
       if (testErr) {