@appthrust/kest 0.3.1 → 0.4.0

package/README.md

@@ -254,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
   },
 });
 ```
@@ -310,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
 
@@ -410,21 +428,22 @@ 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  |
-| `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      |
+| 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                     |
+| `generateName(prefix)`                                                  | Generate a random-suffix name (statistical uniqueness)      |
+| `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
 
@@ -441,6 +460,38 @@ All actions accept an optional options object for retry configuration.
 
 Duration strings support units like `"200ms"`, `"5s"`, `"1m"`.
 
+## Best Practices
+
+### Avoiding naming collisions between tests
+
+When tests run in parallel, hard-coded resource names can collide (especially when you create cluster-scoped resources).
+
+Kest offers a few ways to avoid these collisions:
+
+- 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).
+
+`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).
+
+```ts
+s.given("a cluster-scoped resource name should not collide with other tests");
+const roleName = s.generateName("kest-e2e-role-");
+
+await s.create({
+  apiVersion: "rbac.authorization.k8s.io/v1",
+  kind: "ClusterRole",
+  metadata: { name: roleName },
+  rules: [
+    {
+      apiGroups: [""],
+      resources: ["configmaps"],
+      verbs: ["get", "list"],
+    },
+  ],
+});
+```
+
 ## 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.3.1",
+  "version": "0.4.0",
   "description": "Kubernetes E2E testing framework designed for humans and AI alike",
   "type": "module",
   "module": "ts/index.ts",

package/ts/actions/{apply-namespace.ts → create-namespace.ts}

@@ -1,5 +1,6 @@
-import { apply } from "./apply";
+import { create } from "./create";
 import type { MutateDef } from "./types";
+import { generateName } from "../naming";
 
 /**
  * Input for namespace creation.
@@ -9,19 +10,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: {
@@ -32,30 +33,21 @@ export const applyNamespace = {
     },
   describe: (input) => {
     if (input === undefined) {
-      return "Apply `Namespace` with auto-generated name";
+      return "Create `Namespace` with auto-generated name";
     }
     if (typeof input === "string") {
-      return `Apply \`Namespace\` "${input}"`;
+      return `Create \`Namespace\` "${input}"`;
     }
-    return `Apply \`Namespace\` with prefix "${input.generateName}"`;
+    return `Create \`Namespace\` with prefix "${input.generateName}"`;
   },
-} satisfies MutateDef<ApplyNamespaceInput, string>;
+} satisfies MutateDef<CreateNamespaceInput, string>;
 
-function resolveNamespaceName(input: ApplyNamespaceInput): string {
+function resolveNamespaceName(input: CreateNamespaceInput): string {
   if (input === undefined) {
-    return `kest-${randomConsonantDigits(5)}`;
+    return generateName("kest-", 5);
   }
   if (typeof input === "string") {
     return input;
   }
-  return `${input.generateName}${randomConsonantDigits(5)}`;
-}
-
-function randomConsonantDigits(length = 8): string {
-  const chars = "bcdfghjklmnpqrstvwxyz0123456789";
-  let result = "";
-  for (let i = 0; i < length; i++) {
-    result += chars[Math.floor(Math.random() * chars.length)];
-  }
-  return result;
+  return generateName(input.generateName, 5);
 }

package/ts/apis/index.ts

@@ -332,6 +332,34 @@ export interface Scenario {
     options?: undefined | ActionOptions
   ): Promise<Namespace>;
 
+  /**
+   * Generates a random, Kubernetes-friendly name with the given prefix.
+   *
+   * This is a pure helper (no kubectl calls). Useful when you need multiple
+   * unique names within a single scenario, especially when you need custom
+   * metadata (e.g. labels) and can't use {@link Scenario.newNamespace}.
+   *
+   * @example
+   * ```ts
+   * // Useful for cluster-scoped resources (names must be unique cluster-wide)
+   * const roleName = s.generateName("kest-e2e-role-");
+   *
+   * await s.create({
+   *   apiVersion: "rbac.authorization.k8s.io/v1",
+   *   kind: "ClusterRole",
+   *   metadata: { name: roleName },
+   *   rules: [
+   *     {
+   *       apiGroups: [""],
+   *       resources: ["configmaps"],
+   *       verbs: ["get", "list"],
+   *     },
+   *   ],
+   * });
+   * ```
+   */
+  generateName(prefix: string): string;
+
   // Shell command actions
 
   /**

package/ts/naming/index.ts

@@ -0,0 +1,27 @@
+const consonantDigits = "bcdfghjklmnpqrstvwxyz0123456789";
+
+/**
+ * Generates a random string consisting of consonants and digits.
+ *
+ * This is intended for Kubernetes resource names to avoid accidental words.
+ */
+export function randomConsonantDigits(length = 8): string {
+  let result = "";
+  for (let i = 0; i < length; i++) {
+    result += consonantDigits[Math.floor(Math.random() * consonantDigits.length)];
+  }
+  return result;
+}
+
+/**
+ * Generates a Kubernetes-friendly name by appending a random suffix.
+ *
+ * @example
+ * ```ts
+ * generateName("foo-"); // "foo-d7kpn"
+ * ```
+ */
+export function generateName(prefix: string, suffixLength = 5): string {
+  return `${prefix}${randomConsonantDigits(suffixLength)}`;
+}
+

package/ts/scenario/index.ts

@@ -1,13 +1,13 @@
 import { apply } from "../actions/apply";
-import {
-  type ApplyNamespaceInput,
-  applyNamespace,
-} from "../actions/apply-namespace";
 import { applyStatus } from "../actions/apply-status";
 import { assert } from "../actions/assert";
 import { assertAbsence } from "../actions/assert-absence";
 import { assertList } from "../actions/assert-list";
 import { create } from "../actions/create";
+import {
+  type CreateNamespaceInput,
+  createNamespace,
+} from "../actions/create-namespace";
 import { deleteResource } from "../actions/delete";
 import { exec } from "../actions/exec";
 import { get } from "../actions/get";
@@ -22,6 +22,7 @@ import type {
 } from "../apis";
 import bdd from "../bdd";
 import type { Kubectl } from "../kubectl";
+import { generateName as generateRandomName } from "../naming";
 import type { Recorder } from "../recording";
 import type { Reporter } from "../reporter/interface";
 import { retryUntil } from "../retry";
@@ -51,6 +52,7 @@ export function createScenario(deps: CreateScenarioOptions): InternalScenario {
     then: bdd.then(deps),
     and: bdd.and(deps),
     but: bdd.but(deps),
+    generateName: (prefix: string) => generateRandomName(prefix),
     newNamespace: createNewNamespaceFn(deps),
     useCluster: createUseClusterFn(deps),
     async cleanup() {
@@ -187,10 +189,10 @@ const createQueryFn =
 const createNewNamespaceFn =
   (scenarioDeps: CreateScenarioOptions) =>
   async (
-    name?: ApplyNamespaceInput,
+    name?: CreateNamespaceInput,
     options?: undefined | ActionOptions
   ): Promise<Namespace> => {
-    const namespaceName = await createMutateFn(scenarioDeps, applyNamespace)(
+    const namespaceName = await createMutateFn(scenarioDeps, createNamespace)(
       name,
       options
     );