@appthrust/kest 0.4.0 → 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
 
@@ -462,17 +507,366 @@ Duration strings support units like `"200ms"`, `"5s"`, `"1m"`.
 
 ## Best Practices
 
+### Test API contracts, not controllers
+
+E2E tests should describe **how an API behaves from the user's perspective**, not how a specific controller implements that behavior internally. The subject of every test should be the API resource, not the controller behind it.
+
+Why? Controllers are an implementation detail. They get renamed, split, merged, or rewritten -- but as long as the API contract is unchanged, users are unaffected. If your tests are written in terms of controllers, a harmless refactor can break your entire test suite.
+
+```ts
+// ✅ Good — the subject is the API resource
+test("Tenant API creates namespaces for each tenant", async (s) => {
+  s.given("a Tenant resource is applied");
+  const ns = await s.newNamespace();
+  await ns.apply({
+    apiVersion: "example.com/v1",
+    kind: "Tenant",
+    metadata: { name: "acme" },
+    spec: { namespaces: ["dev", "staging"] },
+  });
+
+  s.then("the Tenant reports Ready=True");
+  await ns.assert({
+    apiVersion: "example.com/v1",
+    kind: "Tenant",
+    name: "acme",
+    test() {
+      expect(this.status?.conditions).toContainEqual(
+        expect.objectContaining({ type: "Ready", status: "True" }),
+      );
+    },
+  });
+});
+```
+
+```ts
+// ❌ Bad — the subject is the controller (implementation detail)
+test("tenant-controller creates namespaces", async (s) => {
+  s.given("tenant-controller is running");
+  // ...
+  s.then("tenant-controller creates child namespaces");
+  // ...
+});
+```
+
+The same principle applies to BDD annotations -- keep `s.given()`, `s.when()`, and `s.then()` free of controller names:
+
+| ❌ Controller-centric                             | ✅ API-centric                            |
+| ------------------------------------------------- | ----------------------------------------- |
+| `s.given("tenant-controller is running")`         | `s.given("a Tenant resource exists")`     |
+| `s.when("tenant-controller reconciles")`          | `s.when("the Tenant spec is updated")`    |
+| `s.then("tenant-controller creates a Namespace")` | `s.then("the expected Namespace exists")` |
+
+### Choosing what to test in E2E
+
+E2E tests are powerful for validating **user-observable behavior** but expensive for verifying internal details. Placing implementation details in E2E tests makes refactoring harder without giving users any extra confidence.
+
+**Good candidates for E2E (API contract):**
+
+- Status transitions -- e.g. a resource reaches `Ready=True` after creation
+- Error feedback -- e.g. invalid input produces an explanatory condition like `Ready=False, reason=InvalidSpec`
+- User-facing side effects -- e.g. resources that users are expected to observe or interact with
+
+```ts
+// ✅ Assert a user-observable status condition
+await ns.assert({
+  apiVersion: "example.com/v1",
+  kind: "Database",
+  name: "my-db",
+  test() {
+    expect(this.status?.conditions).toContainEqual(
+      expect.objectContaining({ type: "Ready", status: "True" }),
+    );
+  },
+});
+```
+
+**Better left to unit / integration tests (implementation details):**
+
+- Internal label keys, annotation formats, or hash values
+- Intermediate resources that users don't directly interact with
+- Controller-internal reconciliation logic and branching
+
+```ts
+// ❌ Avoid — internal label format is an implementation detail
+await ns.assert({
+  apiVersion: "example.com/v1",
+  kind: "Database",
+  name: "my-db",
+  test() {
+    // This label may change without affecting users
+    expect(this.metadata?.labels?.["internal.example.com/config-hash"]).toBe("a1b2c3");
+  },
+});
+```
+
+When you find yourself wanting to E2E-test an intermediate resource, ask: _"Is this part of the public API contract?"_ If yes, document it as such and test it. If no, push the assertion down to a cheaper test layer and keep E2E focused on what users actually see.
+
+### Organizing test files
+
+Structure test directories around **API resources**, not controllers. This makes the test suite resilient to internal refactoring and immediately tells readers _which API behavior_ is being verified.
+
+```
+# ✅ Good — organized by API resource
+tests/e2e/
+├── tenant-api/
+│   ├── creation.test.ts
+│   └── deletion.test.ts
+├── database-api/
+│   └── provisioning.test.ts
+
+# ❌ Bad — organized by controller (implementation detail)
+tests/e2e/
+├── tenant-controller/
+│   ├── creation.test.ts
+│   └── deletion.test.ts
+├── database-controller/
+│   └── provisioning.test.ts
+```
+
+**Refactoring-friendliness checklist** -- the more "yes" answers, the better your E2E tests:
+
+- [ ] Is the subject of every test an API resource (not a controller)?
+- [ ] Can a reader understand the test from the manifest and assertions alone?
+- [ ] Do `then` assertions only check user-observable state (`status`, contracted outputs)?
+- [ ] Would splitting, merging, or renaming controllers leave all tests passing?
+
+### One scenario per file
+
+Put exactly one test scenario in one file -- from the start, not "when it gets big enough."
+
+It may be tempting to group several short scenarios into one file while they are small. But E2E tests grow: assertions get richer, edge-case inputs appear, debug aids are added. Splitting later is far harder than starting separate, and deciding _when_ to split is an unnecessary judgment call. The simplest policy is the best one: one scenario, one file, always.
+
+```
+tests/e2e/tenant-api/
+├── creates-namespaces-for-each-tenant.test.ts
+├── rejects-duplicate-tenant-names.test.ts
+├── updates-status-on-namespace-failure.test.ts
+└── deletes-child-namespaces-on-removal.test.ts
+```
+
+**Why not "split when it gets big"?**
+
+- Tests grow incrementally -- no single commit feels like "the moment to split," so it never happens.
+- Splitting a file retroactively means rewriting imports, moving fixtures, and touching unrelated tests in the same PR.
+- The threshold itself becomes a debate ("Is 250 lines too many? 400?"). A universal rule eliminates the discussion.
+
+Starting with one file per scenario reserves room to grow. Each file has built-in headroom for richer assertions, additional setup steps, and debug annotations -- without ever crowding a neighbor.
+
+**What you get:**
+
+- **Self-contained reading** -- open one file, see the full Given/When/Then without scrolling past unrelated scenarios.
+- **Surgical diffs** -- a change touches exactly one scenario, keeping PRs small and reviews focused.
+- **Failure as an address** -- a failing file name tells you which API contract broke, before you read a single line of output.
+- **Conflict-free collaboration** -- teammates edit different files, not different sections of the same file.
+
+**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` |
+
+**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.
+
+**One-scenario-per-file checklist:**
+
+- [ ] Does each test file contain exactly one scenario?
+- [ ] Does the file name describe the behavior under test (not the controller)?
+- [ ] If a file has multiple scenarios, is there a comment justifying the exception?
+
+### Keep manifests visible in your tests
+
+E2E tests double as living documentation. Every test should read as a self-contained specification: what was applied (Given), what changed (When), and what should be true (Then). When a helper function assembles the entire manifest behind the scenes, the test body may _look_ cleaner -- but it stops serving as documentation because the reader can no longer see the actual input.
+
+```ts
+// ❌ Bad — looks tidy, but the actual manifest is hidden inside makeDeployment().
+//    A reader cannot tell what is being applied without jumping to the helper.
+//    The diff between v1 and v2 is buried in a parameter change.
+function makeDeployment(name: string, image: string) {
+  return {
+    apiVersion: "apps/v1",
+    kind: "Deployment",
+    metadata: { name, labels: { app: name } },
+    spec: {
+      replicas: 2,
+      selector: { matchLabels: { app: name } },
+      template: {
+        metadata: { labels: { app: name } },
+        spec: { containers: [{ name: "app", image }] },
+      },
+    },
+  };
+}
+
+test("rollout updates the image", async (s) => {
+  const ns = await s.newNamespace();
+  await ns.apply(makeDeployment("my-app", "my-app:v1"));
+  await ns.apply(makeDeployment("my-app", "my-app:v2"));
+  // What exactly changed? You have to read makeDeployment to find out.
+});
+```
+
+```ts
+// ✅ Good — the full manifest is right here; the diff between steps is obvious.
+test("rollout updates the image", async (s) => {
+  const ns = await s.newNamespace();
+
+  s.when("I apply a Deployment at v1");
+  await ns.apply({
+    apiVersion: "apps/v1",
+    kind: "Deployment",
+    metadata: { name: "my-app" },
+    spec: {
+      replicas: 2,
+      selector: { matchLabels: { app: "my-app" } },
+      template: {
+        metadata: { labels: { app: "my-app" } },
+        spec: { containers: [{ name: "app", image: "my-app:v1" }] },
+      },
+    },
+  });
+
+  s.when("I update to v2");
+  await ns.apply({
+    apiVersion: "apps/v1",
+    kind: "Deployment",
+    metadata: { name: "my-app" },
+    spec: {
+      replicas: 2,
+      selector: { matchLabels: { app: "my-app" } },
+      template: {
+        metadata: { labels: { app: "my-app" } },
+        spec: { containers: [{ name: "app", image: "my-app:v2" }] },
+        //                                          ^^^^^^^^^ the diff
+      },
+    },
+  });
+});
+```
+
+The duplication is intentional -- in E2E tests, **readability beats DRY**. Duplicated manifests make each test self-explanatory and keep failure reports easy to match against the test source. Notice the `^^^ the diff` comment in the example above -- adding a short inline comment to highlight the key change is a simple technique that makes the intent even clearer.
+
+When manifests become too large to inline comfortably, extract them into **static fixture files** instead of helper functions. Both YAML and TypeScript files work:
+
+```ts
+// ✅ Good — static fixture files keep the input visible at a glance
+await ns.apply(import("./fixtures/deployment-v1.yaml"));
+await ns.apply(import("./fixtures/deployment-v2.yaml"));
+
+// TypeScript files work too — useful when converting from inline objects
+await ns.apply(import("./fixtures/deployment-v1.ts"));
+```
+
+**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 (especially when you create cluster-scoped resources).
+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:
 
-Kest offers a few ways to avoid these collisions:
+```ts
+const ns = await s.newNamespace();
 
-- 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).
+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.**
 
-`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).
+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: deployName }, // "deploy-p3n8r" — what was this test about?
+  // ...
+});
+```
+
+```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();
+
+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" },
+  // ...
+});
+```
+
+**When to use `s.generateName`:**
+
+| 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`                          |
+
+Choose **necessary and sufficient** over "safe side" -- every random suffix is a readability trade-off.
+
+**How the two helpers work:**
+
+- `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");
@@ -492,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.0",
+  "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),
     };
   };