@appthrust/kest 0.3.0 → 0.3.2

package/README.md

@@ -119,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:
@@ -239,8 +254,8 @@ await ns.label({
   kind: "ConfigMap",
   name: "my-config",
   labels: {
-    env: "production",   // add a label
-    deprecated: null,    // remove a label
+    env: "production", // add a label
+    deprecated: null, // remove a label
   },
 });
 ```
@@ -295,33 +310,51 @@ test("ConfigMap lifecycle", async (s) => {
 
 ### Markdown Test Reports
 
-When a test fails (or when `KEST_SHOW_REPORT=1` is set), Kest generates a detailed Markdown report showing every action, the exact `kubectl` commands executed, stdout/stderr output, and cleanup results. This provides full transparency into what happened during the test, making troubleshooting straightforward -- for both humans and AI assistants.
+When a test fails (or when `KEST_SHOW_REPORT=1` is set), Kest generates a detailed Markdown report showing every action, the exact `kubectl` commands executed (including stdin manifests), stdout/stderr output, and cleanup results. This provides full transparency into what happened during the test, making troubleshooting straightforward -- for both humans and AI assistants.
 
-```markdown
+````markdown
 # ConfigMap lifecycle
 
 ## Scenario Overview
 
-| #   | Action           | Resource            | Status |
-| --- | ---------------- | ------------------- | ------ |
-| 1   | Create namespace | kest-9hdhj          | ✅     |
-| 2   | Apply            | ConfigMap/my-config | ✅     |
-| 3   | Assert           | ConfigMap/my-config | ✅     |
+| #   | Action                         | Status |
+| --- | ------------------------------ | ------ |
+| 1   | Apply Namespace `kest-9hdhj`   | ✅     |
+| 2   | Apply `ConfigMap` "my-config"  | ✅     |
+| 3   | Assert `ConfigMap` "my-config" | ✅     |
 
 ## Scenario Details
 
 ### Given: a namespace exists
 
-✅ Create Namespace "kest-9hdhj"
+**✅ Apply Namespace `kest-9hdhj`**
+
+```shell
+kubectl apply -f - <<EOF
+apiVersion: v1
+kind: Namespace
+metadata:
+  name: kest-9hdhj
+EOF
+```
+
 ...
 
 ### Cleanup
 
-| #   | Action           | Resource            | Status |
-| --- | ---------------- | ------------------- | ------ |
-| 1   | Delete           | ConfigMap/my-config | ✅     |
-| 2   | Delete namespace | kest-9hdhj          | ✅     |
+| #   | Action                         | Status |
+| --- | ------------------------------ | ------ |
+| 1   | Delete `ConfigMap` "my-config" | ✅     |
+| 2   | Delete Namespace `kest-9hdhj`  | ✅     |
+
+```shellsession
+$ kubectl delete ConfigMap/my-config -n kest-9hdhj
+configmap "my-config" deleted
+
+$ kubectl delete namespace/kest-9hdhj
+namespace "kest-9hdhj" deleted
 ```
+````
 
 ## Getting Started
 
@@ -395,24 +428,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  |
-| `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      |
+| 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                     |
+| `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`, `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`) 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.3.0",
+  "version": "0.3.2",
   "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-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

@@ -22,6 +22,8 @@ export const assertAbsence = {
         `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>;
 
 /**

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/{apply-namespace.ts → create-namespace.ts}

@@ -1,4 +1,4 @@
-import { apply } from "./apply";
+import { create } from "./create";
 import type { MutateDef } from "./types";
 
 /**
@@ -9,19 +9,19 @@ import type { MutateDef } from "./types";
  * - `{ generateName: string }` -- use the string as a prefix followed by
  *   random characters (e.g. `{ generateName: "foo-" }` → `"foo-d7kpn"`).
  */
-export type ApplyNamespaceInput =
+export type CreateNamespaceInput =
   | undefined
   | string
   | { readonly generateName: string };
 
-export const applyNamespace = {
+export const createNamespace = {
   type: "mutate",
-  name: "ApplyNamespace",
+  name: "CreateNamespace",
   mutate:
     ({ kubectl }) =>
     async (input) => {
       const name = resolveNamespaceName(input);
-      const { revert } = await apply.mutate({ kubectl })({
+      const { revert } = await create.mutate({ kubectl })({
         apiVersion: "v1",
         kind: "Namespace",
         metadata: {
@@ -30,9 +30,18 @@ export const applyNamespace = {
       });
       return { revert, output: name };
     },
-} satisfies MutateDef<ApplyNamespaceInput, string>;
+  describe: (input) => {
+    if (input === undefined) {
+      return "Create `Namespace` with auto-generated name";
+    }
+    if (typeof input === "string") {
+      return `Create \`Namespace\` "${input}"`;
+    }
+    return `Create \`Namespace\` with prefix "${input.generateName}"`;
+  },
+} satisfies MutateDef<CreateNamespaceInput, string>;
 
-function resolveNamespaceName(input: ApplyNamespaceInput): string {
+function resolveNamespaceName(input: CreateNamespaceInput): string {
   if (input === undefined) {
     return `kest-${randomConsonantDigits(5)}`;
   }

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

@@ -11,4 +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>;

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/label.ts

@@ -17,4 +17,7 @@ export const label = {
       });
       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> = (

package/ts/apis/index.ts

@@ -54,6 +54,39 @@ export interface Scenario {
     options?: undefined | ActionOptions
   ): Promise<void>;
 
+  /**
+   * Creates a Kubernetes resource with `kubectl create`.
+   *
+   * The manifest is validated and then created. When the action succeeds, Kest
+   * registers a cleanup handler that deletes the resource using
+   * `kubectl delete <kind>/<metadata.name>` during scenario cleanup.
+   *
+   * Unlike {@link Scenario.apply}, this action uses `kubectl create` which
+   * fails if the resource already exists. Use this when you need to ensure the
+   * resource is freshly created (e.g. for resources that use `generateName` or
+   * when you want to guarantee no prior state).
+   *
+   * This action is retried when it throws.
+   *
+   * @template T - The expected Kubernetes resource shape.
+   * @param manifest - YAML string, resource object, or imported YAML module.
+   * @param options - Retry options such as timeout and polling interval.
+   *
+   * @example
+   * ```ts
+   * await s.create({
+   *   apiVersion: "v1",
+   *   kind: "ConfigMap",
+   *   metadata: { name: "my-config" },
+   *   data: { mode: "demo" },
+   * });
+   * ```
+   */
+  create<T extends K8sResource>(
+    manifest: ApplyingManifest<T>,
+    options?: undefined | ActionOptions
+  ): Promise<void>;
+
   /**
    * Applies the `status` subresource using server-side apply.
    *
@@ -442,6 +475,30 @@ export interface Cluster {
     options?: undefined | ActionOptions
   ): Promise<void>;
 
+  /**
+   * Creates a Kubernetes resource with `kubectl create` and registers cleanup.
+   *
+   * Unlike {@link Cluster.apply}, this uses `kubectl create` which fails if the
+   * resource already exists.
+   *
+   * @template T - The expected Kubernetes resource shape.
+   * @param manifest - YAML string, resource object, or imported YAML module.
+   * @param options - Retry options such as timeout and polling interval.
+   *
+   * @example
+   * ```ts
+   * await cluster.create({
+   *   apiVersion: "v1",
+   *   kind: "Namespace",
+   *   metadata: { name: "my-team" },
+   * });
+   * ```
+   */
+  create<T extends K8sResource>(
+    manifest: ApplyingManifest<T>,
+    options?: undefined | ActionOptions
+  ): Promise<void>;
+
   /**
    * Applies the `status` subresource using server-side apply.
    *
@@ -683,6 +740,37 @@ export interface Namespace {
     options?: undefined | ActionOptions
   ): Promise<void>;
 
+  /**
+   * Creates a Kubernetes resource in this namespace with `kubectl create` and
+   * registers cleanup.
+   *
+   * The target namespace is controlled by this {@link Namespace} instance.
+   * Prefer omitting `manifest.metadata.namespace`; if it is set, it must match
+   * this namespace (otherwise `kubectl` fails).
+   *
+   * Unlike {@link Namespace.apply}, this uses `kubectl create` which fails if
+   * the resource already exists.
+   *
+   * @template T - The expected Kubernetes resource shape.
+   * @param manifest - YAML string, resource object, or imported YAML module.
+   * @param options - Retry options such as timeout and polling interval.
+   *
+   * @example
+   * ```ts
+   * const ns = await s.newNamespace("my-ns");
+   * await ns.create({
+   *   apiVersion: "v1",
+   *   kind: "ConfigMap",
+   *   metadata: { name: "my-config" },
+   *   data: { mode: "demo" },
+   * });
+   * ```
+   */
+  create<T extends K8sResource>(
+    manifest: ApplyingManifest<T>,
+    options?: undefined | ActionOptions
+  ): Promise<void>;
+
   /**
    * Applies the `status` subresource in this namespace using server-side apply.
    *

package/ts/k8s-resource/index.ts

@@ -118,3 +118,25 @@ export interface ESM {
 function isESM(value: unknown): value is ESM {
   return typeof value === "object" && value !== null && "default" in value;
 }
+
+export function getResourceMeta(
+  value: unknown
+): undefined | { kind: string; name: string } {
+  if (typeof value === "string") {
+    const result = parseK8sResourceYaml(value);
+    if (result.ok) {
+      return { kind: result.value.kind, name: result.value.metadata.name };
+    }
+  }
+  if (isESM(value)) {
+    const result = parseK8sResourceFromESM(value);
+    if (result.ok) {
+      return { kind: result.value.kind, name: result.value.metadata.name };
+    }
+  }
+  const result = parseK8sResource(value);
+  if (result.ok) {
+    return { kind: result.value.kind, name: result.value.metadata.name };
+  }
+  return undefined;
+}