@appthrust/kest 0.3.0 → 0.3.1

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:
@@ -398,6 +413,7 @@ The top-level API surface available in every test callback.
 | 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       |
@@ -412,7 +428,7 @@ 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`, `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.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

@@ -30,6 +30,15 @@ export const applyNamespace = {
       });
       return { revert, output: name };
     },
+  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 {

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/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;
+}

package/ts/recording/index.ts

@@ -1,126 +1,92 @@
-interface BaseEvent<
-  Kind extends string,
-  Data extends Record<string, unknown> = Record<string, never>,
-> {
-  readonly kind: Kind;
-  readonly data: Data;
-}
-
 export type Event =
-  | ScenarioStartedEvent
-  | CommandRunEvent
-  | CommandResultEvent
-  | RetryEvent
+  | ScenarioEvent
   | ActionEvent
+  | CommandEvent
+  | RetryEvent
   | RevertingsEvent
   | BDDEvent;
 
-export type ScenarioStartedEvent = BaseEvent<
-  "ScenarioStarted",
-  {
-    readonly name: string;
-  }
->;
-
-export type RetryEvent =
-  | RetryStartEvent
-  | RetryAttemptEvent
-  | RetryFailureEvent
-  | RetryEndEvent;
+type ScenarioEvent =
+  | BaseEvent<
+      "ScenarioStart",
+      {
+        readonly name: string;
+      }
+    >
+  | BaseEvent<"ScenarioEnd", Record<string, never>>;
+
+type ActionEvent =
+  | BaseEvent<
+      "ActionStart",
+      {
+        readonly description: string;
+      }
+    >
+  | BaseEvent<
+      "ActionEnd",
+      {
+        readonly ok: boolean;
+        readonly error?: undefined | Error;
+      }
+    >;
+
+type CommandEvent =
+  | BaseEvent<
+      "CommandRun",
+      {
+        readonly cmd: string;
+        readonly args: ReadonlyArray<string>;
+        readonly stdin?: undefined | string;
+        readonly stdinLanguage?: undefined | string;
+      }
+    >
+  | BaseEvent<
+      "CommandResult",
+      {
+        readonly exitCode: number;
+        readonly stdout: string;
+        readonly stderr: string;
+        readonly stdoutLanguage?: undefined | string;
+        readonly stderrLanguage?: undefined | string;
+      }
+    >;
+
+type RetryEvent =
+  | BaseEvent<"RetryStart", Record<string, never>>
+  | BaseEvent<
+      "RetryEnd",
+      | {
+          readonly attempts: number;
+          readonly success: true;
+          readonly reason: "success";
+        }
+      | {
+          readonly attempts: number;
+          readonly success: false;
+          readonly reason: "timeout";
+          readonly error: Error;
+        }
+    >;
+
+type RevertingsEvent =
+  | BaseEvent<"RevertingsStart">
+  | BaseEvent<"RevertingsEnd">;
+
+type BDDEvent =
+  | BaseEvent<"BDDGiven", { readonly description: string }>
+  | BaseEvent<"BDDWhen", { readonly description: string }>
+  | BaseEvent<"BDDThen", { readonly description: string }>
+  | BaseEvent<"BDDAnd", { readonly description: string }>
+  | BaseEvent<"BDBut", { readonly description: string }>;
 
-export interface ErrorSummary {
-  readonly name?: undefined | string;
-  readonly message: string;
+interface BaseEvent<
+  Kind extends string,
+  Data extends Record<string, unknown> = Record<string, never>,
+> {
+  readonly kind: Kind;
+  readonly data: Data;
 }
 
-export type RetryStartEvent = BaseEvent<"RetryStart", Record<string, never>>;
-
-export type RetryAttemptEvent = BaseEvent<
-  "RetryAttempt",
-  {
-    readonly attempt: number;
-  }
->;
-
-export type RetryFailureEvent = BaseEvent<
-  "RetryFailure",
-  {
-    readonly attempt: number;
-    readonly error: ErrorSummary;
-  }
->;
-
-export type RetryEndEvent = BaseEvent<
-  "RetryEnd",
-  | {
-      readonly attempts: number;
-      readonly success: true;
-      readonly reason: "success";
-    }
-  | {
-      readonly attempts: number;
-      readonly success: false;
-      readonly reason: "timeout";
-      readonly error: ErrorSummary;
-    }
->;
-
-export type CommandRunEvent = BaseEvent<
-  "CommandRun",
-  {
-    readonly cmd: string;
-    readonly args: ReadonlyArray<string>;
-    readonly stdin?: undefined | string;
-    readonly stdinLanguage?: undefined | string;
-  }
->;
-
-export type CommandResultEvent = BaseEvent<
-  "CommandResult",
-  {
-    readonly exitCode: number;
-    readonly stdout: string;
-    readonly stderr: string;
-    readonly stdoutLanguage?: undefined | string;
-    readonly stderrLanguage?: undefined | string;
-  }
->;
-
-export type ActionEvent = ActionStartEvent | ActionEndEvent;
-
-export type ActionPhase = "mutate" | "revert" | "query";
-
-export type ActionStartEvent = BaseEvent<
-  "ActionStart",
-  {
-    readonly action: string; // e.g. "CreateNamespaceAction"
-    readonly phase: ActionPhase;
-    readonly input?: undefined | Readonly<Record<string, unknown>>;
-  }
->;
-
-export type ActionEndEvent = BaseEvent<
-  "ActionEnd",
-  {
-    readonly action: string; // e.g. "CreateNamespaceAction"
-    readonly phase: ActionPhase;
-    readonly ok: boolean;
-    readonly error?: undefined | ErrorSummary;
-    readonly output?: undefined | Readonly<Record<string, unknown>>;
-  }
->;
-
-export type RevertingsEvent = RevertingsStartEvent | RevertingsEndEvent;
-export type RevertingsStartEvent = BaseEvent<"RevertingsStart">;
-export type RevertingsEndEvent = BaseEvent<"RevertingsEnd">;
-
-export type BDDEvent = BaseEvent<
-  "BDDGiven" | "BDDWhen" | "BDDThen" | "BDDAnd" | "BDBut",
-  {
-    readonly description: string;
-  }
->;
-
 export class Recorder {
   private readonly events: Array<Event> = [];
 

package/ts/reporter/markdown/index.ts

@@ -0,0 +1,23 @@
+import type { Event } from "../../recording";
+import type { Reporter } from "../interface";
+import { parseEvents } from "./parser";
+import { renderReport } from "./renderer";
+
+export interface MarkdownReporterOptions {
+  /**
+   * If true, keep ANSI escape codes (colors) in error messages.
+   * If false (default), remove ANSI escape codes.
+   */
+  enableANSI?: undefined | boolean;
+}
+
+export function newMarkdownReporter(
+  options: MarkdownReporterOptions = {}
+): Reporter {
+  return {
+    report(events: ReadonlyArray<Event>): Promise<string> {
+      const report = parseEvents(events);
+      return renderReport(report, options);
+    },
+  };
+}

package/ts/reporter/markdown/model.ts

@@ -0,0 +1,63 @@
+export interface Report {
+  scenarios: Array<Scenario>;
+}
+
+export interface Scenario {
+  name: string;
+  overview: Array<OverviewItem>;
+  details: Array<Tagged<"BDDSection", BDDSection> | Tagged<"Action", Action>>;
+  cleanup: Array<CleanupItem>;
+}
+
+type Tagged<Tag extends string, Target extends object> = Target & {
+  readonly type: Tag;
+};
+
+export interface OverviewItem {
+  name: string;
+  status: "pending" | "success" | "failure";
+}
+
+export interface BDDSection {
+  keyword: "given" | "when" | "then" | "and" | "but";
+  description: string;
+  actions: Array<Action>;
+}
+
+export interface Action {
+  name: string;
+  attempts?: undefined | number;
+  command?: undefined | Command;
+  error?: undefined | Error;
+}
+
+export interface Command {
+  cmd: string;
+  args: Array<string>;
+  stdin?: Text;
+  stdout?: Text;
+  stderr?: Text;
+}
+
+export interface Text {
+  text: string;
+  language?: undefined | string;
+}
+
+export interface Error {
+  message: Text;
+  stack?: undefined | string;
+}
+
+export interface CleanupItem {
+  action: string;
+  resource?: undefined | string;
+  status: "success" | "failure";
+  command: CleanupCommand;
+}
+
+export interface CleanupCommand {
+  cmd: string;
+  args: Array<string>;
+  output: string;
+}