@appthrust/kest 0.4.1 → 0.5.0

package/README.md

@@ -78,6 +78,13 @@ const ns = await s.newNamespace({ generateName: "foo-" });
 // Namespace name will be like "foo-d7kpn"
 ```
 
+The returned object has a `name` property that holds the generated namespace name:
+
+```ts
+const ns = await s.newNamespace({ generateName: "foo-" });
+console.log(ns.name); //=> "foo-d7kpn"
+```
+
 ### Automatic Cleanup (Reverse-Order, Blocking)
 
 Resources are deleted in the reverse order they were created (LIFO). Kest waits until each resource is fully removed before proceeding, preventing flaky failures caused by lingering resources or `Terminating` namespaces.
@@ -219,6 +226,37 @@ await ns.assertList<ConfigMap>({
 });
 ```
 
+### Single-Resource List Assertions
+
+Assert that exactly one resource of a kind exists (or matches a predicate) and test it:
+
+```ts
+// Assert exactly one ConfigMap exists and check its data
+await ns.assertOne<ConfigMap>({
+  apiVersion: "v1",
+  kind: "ConfigMap",
+  test() {
+    expect(this.data?.mode).toBe("demo");
+  },
+});
+```
+
+Use the optional `where` predicate to narrow candidates when multiple resources exist:
+
+```ts
+// Find the one ConfigMap whose name starts with "generated-"
+await ns.assertOne<ConfigMap>({
+  apiVersion: "v1",
+  kind: "ConfigMap",
+  where: (cm) => cm.metadata.name.startsWith("generated-"),
+  test() {
+    expect(this.data?.mode).toBe("auto");
+  },
+}, { timeout: "30s", interval: "1s" });
+```
+
+`assertOne` throws if zero or more than one resource matches, and retries until exactly one is found or the timeout expires.
+
 ### Absence Assertions
 
 Assert that a resource does not exist (e.g. after deletion or to verify a controller hasn't created something):
@@ -439,6 +477,7 @@ The top-level API surface available in every test callback.
 | `assert(resource, options?)`                                            | Fetch a resource and run assertions with retries            |
 | `assertAbsence(resource, options?)`                                     | Assert that a resource does not exist                       |
 | `assertList(resource, options?)`                                        | Fetch a list of resources and run assertions                |
+| `assertOne(resource, options?)`                                         | Assert exactly one resource matches, then run assertions    |
 | `newNamespace(name?, options?)`                                         | Create an ephemeral namespace (supports `{ generateName }`) |
 | `generateName(prefix)`                                                  | Generate a random-suffix name (statistical uniqueness)      |
 | `exec(input, options?)`                                                 | Execute shell commands with optional revert                 |
@@ -447,7 +486,13 @@ The top-level API surface available in every test callback.
 
 ### Namespace / Cluster
 
-Returned by `newNamespace()` and `useCluster()` respectively. They expose the same core methods (`apply`, `create`, `applyStatus`, `delete`, `label`, `get`, `assert`, `assertAbsence`, `assertList`) scoped to their namespace or cluster context. `Cluster` additionally supports `newNamespace`.
+Returned by `newNamespace()` and `useCluster()` respectively. They expose the same core methods (`apply`, `create`, `applyStatus`, `delete`, `label`, `get`, `assert`, `assertAbsence`, `assertList`, `assertOne`) scoped to their namespace or cluster context. `Cluster` additionally supports `newNamespace`.
+
+`Namespace` also exposes a `name` property:
+
+| Property | Type     | Description                                        |
+| -------- | -------- | -------------------------------------------------- |
+| `name`   | `string` | The generated namespace name (e.g. `"kest-abc12"`) |
 
 ### Action Options
 
@@ -617,11 +662,11 @@ Starting with one file per scenario reserves room to grow. Each file has built-i
 
 **Name files after the behavior they verify.** A reader should know what a test checks without opening the file:
 
-| ✅ Good | ❌ Bad |
-| --- | --- |
-| `creates-namespaces-with-labels.test.ts` | `tenant-test-1.test.ts` |
-| `rejects-reserved-selector-labels.test.ts` | `validation.test.ts` |
-| `rolls-out-when-image-changes.test.ts` | `deployment-tests.test.ts` |
+| ✅ Good                                    | ❌ Bad                     |
+| ------------------------------------------ | -------------------------- |
+| `creates-namespaces-with-labels.test.ts`   | `tenant-test-1.test.ts`    |
+| `rejects-reserved-selector-labels.test.ts` | `validation.test.ts`       |
+| `rolls-out-when-image-changes.test.ts`     | `deployment-tests.test.ts` |
 
 **Exceptions.** Tiny negative-case variations of the same API -- where each case is only a few lines and they are always read together (e.g. boundary-condition lists) -- may share a file. When you do this, leave a comment explaining why, because the exception easily becomes the norm.
 
@@ -714,39 +759,114 @@ await ns.apply(import("./fixtures/deployment-v2.yaml"));
 await ns.apply(import("./fixtures/deployment-v1.ts"));
 ```
 
-If you do use helpers, limit them to **name generation** -- never to assembling `spec`:
+**Manifest-visibility checklist:**
+
+- [ ] Can you understand the full input by reading just the test file?
+- [ ] Is the diff between test steps visible as a spec-level change?
+- [ ] Can you reconstruct the applied manifest from the failure report alone?
+
+### Avoiding naming collisions between tests
+
+When tests run in parallel, hard-coded resource names can collide. In most cases, `newNamespace()` is all you need -- each test gets its own namespace, so names like `"my-config"` or `"my-app"` are already isolated:
 
 ```ts
-// ✅ Good — helper generates a name; the manifest stays in the test
-const name = s.generateName("deploy-");
+const ns = await s.newNamespace();
+
+await ns.apply({
+  apiVersion: "v1",
+  kind: "ConfigMap",
+  metadata: { name: "app-config" }, // safe — no other test shares this namespace
+  data: { mode: "test" },
+});
+```
+
+Because the namespace itself is unique, the resource names inside it don't need to be randomized. **You only need `s.generateName` when `newNamespace` alone is not enough.**
+
+A common mistake is to reach for `s.generateName` on _every_ resource "just to be safe." This adds no real protection when the resources are already in an isolated namespace, and it makes tests harder to read and debug:
+
+```ts
+// ❌ Bad — generateName on namespaced resources inside an isolated namespace.
+//    The random suffixes add noise without preventing any actual collisions.
+const ns = await s.newNamespace();
+
+const configName = s.generateName("cfg-");
+const deployName = s.generateName("deploy-");
+
+await ns.apply({
+  apiVersion: "v1",
+  kind: "ConfigMap",
+  metadata: { name: configName }, // "cfg-x7k2m" — hard to find in logs
+  data: { mode: "test" },
+});
 await ns.apply({
   apiVersion: "apps/v1",
   kind: "Deployment",
-  metadata: { name },
-  spec: {
-    /* full spec here, not hidden in a function */
-  },
+  metadata: { name: deployName }, // "deploy-p3n8r" — what was this test about?
+  // ...
 });
 ```
 
-**Manifest-visibility checklist:**
+```ts
+// ✅ Good — fixed, descriptive names inside an isolated namespace.
+//    The namespace already guarantees no collisions. Fixed names are
+//    easy to read, easy to grep in logs, and match the failure report.
+const ns = await s.newNamespace();
 
-- [ ] Can you understand the full input by reading just the test file?
-- [ ] Is the diff between test steps visible as a spec-level change?
-- [ ] Can you reconstruct the applied manifest from the failure report alone?
-- [ ] Are helper functions limited to name generation (no `spec` assembly)?
+await ns.apply({
+  apiVersion: "v1",
+  kind: "ConfigMap",
+  metadata: { name: "app-config" },
+  data: { mode: "test" },
+});
+await ns.apply({
+  apiVersion: "apps/v1",
+  kind: "Deployment",
+  metadata: { name: "my-app" },
+  // ...
+});
+```
 
-### Avoiding naming collisions between tests
+**When to use `s.generateName`:**
 
-When tests run in parallel, hard-coded resource names can collide (especially when you create cluster-scoped resources).
+| Situation                                              | Approach                                  |
+| ------------------------------------------------------ | ----------------------------------------- |
+| Namespaced resource inside `newNamespace()`            | Use a fixed name (default)                |
+| Same-kind resources created multiple times in one test | `s.generateName` or numbered fixed names  |
+| Cluster-scoped resource (e.g. `ClusterRole`, `CRD`)    | `s.generateName` (no namespace isolation) |
+| Fixed name causes unintended upsert / side effects     | `s.generateName`                          |
 
-Kest offers a few ways to avoid these collisions:
+Choose **necessary and sufficient** over "safe side" -- every random suffix is a readability trade-off.
 
-- Use `s.newNamespace()` to isolate namespaced resources per test (recommended default).
-- Use `s.newNamespace({ generateName: "prefix-" })` to keep isolation while making the namespace name easier to recognize in logs/reports.
-- Use `s.generateName("prefix-")` to generate a random-suffix name when you need additional names outside of `newNamespace` (e.g. cluster-scoped resources).
+**How the two helpers work:**
 
-`s.newNamespace(...)` actually creates the `Namespace` via `kubectl create` and retries on name collisions (regenerating a new name each attempt), so once it succeeds the namespace name is unique in the cluster. `s.generateName(...)` is a pure string helper and provides **statistical uniqueness** only (collisions are extremely unlikely, but not impossible).
+- `newNamespace(...)` creates a `Namespace` via `kubectl create` and retries on name collisions (regenerating a new name each attempt), so once it succeeds the namespace name is guaranteed unique in the cluster.
+- `s.generateName(...)` is a pure string helper that provides **statistical uniqueness** only (collisions are extremely unlikely, but not impossible).
+
+**Using `newNamespace` with `.name` (cross-namespace references):**
+
+Every `Namespace` object returned by `newNamespace` has a `.name` property. When resources in one namespace need to reference another namespace by name -- for example in cross-namespace `spec.*Ref.namespace` fields -- use `.name`:
+
+```ts
+const nsA = await s.newNamespace({ generateName: "infra-" });
+const nsB = await s.newNamespace({ generateName: "app-" });
+
+s.when("I apply a resource in nsB that references nsA");
+await nsB.apply({
+  apiVersion: "example.com/v1",
+  kind: "AppConfig",
+  metadata: { name: "my-app" },
+  spec: {
+    secretStoreRef: {
+      namespace: nsA.name, // e.g. "infra-k7rtn"
+      name: "vault",
+    },
+  },
+});
+```
+
+**Using `s.generateName` (for cluster-scoped resources):**
+
+For cluster-scoped resources (where `newNamespace` is not applicable), use `s.generateName`:
 
 ```ts
 s.given("a cluster-scoped resource name should not collide with other tests");
@@ -766,6 +886,12 @@ await s.create({
 });
 ```
 
+**Naming-collision checklist:**
+
+- [ ] Are namespaced resources inside `newNamespace` using fixed names (not `generateName`)?
+- [ ] Is `generateName` reserved for cluster-scoped resources or multi-instance cases?
+- [ ] Can you identify every resource in the failure report without decoding random suffixes?
+
 ## Type Safety
 
 Define TypeScript interfaces for your Kubernetes resources to get full type checking in manifests and assertions:

package/package.json

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

package/ts/actions/assert-one.ts

@@ -0,0 +1,93 @@
+import { YAML } from "bun";
+import type { K8sResource, ResourceOneTest } from "../apis";
+import { parseK8sResourceListYaml } from "../k8s-resource";
+import type { QueryDef } from "./types";
+
+export const assertOne = {
+  type: "query",
+  name: "AssertOne",
+  query:
+    ({ kubectl }) =>
+    async <T extends K8sResource>(
+      condition: ResourceOneTest<T>
+    ): Promise<T> => {
+      const yaml = await kubectl.list(toKubectlType(condition));
+      const result = parseK8sResourceListYaml(yaml);
+      if (!result.ok) {
+        throw new Error(
+          `Invalid Kubernetes resource list: ${result.violations.join(", ")}`
+        );
+      }
+
+      const fetched = result.value;
+      for (const item of fetched) {
+        assertSameGVK(condition, item);
+      }
+
+      const typed = fetched as Array<T>;
+      const found = findExactlyOne(typed, condition);
+      await condition.test.call(found, found);
+      return found;
+    },
+  describe: <T extends K8sResource>(condition: ResourceOneTest<T>): string => {
+    return `Assert one \`${condition.kind}\` resource`;
+  },
+} satisfies QueryDef<ResourceOneTest, K8sResource>;
+
+function findExactlyOne<T extends K8sResource>(
+  items: Array<T>,
+  condition: ResourceOneTest<T>
+): T {
+  const candidates = condition.where ? items.filter(condition.where) : items;
+  const hasWhere = condition.where !== undefined;
+
+  if (candidates.length === 0) {
+    throw new Error(
+      hasWhere
+        ? `No ${condition.kind} resource found matching the "where" predicate`
+        : `No ${condition.kind} resource found`
+    );
+  }
+
+  if (candidates.length > 1) {
+    throw new Error(
+      hasWhere
+        ? `Expected exactly one ${condition.kind} matching the "where" predicate, but found ${candidates.length}`
+        : `Expected exactly one ${condition.kind}, but found ${candidates.length}`
+    );
+  }
+
+  return candidates[0] as T;
+}
+
+function isSameGVK<T extends K8sResource>(
+  finding: Pick<ResourceOneTest<T>, "apiVersion" | "kind">,
+  fetched: K8sResource
+): fetched is T {
+  return (
+    finding.apiVersion === fetched.apiVersion && finding.kind === fetched.kind
+  );
+}
+
+function assertSameGVK<T extends K8sResource>(
+  finding: Pick<ResourceOneTest<T>, "apiVersion" | "kind">,
+  fetched: K8sResource
+): void {
+  if (!isSameGVK(finding, fetched)) {
+    throw new Error(
+      `Fetched Kubernetes resource: ${YAML.stringify(fetched)} is not expected: ${YAML.stringify(finding)}`
+    );
+  }
+}
+
+function toKubectlType<T extends K8sResource>(
+  condition: Pick<ResourceOneTest<T>, "apiVersion" | "kind">
+): string {
+  const { kind, apiVersion } = condition;
+  const [group, version] = apiVersion.split("/");
+  if (version === undefined) {
+    // core group cannot include version in the type
+    return kind;
+  }
+  return [kind, version, group].filter(Boolean).join(".");
+}

package/ts/apis/index.ts

@@ -296,6 +296,52 @@ export interface Scenario {
     options?: undefined | ActionOptions
   ): Promise<Array<T>>;
 
+  /**
+   * Fetches a list of Kubernetes resources, asserts that exactly one matches
+   * the optional `where` predicate, and runs a test function on it.
+   *
+   * When `where` is omitted, all resources of the given kind are candidates;
+   * the method then asserts that exactly one resource of that kind exists.
+   *
+   * The `test` callback is invoked with `this` bound to the matching resource.
+   * If the callback throws (or rejects), the assertion fails and the whole
+   * action is retried until it succeeds or times out.
+   *
+   * @template T - The expected Kubernetes resource shape.
+   * @param resource - Group/version/kind selector, optional `where` predicate,
+   *   and test callback.
+   * @param options - Retry options such as timeout and polling interval.
+   *
+   * @example
+   * ```ts
+   * // Assert exactly one ConfigMap exists and check its data
+   * await s.assertOne({
+   *   apiVersion: "v1",
+   *   kind: "ConfigMap",
+   *   test() {
+   *     expect(this.data?.mode).toBe("demo");
+   *   },
+   * });
+   * ```
+   *
+   * @example
+   * ```ts
+   * // Find the one ConfigMap whose name starts with "generated-"
+   * await s.assertOne({
+   *   apiVersion: "v1",
+   *   kind: "ConfigMap",
+   *   where: (cm) => cm.metadata.name.startsWith("generated-"),
+   *   test() {
+   *     expect(this.data?.mode).toBe("auto");
+   *   },
+   * });
+   * ```
+   */
+  assertOne<T extends K8sResource>(
+    resource: ResourceOneTest<T>,
+    options?: undefined | ActionOptions
+  ): Promise<T>;
+
   /**
    * Creates a new namespace and returns a namespaced API surface.
    *
@@ -686,6 +732,32 @@ export interface Cluster {
     options?: undefined | ActionOptions
   ): Promise<Array<T>>;
 
+  /**
+   * Fetches a list of Kubernetes resources, asserts that exactly one matches
+   * the optional `where` predicate, and runs a test function on it.
+   *
+   * @template T - The expected Kubernetes resource shape.
+   * @param resource - Group/version/kind selector, optional `where` predicate,
+   *   and test callback.
+   * @param options - Retry options such as timeout and polling interval.
+   *
+   * @example
+   * ```ts
+   * await cluster.assertOne({
+   *   apiVersion: "v1",
+   *   kind: "Namespace",
+   *   where: (ns) => ns.metadata.name === "my-namespace",
+   *   test() {
+   *     expect(this.metadata.labels?.env).toBe("production");
+   *   },
+   * });
+   * ```
+   */
+  assertOne<T extends K8sResource>(
+    resource: ResourceOneTest<T>,
+    options?: undefined | ActionOptions
+  ): Promise<T>;
+
   /**
    * Creates a new namespace in this cluster and returns a namespaced API.
    *
@@ -963,6 +1035,32 @@ export interface Namespace {
     resource: ResourceListTest<T>,
     options?: undefined | ActionOptions
   ): Promise<Array<T>>;
+
+  /**
+   * Fetches a list of namespaced Kubernetes resources, asserts that exactly one
+   * matches the optional `where` predicate, and runs a test function on it.
+   *
+   * @template T - The expected Kubernetes resource shape.
+   * @param resource - Group/version/kind selector, optional `where` predicate,
+   *   and test callback.
+   * @param options - Retry options such as timeout and polling interval.
+   *
+   * @example
+   * ```ts
+   * await ns.assertOne({
+   *   apiVersion: "v1",
+   *   kind: "ConfigMap",
+   *   where: (cm) => cm.metadata.name.startsWith("generated-"),
+   *   test() {
+   *     expect(this.data?.mode).toBe("auto");
+   *   },
+   * });
+   * ```
+   */
+  assertOne<T extends K8sResource>(
+    resource: ResourceOneTest<T>,
+    options?: undefined | ActionOptions
+  ): Promise<T>;
 }
 
 /**
@@ -1146,6 +1244,41 @@ export interface ResourceListTest<T extends K8sResource = K8sResource> {
   ) => unknown | Promise<unknown>;
 }
 
+/**
+ * A test definition for {@link Scenario.assertOne}.
+ *
+ * Fetches a list of resources, filters by an optional `where` predicate, asserts
+ * that exactly one resource matches, then runs the `test` callback on it.
+ */
+export interface ResourceOneTest<T extends K8sResource = K8sResource> {
+  /**
+   * Kubernetes API version (e.g. `"v1"`, `"apps/v1"`).
+   */
+  readonly apiVersion: T["apiVersion"];
+
+  /**
+   * Kubernetes kind (e.g. `"ConfigMap"`, `"Deployment"`).
+   */
+  readonly kind: T["kind"];
+
+  /**
+   * Optional predicate to narrow which resources are candidates.
+   *
+   * When omitted, all resources of the given kind are candidates.
+   * Combined with the strict uniqueness check this means "assert there is
+   * exactly one resource of this kind."
+   */
+  readonly where?: undefined | ((resource: T) => boolean);
+
+  /**
+   * Assertion callback.
+   *
+   * The callback is invoked with `this` bound to the single matching resource.
+   * Throwing (or rejecting) signals a failed assertion.
+   */
+  readonly test: (this: T, resource: T) => unknown | Promise<unknown>;
+}
+
 /**
  * Kubernetes cluster selector for {@link Scenario.useCluster}.
  */

package/ts/scenario/index.ts

@@ -3,6 +3,7 @@ import { applyStatus } from "../actions/apply-status";
 import { assert } from "../actions/assert";
 import { assertAbsence } from "../actions/assert-absence";
 import { assertList } from "../actions/assert-list";
+import { assertOne } from "../actions/assert-one";
 import { create } from "../actions/create";
 import {
   type CreateNamespaceInput,
@@ -46,6 +47,7 @@ export function createScenario(deps: CreateScenarioOptions): InternalScenario {
     assert: createQueryFn(deps, assert),
     assertAbsence: createQueryFn(deps, assertAbsence),
     assertList: createQueryFn(deps, assertList),
+    assertOne: createQueryFn(deps, assertOne),
     given: bdd.given(deps),
     when: bdd.when(deps),
     // biome-ignore lint/suspicious/noThenProperty: BDD DSL uses `then()` method name
@@ -210,6 +212,7 @@ const createNewNamespaceFn =
       assert: createQueryFn(namespacedDeps, assert),
       assertAbsence: createQueryFn(namespacedDeps, assertAbsence),
       assertList: createQueryFn(namespacedDeps, assertList),
+      assertOne: createQueryFn(namespacedDeps, assertOne),
     };
   };
 
@@ -233,6 +236,7 @@ const createUseClusterFn =
       assert: createQueryFn(clusterDeps, assert),
       assertAbsence: createQueryFn(clusterDeps, assertAbsence),
       assertList: createQueryFn(clusterDeps, assertList),
+      assertOne: createQueryFn(clusterDeps, assertOne),
       newNamespace: createNewNamespaceFn(clusterDeps),
     };
   };