@appthrust/kest 0.3.2 → 0.4.0

package/README.md

@@ -440,6 +440,7 @@ The top-level API surface available in every test callback.
 | `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 }`) |
+| `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                               |
@@ -459,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.2",
+  "version": "0.4.0",
   "description": "Kubernetes E2E testing framework designed for humans and AI alike",
   "type": "module",
   "module": "ts/index.ts",

package/ts/actions/create-namespace.ts

@@ -1,5 +1,6 @@
 import { create } from "./create";
 import type { MutateDef } from "./types";
+import { generateName } from "../naming";
 
 /**
  * Input for namespace creation.
@@ -43,19 +44,10 @@ export const createNamespace = {
 
 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

@@ -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() {