@appthrust/kest 0.9.0 → 0.11.0

package/README.md

@@ -915,11 +915,11 @@ test("scaling up increases available replicas", async (s) => {
 
 **When to use which approach:**
 
-| Scenario | Approach |
-| --- | --- |
+| Scenario                                                  | Approach                                                 |
+| --------------------------------------------------------- | -------------------------------------------------------- |
 | Each `apply` is a different resource or independent input | Inline each manifest separately (keep manifests visible) |
-| The same resource is applied twice with a small change | `structuredClone` + targeted mutation |
-| The manifest is too large to inline comfortably | Static fixture files (`import("./fixtures/...")`) |
+| The same resource is applied twice with a small change    | `structuredClone` + targeted mutation                    |
+| The manifest is too large to inline comfortably           | Static fixture files (`import("./fixtures/...")`)        |
 
 **Mutation-readability checklist:**
 
@@ -1098,6 +1098,34 @@ await ns.assert({
 - **With a type parameter** (e.g. `assert<MyResource>`) — either style works; `this` is fully typed, so it's a matter of preference.
 - **Without a type parameter** — always use `toMatchObject`. `this.spec` is `unknown`, and `toMatchObject` scales naturally as you add more assertions.
 
+### Prefer whole-array assertions over for-loops in `assertList`
+
+Avoid `for` loops inside `assertList` — when an assertion fails, the error doesn't identify which item caused it:
+
+```ts
+// ❌ Failure messages are opaque — which Secret failed?
+test() {
+  for (const s of this) {
+    expect(s.metadata.labels).toMatchObject({ app: "my-app" });
+  }
+}
+
+// ✅ Assert the whole array — full per-item diff on failure
+test() {
+  expect(this).toMatchUnordered([
+    { metadata: { name: "secret-a", labels: { app: "my-app" } } },
+    { metadata: { name: "secret-b", labels: { app: "my-app" } } },
+  ]);
+}
+```
+
+`toMatchUnordered` uses deep partial matching (like `toMatchObject`) but ignores order. Neither matcher checks array length — use `toHaveLength` when you need an exact count.
+
+| Matcher | Order-sensitive | Matching |
+|---|---|---|
+| `toMatchObject([...])` | yes | deep partial |
+| `toMatchUnordered([...])` | no | deep partial |
+
 ## Type Safety
 
 Define TypeScript interfaces for your Kubernetes resources to get full type checking in manifests and assertions:

package/example/example.test.ts

@@ -197,6 +197,39 @@ test("Example: asserts resource presence and absence in a list", async (s) => {
   });
 });
 
+test("Example: asserts list items in any order with toMatchUnordered", async (s) => {
+  s.given("a new namespace exists");
+  const ns = await s.newNamespace();
+
+  s.when("I apply multiple Secrets");
+  await ns.apply({
+    apiVersion: "v1",
+    kind: "Secret",
+    metadata: { name: "app-secret" },
+    stringData: { token: "abc" },
+  });
+  await ns.apply({
+    apiVersion: "v1",
+    kind: "Secret",
+    metadata: { name: "db-secret" },
+    stringData: { token: "xyz" },
+  });
+
+  s.then("the list should contain both Secrets regardless of order");
+  await ns.assertList({
+    apiVersion: "v1",
+    kind: "Secret",
+    test() {
+      // toMatchUnordered uses deep partial matching (like toMatchObject)
+      // but ignores array order.
+      expect(this).toMatchUnordered([
+        { metadata: { name: "db-secret" } },
+        { metadata: { name: "app-secret" } },
+      ]);
+    },
+  });
+});
+
 test("Example: applies status subresource to custom resource", async (s) => {
   s.given("a HelloWorld custom resource definition exists");
   await s.apply(import("./hello-world-crd.yaml"));

package/package.json

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

package/ts/apis/index.ts

@@ -1555,3 +1555,30 @@ export interface K8sResource {
 export interface ImportedYaml {
   readonly default: unknown;
 }
+
+// ---------------------------------------------------------------------------
+// Custom matchers – auto-registered when importing `@appthrust/kest`
+// ---------------------------------------------------------------------------
+
+declare module "bun:test" {
+  interface Matchers<T> {
+    /**
+     * Assert that an array contains the expected items using **deep partial
+     * matching** (same semantics as `toMatchObject`) but **ignoring order**.
+     *
+     * - Each expected item must match exactly one actual item (one-to-one).
+     * - Does not check array length (actual may have extra items).
+     *
+     * ```ts
+     * expect(actual).toMatchUnordered([
+     *   { metadata: { name: "b" } },
+     *   { metadata: { name: "a" } },
+     * ]);
+     * ```
+     */
+    toMatchUnordered(expected: ReadonlyArray<unknown>): void;
+  }
+  interface AsymmetricMatchers {
+    toMatchUnordered(expected: ReadonlyArray<unknown>): void;
+  }
+}

package/ts/index.ts

@@ -1,3 +1,4 @@
 /** biome-ignore-all lint/performance/noBarrelFile: that's ok */
 export type * from "./apis";
 export { test } from "./test";
+import "./matchers";

package/ts/matchers/index.ts

@@ -0,0 +1,4 @@
+import { expect } from "bun:test";
+import { toMatchUnordered } from "./to-match-unordered";
+
+expect.extend({ toMatchUnordered });

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

@@ -0,0 +1,273 @@
+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,
+  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 false;
+  }
+
+  if (typeof expected !== "object" || typeof actual !== "object") {
+    return false;
+  }
+
+  if (Array.isArray(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>,
+    equals
+  );
+}
+
+function deepPartialMatchArrays(
+  actual: unknown,
+  expected: Array<unknown>,
+  equals?: EqualsFunction
+): boolean {
+  if (!Array.isArray(actual)) {
+    return false;
+  }
+  if (actual.length !== expected.length) {
+    return false;
+  }
+  return expected.every((item, i) => deepPartialMatch(actual[i], item, equals));
+}
+
+function deepPartialMatchObjects(
+  actual: 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], 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 a pairing array and unmatched
+ * actual indices.
+ */
+function findMatching(
+  actual: ReadonlyArray<unknown>,
+  expected: ReadonlyArray<unknown>,
+  equals?: EqualsFunction
+): MatchResult {
+  const usedActual = new Set<number>();
+  const pairing: Array<number> = [];
+
+  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], expectedItem, equals)) {
+        usedActual.add(ai);
+        matched = ai;
+        break;
+      }
+    }
+    pairing.push(matched);
+  }
+
+  const unmatchedActual: Array<number> = [];
+  for (let ai = 0; ai < actual.length; ai++) {
+    if (!usedActual.has(ai)) {
+      unmatchedActual.push(ai);
+    }
+  }
+
+  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;
+    equals: EqualsFunction;
+    utils: { stringify(v: unknown): string };
+  },
+  actual: unknown,
+  expected: ReadonlyArray<unknown>
+): MatcherResult {
+  if (!Array.isArray(actual)) {
+    return {
+      pass: false,
+      message: () =>
+        `expect(received).toMatchUnordered(expected)\n\nReceived value must be an array, but got ${typeof actual}`,
+    };
+  }
+  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 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 { pass, message };
+}