@appthrust/kest 0.2.0 → 0.3.1

package/README.md

@@ -71,6 +71,13 @@ const ns = await s.newNamespace();
 // All resources applied through `ns` are scoped to this namespace.
 ```
 
+You can also specify a custom prefix for the generated namespace name using `generateName`:
+
+```ts
+const ns = await s.newNamespace({ generateName: "foo-" });
+// Namespace name will be like "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.
@@ -112,6 +119,21 @@ await ns.assert(
 );
 ```
 
+### Create Resources
+
+Use `kubectl create` instead of `kubectl apply` when you need to ensure a resource is freshly created (e.g. the resource must not already exist, or you want to use `generateName`):
+
+```ts
+await ns.create({
+  apiVersion: "v1",
+  kind: "ConfigMap",
+  metadata: { name: "my-config" },
+  data: { mode: "demo" },
+});
+```
+
+Like `apply`, `create` registers a cleanup handler that deletes the resource when the test ends. The key difference is that `kubectl create` fails if the resource already exists, whereas `kubectl apply` performs an upsert.
+
 ### Multiple Manifest Formats
 
 Apply resources using whichever format is most convenient:
@@ -197,6 +219,61 @@ await ns.assertList<ConfigMap>({
 });
 ```
 
+### Absence Assertions
+
+Assert that a resource does not exist (e.g. after deletion or to verify a controller hasn't created something):
+
+```ts
+await ns.assertAbsence({
+  apiVersion: "v1",
+  kind: "ConfigMap",
+  name: "deleted-config",
+});
+```
+
+With retry-based polling to wait for a resource to disappear:
+
+```ts
+await ns.assertAbsence(
+  {
+    apiVersion: "apps/v1",
+    kind: "Deployment",
+    name: "my-app",
+  },
+  { timeout: "30s", interval: "1s" },
+);
+```
+
+### Label Resources
+
+Add, update, or remove labels on Kubernetes resources using `kubectl label`:
+
+```ts
+await ns.label({
+  apiVersion: "v1",
+  kind: "ConfigMap",
+  name: "my-config",
+  labels: {
+    env: "production",   // add a label
+    deprecated: null,    // remove a label
+  },
+});
+```
+
+To overwrite an existing label, set `overwrite: true`:
+
+```ts
+await ns.label({
+  apiVersion: "apps/v1",
+  kind: "Deployment",
+  name: "my-app",
+  labels: {
+    version: "v2",
+  },
+  overwrite: true,
+});
+```
+
 ### Shell Command Execution
 
 Run arbitrary shell commands with optional revert handlers for cleanup:
@@ -333,22 +410,25 @@ Entry point for defining a test scenario. The callback receives a `Scenario` obj
 
 The top-level API surface available in every test callback.
 
-| Method                                                                  | Description                                      |
-| ----------------------------------------------------------------------- | ------------------------------------------------ |
-| `apply(manifest, options?)`                                             | Apply a Kubernetes manifest and register cleanup |
-| `applyStatus(manifest, options?)`                                       | Apply a status subresource (server-side apply)   |
-| `delete(resource, options?)`                                            | Delete a resource by API version, kind, and name |
-| `get(resource, options?)`                                               | Fetch a resource by API version, kind, and name  |
-| `assert(resource, options?)`                                            | Fetch a resource and run assertions with retries |
-| `assertList(resource, options?)`                                        | Fetch a list of resources and run assertions     |
-| `newNamespace(name?, options?)`                                         | Create an ephemeral namespace                    |
-| `exec(input, options?)`                                                 | Execute shell commands with optional revert      |
-| `useCluster(ref)`                                                       | Create a cluster-bound API surface               |
-| `given(desc)` / `when(desc)` / `then(desc)` / `and(desc)` / `but(desc)` | BDD annotations for reporting                    |
+| Method                                                                  | Description                                       |
+| ----------------------------------------------------------------------- | ------------------------------------------------- |
+| `apply(manifest, options?)`                                             | Apply a Kubernetes manifest and register cleanup  |
+| `create(manifest, options?)`                                            | Create a Kubernetes resource and register cleanup |
+| `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       |
+| `get(resource, options?)`                                               | Fetch a resource by API version, kind, and name   |
+| `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      |
+| `newNamespace(name?, options?)`                                         | Create an ephemeral namespace (supports `{ generateName }`) |
+| `exec(input, options?)`                                                 | Execute shell commands with optional revert       |
+| `useCluster(ref)`                                                       | Create a cluster-bound API surface                |
+| `given(desc)` / `when(desc)` / `then(desc)` / `and(desc)` / `but(desc)` | BDD annotations for reporting                     |
 
 ### Namespace / Cluster
 
-Returned by `newNamespace()` and `useCluster()` respectively. They expose the same core methods (`apply`, `applyStatus`, `delete`, `get`, `assert`, `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`) scoped to their namespace or cluster context. `Cluster` additionally supports `newNamespace`.
 
 ### Action Options
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@appthrust/kest",
-  "version": "0.2.0",
+  "version": "0.3.1",
   "description": "Kubernetes E2E testing framework designed for humans and AI alike",
   "type": "module",
   "module": "ts/index.ts",
@@ -52,6 +52,7 @@
   "devDependencies": {
     "@biomejs/biome": "^2.3.13",
     "@suin/biome.json": "^0.1.0",
+    "@taml/encoder": "^1.0.0",
     "@tsconfig/bun": "^1.0.10",
     "@tsconfig/strictest": "^2.0.8",
     "@types/bun": "^1.3.7",

package/ts/actions/apply-namespace.ts

@@ -1,13 +1,26 @@
 import { apply } from "./apply";
 import type { MutateDef } from "./types";
 
+/**
+ * Input for namespace creation.
+ *
+ * - `undefined` -- auto-generate a name like `kest-{random}`.
+ * - `string` -- use the exact name provided.
+ * - `{ generateName: string }` -- use the string as a prefix followed by
+ *   random characters (e.g. `{ generateName: "foo-" }` → `"foo-d7kpn"`).
+ */
+export type ApplyNamespaceInput =
+  | undefined
+  | string
+  | { readonly generateName: string };
+
 export const applyNamespace = {
   type: "mutate",
   name: "ApplyNamespace",
   mutate:
     ({ kubectl }) =>
-    async (namespaceName) => {
-      const name = namespaceName ?? `kest-${randomConsonantDigits(5)}`;
+    async (input) => {
+      const name = resolveNamespaceName(input);
       const { revert } = await apply.mutate({ kubectl })({
         apiVersion: "v1",
         kind: "Namespace",
@@ -17,7 +30,26 @@ export const applyNamespace = {
       });
       return { revert, output: name };
     },
-} satisfies MutateDef<undefined | string, string>;
+  describe: (input) => {
+    if (input === undefined) {
+      return "Apply `Namespace` with auto-generated name";
+    }
+    if (typeof input === "string") {
+      return `Apply \`Namespace\` "${input}"`;
+    }
+    return `Apply \`Namespace\` with prefix "${input.generateName}"`;
+  },
+} satisfies MutateDef<ApplyNamespaceInput, string>;
+
+function resolveNamespaceName(input: ApplyNamespaceInput): string {
+  if (input === undefined) {
+    return `kest-${randomConsonantDigits(5)}`;
+  }
+  if (typeof input === "string") {
+    return input;
+  }
+  return `${input.generateName}${randomConsonantDigits(5)}`;
+}
 
 function randomConsonantDigits(length = 8): string {
   const chars = "bcdfghjklmnpqrstvwxyz0123456789";

package/ts/actions/apply-status.ts

@@ -1,5 +1,5 @@
 import type { ApplyingManifest } from "../apis";
-import { parseK8sResourceAny } from "../k8s-resource";
+import { getResourceMeta, parseK8sResourceAny } from "../k8s-resource";
 import type { OneWayMutateDef } from "./types";
 
 export const applyStatus = {
@@ -20,4 +20,11 @@ export const applyStatus = {
       await kubectl.applyStatus(result.value);
       return undefined;
     },
+  describe: (manifest) => {
+    const meta = getResourceMeta(manifest);
+    if (meta === undefined) {
+      return "Apply status of a resource";
+    }
+    return `Apply status of \`${meta.kind}\` "${meta.name}"`;
+  },
 } satisfies OneWayMutateDef<ApplyingManifest, void>;

package/ts/actions/apply.ts

@@ -1,5 +1,5 @@
 import type { ApplyingManifest } from "../apis";
-import { parseK8sResourceAny } from "../k8s-resource";
+import { getResourceMeta, parseK8sResourceAny } from "../k8s-resource";
 import type { MutateDef } from "./types";
 
 export const apply = {
@@ -24,4 +24,11 @@ export const apply = {
         output: undefined,
       };
     },
+  describe: (manifest) => {
+    const meta = getResourceMeta(manifest);
+    if (meta === undefined) {
+      return "Apply a resource";
+    }
+    return `Apply \`${meta.kind}\` "${meta.name}"`;
+  },
 } satisfies MutateDef<ApplyingManifest, void>;

package/ts/actions/assert-absence.ts

@@ -0,0 +1,38 @@
+import type { K8sResource, K8sResourceReference } from "../apis";
+import { toKubectlType } from "./kubectl-type";
+import type { Deps, QueryDef } from "./types";
+
+export const assertAbsence = {
+  type: "query",
+  name: "AssertAbsence",
+  query:
+    ({ kubectl }: Deps) =>
+    async <T extends K8sResource>(
+      resource: K8sResourceReference<T>
+    ): Promise<void> => {
+      try {
+        await kubectl.get(toKubectlType(resource), resource.name);
+      } catch (error) {
+        if (isNotFoundError(error)) {
+          return;
+        }
+        throw error;
+      }
+      throw new Error(
+        `Expected ${resource.kind} "${resource.name}" to be absent, but it exists`
+      );
+    },
+  describe: (resource) =>
+    `Assert that \`${resource.kind}\` "${resource.name}" is absent`,
+} satisfies QueryDef<K8sResourceReference, void>;
+
+/**
+ * Checks whether a kubectl error is a "NotFound" error.
+ *
+ * kubectl outputs `Error from server (NotFound):` when the resource does not
+ * exist, and the {@link RealKubectl} wrapper embeds that message in the
+ * thrown `Error`.
+ */
+function isNotFoundError(error: unknown): boolean {
+  return error instanceof Error && error.message.includes("(NotFound)");
+}

package/ts/actions/assert-list.ts

@@ -28,6 +28,9 @@ export const assertList = {
       await condition.test.call(typed, typed);
       return typed;
     },
+  describe: <T extends K8sResource>(condition: ResourceListTest<T>): string => {
+    return `Assert a list of \`${condition.kind}\` resources`;
+  },
 } satisfies QueryDef<ResourceListTest, Array<K8sResource>>;
 
 function isSameGVK<T extends K8sResource>(

package/ts/actions/assert.ts

@@ -19,6 +19,9 @@ export const assert = {
       await condition.test.call(fetched, fetched);
       return fetched;
     },
+  describe: <T extends K8sResource>(condition: ResourceTest<T>): string => {
+    return `Assert \`${condition.kind}\` "${condition.name}"`;
+  },
 } satisfies QueryDef<ResourceTest, K8sResource>;
 
 function toKubectlType<T extends K8sResource>(

package/ts/actions/create.ts

@@ -0,0 +1,34 @@
+import type { ApplyingManifest } from "../apis";
+import { getResourceMeta, parseK8sResourceAny } from "../k8s-resource";
+import type { MutateDef } from "./types";
+
+export const create = {
+  type: "mutate",
+  name: "Create",
+  mutate:
+    ({ kubectl }) =>
+    async (manifest) => {
+      const result = await parseK8sResourceAny(manifest);
+      if (!result.ok) {
+        throw new Error(
+          `Invalid Kubernetes resource: ${result.violations.join(", ")}`
+        );
+      }
+      await kubectl.create(result.value);
+      return {
+        async revert() {
+          await kubectl.delete(result.value.kind, result.value.metadata.name, {
+            ignoreNotFound: true,
+          });
+        },
+        output: undefined,
+      };
+    },
+  describe: (manifest) => {
+    const meta = getResourceMeta(manifest);
+    if (meta === undefined) {
+      return "Create a resource";
+    }
+    return `Create \`${meta.kind}\` "${meta.name}"`;
+  },
+} satisfies MutateDef<ApplyingManifest, void>;

package/ts/actions/delete.ts

@@ -1,4 +1,5 @@
 import type { K8sResource, K8sResourceReference } from "../apis";
+import { toKubectlType } from "./kubectl-type";
 import type { OneWayMutateDef } from "./types";
 
 export const deleteResource = {
@@ -10,16 +11,7 @@ export const deleteResource = {
       await kubectl.delete(toKubectlType(resource), resource.name);
       return undefined;
     },
+  describe: (resource) => {
+    return `Delete \`${resource.kind}\` "${resource.name}"`;
+  },
 } satisfies OneWayMutateDef<K8sResourceReference, void>;
-
-function toKubectlType<T extends K8sResource>(
-  resource: K8sResourceReference<T>
-): string {
-  const { kind, apiVersion } = resource;
-  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/exec.ts

@@ -17,5 +17,8 @@ export const exec = {
       revert: revert ? () => revert(context) : noopRevert,
     };
   },
+  describe: () => {
+    return "Execute arbitrary processing";
+  },
   // biome-ignore lint/suspicious/noExplicitAny: 本当はunknownにしたいが、createMutateFnとの噛み合せが難しいためanyにしている
 } satisfies MutateDef<ExecInput<any>, unknown>;

package/ts/actions/get.ts

@@ -15,6 +15,9 @@ export const get = {
         ...finding,
         test: (fetched) => assertSameGVK<T>(finding, fetched),
       }),
+  describe: (finding) => {
+    return `Get \`${finding.kind}\` "${finding.name}"`;
+  },
 } satisfies QueryDef<K8sResourceReference, K8sResource>;
 
 function isSameGVK<T extends K8sResource>(

package/ts/actions/kubectl-type.ts

@@ -0,0 +1,19 @@
+/**
+ * Converts an `apiVersion` + `kind` pair into the resource type string
+ * expected by kubectl subcommands (e.g. `get`, `delete`, `label`).
+ *
+ * - Core-group resources (`apiVersion: "v1"`) → `"ConfigMap"`
+ * - Non-core resources (`apiVersion: "apps/v1"`) → `"Deployment.v1.apps"`
+ */
+export function toKubectlType(resource: {
+  readonly apiVersion: string;
+  readonly kind: string;
+}): string {
+  const { kind, apiVersion } = resource;
+  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/label.ts

@@ -0,0 +1,23 @@
+import type { K8sResource, LabelInput } from "../apis";
+import { toKubectlType } from "./kubectl-type";
+import type { OneWayMutateDef } from "./types";
+
+export const label = {
+  type: "oneWayMutate",
+  name: "Label",
+  mutate:
+    ({ kubectl }) =>
+    async <T extends K8sResource>(input: LabelInput<T>) => {
+      const overrideContext = input.namespace
+        ? { namespace: input.namespace }
+        : undefined;
+      await kubectl.label(toKubectlType(input), input.name, input.labels, {
+        overwrite: input.overwrite,
+        context: overrideContext,
+      });
+      return undefined;
+    },
+  describe: (input) => {
+    return `Label \`${input.kind}\` "${input.name}"`;
+  },
+} satisfies OneWayMutateDef<LabelInput, void>;

package/ts/actions/types.ts

@@ -6,6 +6,7 @@ export interface MutateDef<Input, Output> {
   readonly type: "mutate";
   readonly name: string;
   readonly mutate: Mutate<Input, Output>;
+  readonly describe: (input: Input) => string;
 }
 
 export type Mutate<Input, Output> = (
@@ -27,6 +28,7 @@ export interface OneWayMutateDef<Input, Output> {
   readonly type: "oneWayMutate";
   readonly name: string;
   readonly mutate: OneWayMutate<Input, Output>;
+  readonly describe: (input: Input) => string;
 }
 
 export type OneWayMutate<Input, Output> = (
@@ -37,6 +39,7 @@ export interface QueryDef<Input, Output> {
   readonly type: "query";
   readonly name: string;
   readonly query: Query<Input, Output>;
+  readonly describe: (input: Input) => string;
 }
 
 export type Query<Input, Output> = (