@appthrust/kest 0.4.1 → 0.6.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.
@@ -106,17 +113,14 @@ await ns.assert({
 Custom timeouts are supported per action:
 
 ```ts
-await ns.assert(
-  {
-    apiVersion: "apps/v1",
-    kind: "Deployment",
-    name: "my-app",
-    test() {
-      expect(this.status?.availableReplicas).toBe(3);
-    },
+await ns.assert({
+  apiVersion: "apps/v1",
+  kind: "Deployment",
+  name: "my-app",
+  test() {
+    expect(this.status?.availableReplicas).toBe(3);
   },
-  { timeout: "30s", interval: "1s" },
-);
+});
 ```
 
 ### Create Resources
@@ -219,6 +223,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");
+  },
+});
+```
+
+`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):
@@ -231,19 +266,57 @@ await ns.assertAbsence({
 });
 ```
 
-With retry-based polling to wait for a resource to disappear:
+### Error Assertions
+
+Assert that applying or creating a resource produces an error (e.g. an admission webhook rejects the request, or a validation rule fails). The `test` callback inspects the error -- `this` is bound to the `Error`:
 
 ```ts
-await ns.assertAbsence(
-  {
-    apiVersion: "apps/v1",
-    kind: "Deployment",
-    name: "my-app",
+await ns.assertApplyError({
+  apply: {
+    apiVersion: "example.com/v1",
+    kind: "MyResource",
+    metadata: { name: "my-resource" },
+    spec: { immutableField: "changed" },
+  },
+  test() {
+    expect(this.message).toContain("field is immutable");
   },
-  { timeout: "30s", interval: "1s" },
-);
+});
 ```
 
+The `test` callback participates in retry -- if it throws, the action is retried until the callback passes or the timeout expires. This is useful when a webhook is being set up asynchronously:
+
+```ts
+await ns.assertApplyError({
+  apply: {
+    apiVersion: "example.com/v1",
+    kind: "MyResource",
+    metadata: { name: "my-resource" },
+    spec: { immutableField: "changed" },
+  },
+  test(error) {
+    expect(error.message).toContain("field is immutable");
+  },
+});
+```
+
+`assertCreateError` works identically for `kubectl create`:
+
+```ts
+await ns.assertCreateError({
+  create: {
+    apiVersion: "v1",
+    kind: "ConfigMap",
+    metadata: { name: "already-exists" },
+  },
+  test(error) {
+    expect(error.message).toContain("already exists");
+  },
+});
+```
+
+If the apply/create unexpectedly succeeds (e.g. the webhook is not yet active), the resource is immediately reverted and the action retries until the expected error occurs.
+
 ### Label Resources
 
 Add, update, or remove labels on Kubernetes resources using `kubectl label`:
@@ -432,6 +505,8 @@ The top-level API surface available in every test callback.
 | ----------------------------------------------------------------------- | ----------------------------------------------------------- |
 | `apply(manifest, options?)`                                             | Apply a Kubernetes manifest and register cleanup            |
 | `create(manifest, options?)`                                            | Create a Kubernetes resource and register cleanup           |
+| `assertApplyError(input, options?)`                                     | Assert that `kubectl apply` produces an error               |
+| `assertCreateError(input, options?)`                                    | Assert that `kubectl create` produces an error              |
 | `applyStatus(manifest, options?)`                                       | Apply a status subresource (server-side apply)              |
 | `delete(resource, options?)`                                            | Delete a resource by API version, kind, and name            |
 | `label(input, options?)`                                                | Add, update, or remove labels on a resource                 |
@@ -439,6 +514,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 +523,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`, `assertApplyError`, `assertCreateError`, `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 +699,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 +796,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 +923,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.6.0",
   "description": "Kubernetes E2E testing framework designed for humans and AI alike",
   "type": "module",
   "module": "ts/index.ts",

package/ts/actions/assert-apply-error.ts

@@ -0,0 +1,43 @@
+import type { AssertApplyErrorInput } from "../apis";
+import { apply } from "./apply";
+import type { MutateDef } from "./types";
+
+export const assertApplyError = {
+  type: "mutate",
+  name: "AssertApplyError",
+  mutate:
+    ({ kubectl }) =>
+    async (input) => {
+      const applyFn = apply.mutate({ kubectl });
+      let result: Awaited<ReturnType<typeof applyFn>> | undefined;
+      let rejection: Error | undefined;
+      try {
+        result = await applyFn(input.apply);
+      } catch (err) {
+        rejection = err as Error;
+      }
+
+      // Apply succeeded unexpectedly -- revert immediately and throw so that
+      // the scenario wrapper retries.
+      if (result !== undefined) {
+        await result.revert();
+        throw new Error(
+          `Expected ${apply.describe(input.apply)} to err, but it succeeded`
+        );
+      }
+
+      // Apply erred as expected -- run test callback.
+      // biome-ignore lint/style/noNonNullAssertion: rejection is guaranteed non-undefined when result is undefined
+      await input.test.call(rejection!, rejection!);
+
+      return {
+        async revert() {
+          // Nothing to clean up -- the resource was never created.
+        },
+        output: undefined,
+      };
+    },
+  describe: (input) => {
+    return `${apply.describe(input.apply)} (expected error)`;
+  },
+} satisfies MutateDef<AssertApplyErrorInput, void>;

package/ts/actions/assert-create-error.ts

@@ -0,0 +1,43 @@
+import type { AssertCreateErrorInput } from "../apis";
+import { create } from "./create";
+import type { MutateDef } from "./types";
+
+export const assertCreateError = {
+  type: "mutate",
+  name: "AssertCreateError",
+  mutate:
+    ({ kubectl }) =>
+    async (input) => {
+      const createFn = create.mutate({ kubectl });
+      let result: Awaited<ReturnType<typeof createFn>> | undefined;
+      let rejection: Error | undefined;
+      try {
+        result = await createFn(input.create);
+      } catch (err) {
+        rejection = err as Error;
+      }
+
+      // Create succeeded unexpectedly -- revert immediately and throw so that
+      // the scenario wrapper retries.
+      if (result !== undefined) {
+        await result.revert();
+        throw new Error(
+          `Expected ${create.describe(input.create)} to err, but it succeeded`
+        );
+      }
+
+      // Create erred as expected -- run test callback.
+      // biome-ignore lint/style/noNonNullAssertion: rejection is guaranteed non-undefined when result is undefined
+      await input.test.call(rejection!, rejection!);
+
+      return {
+        async revert() {
+          // Nothing to clean up -- the resource was never created.
+        },
+        output: undefined,
+      };
+    },
+  describe: (input) => {
+    return `${create.describe(input.create)} (expected error)`;
+  },
+} satisfies MutateDef<AssertCreateErrorInput, void>;

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/actions/create-namespace.ts

@@ -1,6 +1,6 @@
+import { generateName } from "../naming";
 import { create } from "./create";
 import type { MutateDef } from "./types";
-import { generateName } from "../naming";
 
 /**
  * Input for namespace creation.

package/ts/apis/index.ts

@@ -87,6 +87,75 @@ export interface Scenario {
     options?: undefined | ActionOptions
   ): Promise<void>;
 
+  /**
+   * Asserts that `kubectl apply` produces an error.
+   *
+   * The manifest is applied, and the action succeeds when the API server
+   * returns an error (e.g. an admission webhook rejects the request). The
+   * `test` callback must also pass for the action to succeed.
+   *
+   * If the apply unexpectedly succeeds, the created resource is immediately
+   * reverted and the action is retried until the expected error occurs or the
+   * timeout expires.
+   *
+   * @template T - The expected Kubernetes resource shape.
+   * @param input - Manifest to apply and error assertion callback.
+   * @param options - Retry options such as timeout and polling interval.
+   *
+   * @example
+   * ```ts
+   * await s.assertApplyError({
+   *   apply: {
+   *     apiVersion: "example.com/v1",
+   *     kind: "MyResource",
+   *     metadata: { name: "my-resource" },
+   *     spec: { immutableField: "changed" },
+   *   },
+   *   test() {
+   *     expect(this.message).toContain("field is immutable");
+   *   },
+   * });
+   * ```
+   */
+  assertApplyError<T extends K8sResource>(
+    input: AssertApplyErrorInput<T>,
+    options?: undefined | ActionOptions
+  ): Promise<void>;
+
+  /**
+   * Asserts that `kubectl create` produces an error.
+   *
+   * The manifest is created, and the action succeeds when the API server
+   * returns an error. The `test` callback must also pass for the action to
+   * succeed.
+   *
+   * If the create unexpectedly succeeds, the created resource is immediately
+   * reverted and the action is retried until the expected error occurs or the
+   * timeout expires.
+   *
+   * @template T - The expected Kubernetes resource shape.
+   * @param input - Manifest to create and error assertion callback.
+   * @param options - Retry options such as timeout and polling interval.
+   *
+   * @example
+   * ```ts
+   * await s.assertCreateError({
+   *   create: {
+   *     apiVersion: "v1",
+   *     kind: "ConfigMap",
+   *     metadata: { name: "already-exists" },
+   *   },
+   *   test(error) {
+   *     expect(error.message).toContain("already exists");
+   *   },
+   * });
+   * ```
+   */
+  assertCreateError<T extends K8sResource>(
+    input: AssertCreateErrorInput<T>,
+    options?: undefined | ActionOptions
+  ): Promise<void>;
+
   /**
    * Applies the `status` subresource using server-side apply.
    *
@@ -296,6 +365,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.
    *
@@ -527,6 +642,30 @@ export interface Cluster {
     options?: undefined | ActionOptions
   ): Promise<void>;
 
+  /**
+   * Asserts that `kubectl apply` produces an error.
+   *
+   * @template T - The expected Kubernetes resource shape.
+   * @param input - Manifest to apply and error assertion callback.
+   * @param options - Retry options such as timeout and polling interval.
+   */
+  assertApplyError<T extends K8sResource>(
+    input: AssertApplyErrorInput<T>,
+    options?: undefined | ActionOptions
+  ): Promise<void>;
+
+  /**
+   * Asserts that `kubectl create` produces an error.
+   *
+   * @template T - The expected Kubernetes resource shape.
+   * @param input - Manifest to create and error assertion callback.
+   * @param options - Retry options such as timeout and polling interval.
+   */
+  assertCreateError<T extends K8sResource>(
+    input: AssertCreateErrorInput<T>,
+    options?: undefined | ActionOptions
+  ): Promise<void>;
+
   /**
    * Applies the `status` subresource using server-side apply.
    *
@@ -686,6 +825,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.
    *
@@ -799,6 +964,30 @@ export interface Namespace {
     options?: undefined | ActionOptions
   ): Promise<void>;
 
+  /**
+   * Asserts that `kubectl apply` produces an error in this namespace.
+   *
+   * @template T - The expected Kubernetes resource shape.
+   * @param input - Manifest to apply and error assertion callback.
+   * @param options - Retry options such as timeout and polling interval.
+   */
+  assertApplyError<T extends K8sResource>(
+    input: AssertApplyErrorInput<T>,
+    options?: undefined | ActionOptions
+  ): Promise<void>;
+
+  /**
+   * Asserts that `kubectl create` produces an error in this namespace.
+   *
+   * @template T - The expected Kubernetes resource shape.
+   * @param input - Manifest to create and error assertion callback.
+   * @param options - Retry options such as timeout and polling interval.
+   */
+  assertCreateError<T extends K8sResource>(
+    input: AssertCreateErrorInput<T>,
+    options?: undefined | ActionOptions
+  ): Promise<void>;
+
   /**
    * Applies the `status` subresource in this namespace using server-side apply.
    *
@@ -963,6 +1152,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 +1361,91 @@ 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>;
+}
+
+/**
+ * A test definition for {@link Scenario.assertApplyError},
+ * {@link Cluster.assertApplyError}, and {@link Namespace.assertApplyError}.
+ *
+ * Attempts `kubectl apply` and asserts that the API server returns an error.
+ * When the operation errors as expected, the `test` callback is invoked with
+ * `this` bound to the {@link Error}.
+ */
+export interface AssertApplyErrorInput<T extends K8sResource = K8sResource> {
+  /**
+   * The manifest to apply. Accepts the same formats as {@link Scenario.apply}:
+   * an object literal, a YAML string, or an imported YAML module.
+   */
+  readonly apply: ApplyingManifest<T>;
+
+  /**
+   * Assertion callback invoked when the apply errors as expected.
+   *
+   * `this` is bound to the {@link Error} returned by the API server.
+   * Throwing (or rejecting) signals that the error did not match expectations
+   * and triggers a retry (if timeout allows).
+   */
+  readonly test: (this: Error, error: Error) => unknown | Promise<unknown>;
+}
+
+/**
+ * A test definition for {@link Scenario.assertCreateError},
+ * {@link Cluster.assertCreateError}, and {@link Namespace.assertCreateError}.
+ *
+ * Attempts `kubectl create` and asserts that the API server returns an error.
+ * When the operation errors as expected, the `test` callback is invoked with
+ * `this` bound to the {@link Error}.
+ */
+export interface AssertCreateErrorInput<T extends K8sResource = K8sResource> {
+  /**
+   * The manifest to create. Accepts the same formats as {@link Scenario.create}:
+   * an object literal, a YAML string, or an imported YAML module.
+   */
+  readonly create: ApplyingManifest<T>;
+
+  /**
+   * Assertion callback invoked when the create errors as expected.
+   *
+   * `this` is bound to the {@link Error} returned by the API server.
+   * Throwing (or rejecting) signals that the error did not match expectations
+   * and triggers a retry (if timeout allows).
+   */
+  readonly test: (this: Error, error: Error) => unknown | Promise<unknown>;
+}
+
 /**
  * Kubernetes cluster selector for {@link Scenario.useCluster}.
  */

package/ts/naming/index.ts

@@ -8,7 +8,8 @@ const consonantDigits = "bcdfghjklmnpqrstvwxyz0123456789";
 export function randomConsonantDigits(length = 8): string {
   let result = "";
   for (let i = 0; i < length; i++) {
-    result += consonantDigits[Math.floor(Math.random() * consonantDigits.length)];
+    result +=
+      consonantDigits[Math.floor(Math.random() * consonantDigits.length)];
   }
   return result;
 }
@@ -24,4 +25,3 @@ export function randomConsonantDigits(length = 8): string {
 export function generateName(prefix: string, suffixLength = 5): string {
   return `${prefix}${randomConsonantDigits(suffixLength)}`;
 }
-

package/ts/reporter/markdown/model.ts

@@ -27,7 +27,7 @@ export interface BDDSection {
 export interface Action {
   name: string;
   attempts?: undefined | number;
-  command?: undefined | Command;
+  commands: Array<Command>;
   error?: undefined | Error;
 }
 

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

@@ -114,7 +114,7 @@ function handleActionStart(
     return;
   }
 
-  const action: Action = { name: event.data.description };
+  const action: Action = { name: event.data.description, commands: [] };
   scenario.overview.push({
     name: event.data.description,
     status: "pending",
@@ -180,17 +180,21 @@ function handleCommandResult(
   }
 
   const { currentAction } = state;
-  if (!currentAction?.command) {
+  if (!currentAction || currentAction.commands.length === 0) {
     return;
   }
 
-  currentAction.command.stdout = {
+  const command = currentAction.commands.at(-1);
+  if (!command) {
+    return;
+  }
+  command.stdout = {
     text: event.data.stdout,
     ...(event.data.stdoutLanguage
       ? { language: event.data.stdoutLanguage }
       : {}),
   };
-  currentAction.command.stderr = {
+  command.stderr = {
     text: event.data.stderr,
     ...(event.data.stderrLanguage
       ? { language: event.data.stderrLanguage }
@@ -216,7 +220,7 @@ function handleCommandRun(
   if (!state.currentAction) {
     return;
   }
-  state.currentAction.command = createCommandFromRun(event);
+  state.currentAction.commands.push(createCommandFromRun(event));
 }
 
 function handleScenarioStart(

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

@@ -165,7 +165,7 @@ export function renderReport(
       if (!status) {
         if (action.error) {
           status = "failure";
-        } else if (action.command) {
+        } else if (action.commands.length > 0) {
           status = "success";
         } else {
           status = "pending";
@@ -180,8 +180,7 @@ export function renderReport(
       lines.push(`**${emoji} ${stripAnsi(action.name)}**${attemptsSuffix}`);
       lines.push("");
 
-      const cmd = action.command;
-      if (cmd) {
+      for (const cmd of action.commands) {
         const base = [cmd.cmd, ...cmd.args].join(" ").trim();
         const stdin = cmd.stdin?.text;
         const stdinLanguage = cmd.stdin?.language ?? "text";

package/ts/scenario/index.ts

@@ -2,7 +2,10 @@ import { apply } from "../actions/apply";
 import { applyStatus } from "../actions/apply-status";
 import { assert } from "../actions/assert";
 import { assertAbsence } from "../actions/assert-absence";
+import { assertApplyError } from "../actions/assert-apply-error";
+import { assertCreateError } from "../actions/assert-create-error";
 import { assertList } from "../actions/assert-list";
+import { assertOne } from "../actions/assert-one";
 import { create } from "../actions/create";
 import {
   type CreateNamespaceInput,
@@ -38,6 +41,8 @@ export function createScenario(deps: CreateScenarioOptions): InternalScenario {
   return {
     apply: createMutateFn(deps, apply),
     create: createMutateFn(deps, create),
+    assertApplyError: createMutateFn(deps, assertApplyError),
+    assertCreateError: createMutateFn(deps, assertCreateError),
     applyStatus: createOneWayMutateFn(deps, applyStatus),
     delete: createOneWayMutateFn(deps, deleteResource),
     label: createOneWayMutateFn(deps, label),
@@ -46,6 +51,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
@@ -203,6 +209,8 @@ const createNewNamespaceFn =
       name: namespaceName,
       apply: createMutateFn(namespacedDeps, apply),
       create: createMutateFn(namespacedDeps, create),
+      assertApplyError: createMutateFn(namespacedDeps, assertApplyError),
+      assertCreateError: createMutateFn(namespacedDeps, assertCreateError),
       applyStatus: createOneWayMutateFn(namespacedDeps, applyStatus),
       delete: createOneWayMutateFn(namespacedDeps, deleteResource),
       label: createOneWayMutateFn(namespacedDeps, label),
@@ -210,6 +218,7 @@ const createNewNamespaceFn =
       assert: createQueryFn(namespacedDeps, assert),
       assertAbsence: createQueryFn(namespacedDeps, assertAbsence),
       assertList: createQueryFn(namespacedDeps, assertList),
+      assertOne: createQueryFn(namespacedDeps, assertOne),
     };
   };
 
@@ -226,6 +235,8 @@ const createUseClusterFn =
     return {
       apply: createMutateFn(clusterDeps, apply),
       create: createMutateFn(clusterDeps, create),
+      assertApplyError: createMutateFn(clusterDeps, assertApplyError),
+      assertCreateError: createMutateFn(clusterDeps, assertCreateError),
       applyStatus: createOneWayMutateFn(clusterDeps, applyStatus),
       delete: createOneWayMutateFn(clusterDeps, deleteResource),
       label: createOneWayMutateFn(clusterDeps, label),
@@ -233,6 +244,7 @@ const createUseClusterFn =
       assert: createQueryFn(clusterDeps, assert),
       assertAbsence: createQueryFn(clusterDeps, assertAbsence),
       assertList: createQueryFn(clusterDeps, assertList),
+      assertOne: createQueryFn(clusterDeps, assertOne),
       newNamespace: createNewNamespaceFn(clusterDeps),
     };
   };