@appthrust/kest 0.9.0 → 0.10.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.10.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,141 @@
+import type { MatcherResult } from "bun:test";
+
+/**
+ * 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.
+ */
+export function deepPartialMatch(actual: unknown, expected: unknown): boolean {
+  if (Object.is(actual, expected)) {
+    return true;
+  }
+
+  if (expected === null || actual === null) {
+    return actual === expected;
+  }
+
+  if (typeof expected !== "object" || typeof actual !== "object") {
+    return actual === expected;
+  }
+
+  if (Array.isArray(expected)) {
+    return deepPartialMatchArrays(actual, expected);
+  }
+
+  if (Array.isArray(actual)) {
+    return false;
+  }
+
+  return deepPartialMatchObjects(
+    actual as Record<string, unknown>,
+    expected as Record<string, unknown>
+  );
+}
+
+function deepPartialMatchArrays(
+  actual: unknown,
+  expected: Array<unknown>
+): boolean {
+  if (!Array.isArray(actual)) {
+    return false;
+  }
+  if (actual.length !== expected.length) {
+    return false;
+  }
+  return expected.every((item, i) => deepPartialMatch(actual[i], item));
+}
+
+function deepPartialMatchObjects(
+  actual: Record<string, unknown>,
+  expected: Record<string, unknown>
+): boolean {
+  for (const key of Object.keys(expected)) {
+    if (!(key in actual)) {
+      return false;
+    }
+    if (!deepPartialMatch(actual[key], expected[key])) {
+      return false;
+    }
+  }
+  return true;
+}
+
+/**
+ * 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.
+ */
+function findUnmatched(
+  actual: ReadonlyArray<unknown>,
+  expected: ReadonlyArray<unknown>
+): { unmatchedExpected: Array<number>; unmatchedActual: Array<number> } {
+  const usedActual = new Set<number>();
+  const unmatchedExpected: Array<number> = [];
+
+  for (let ei = 0; ei < expected.length; ei++) {
+    let found = false;
+    for (let ai = 0; ai < actual.length; ai++) {
+      if (usedActual.has(ai)) {
+        continue;
+      }
+      if (deepPartialMatch(actual[ai], expected[ei])) {
+        usedActual.add(ai);
+        found = true;
+        break;
+      }
+    }
+    if (!found) {
+      unmatchedExpected.push(ei);
+    }
+  }
+
+  const unmatchedActual: Array<number> = [];
+  for (let ai = 0; ai < actual.length; ai++) {
+    if (!usedActual.has(ai)) {
+      unmatchedActual.push(ai);
+    }
+  }
+
+  return { unmatchedExpected, unmatchedActual };
+}
+
+export function toMatchUnordered(
+  this: { isNot: boolean; utils: { stringify(v: unknown): string } },
+  actual: unknown,
+  expected: 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}`,
+    };
+  }
+
+  const { unmatchedExpected } = findUnmatched(actual, expected);
+  const pass = unmatchedExpected.length === 0;
+
+  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])}`);
+    }
+    return lines.join("\n");
+  };
+
+  return { pass, message };
+}