@appthrust/kest 0.16.0 → 0.17.0

package/README.md

@@ -185,6 +185,31 @@ test("resources sync across clusters", async (s) => {
 });
 ```
 
+### Existing Namespaces
+
+When testing resources in namespaces that kest did not create (e.g. system namespaces or namespaces installed by Helm charts), use `useNamespace` to obtain the same namespace-scoped DSL without creating or cleaning up the namespace:
+
+```ts
+test("istio root cert exists", async (s) => {
+  const istio = await s.useNamespace("istio-system");
+  await istio.assert({
+    apiVersion: "v1",
+    kind: "ConfigMap",
+    name: "istio-ca-root-cert",
+    test() {
+      expect(this.data["root-cert.pem"]).toBeDefined();
+    },
+  });
+});
+```
+
+`useNamespace` is also available on `Cluster`:
+
+```ts
+const cluster = await s.useCluster({ context: "kind-kind" });
+const kubeSystem = await cluster.useNamespace("kube-system");
+```
+
 #### CAPI Dynamic Clusters
 
 Kest can resolve [Cluster API](https://cluster-api.sigs.k8s.io/) (CAPI) provisioned clusters automatically. Pass a `ClusterResourceReference` to `useCluster` and Kest will:
@@ -579,6 +604,7 @@ The top-level API surface available in every test callback.
 | `assertList(resource, options?)`                                        | Fetch a list of resources and run assertions                |
 | `assertOne(resource, options?)`                                         | Assert exactly one resource matches, then run assertions    |
 | `newNamespace(name?, options?)`                                         | Create an ephemeral namespace (supports `{ generateName }`) |
+| `useNamespace(name, options?)`                                          | Obtain a `Namespace` for an existing namespace (no cleanup) |
 | `generateName(prefix)`                                                  | Generate a random-suffix name (statistical uniqueness)      |
 | `exec(input, options?)`                                                 | Execute shell commands with optional revert                 |
 | `useCluster(ref, options?)`                                             | Create a cluster-bound API surface                          |
@@ -586,7 +612,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`, `create`, `assertApplyError`, `assertCreateError`, `applyStatus`, `delete`, `label`, `get`, `assert`, `assertAbsence`, `assertList`, `assertOne`) scoped to their namespace or cluster context. `Cluster` additionally supports `newNamespace` and `useCluster`.
+Returned by `newNamespace()`, `useNamespace()`, and `useCluster()` respectively. They expose the same core methods (`apply`, `create`, `assertApplyError`, `assertCreateError`, `applyStatus`, `delete`, `label`, `get`, `assert`, `assertAbsence`, `assertList`, `assertOne`) scoped to their namespace or cluster context. `Cluster` additionally supports `newNamespace`, `useNamespace`, and `useCluster`.
 
 `Namespace` also exposes a `name` property:
 
@@ -1039,6 +1065,7 @@ await ns.apply({
 | Situation                                              | Approach                                  |
 | ------------------------------------------------------ | ----------------------------------------- |
 | Namespaced resource inside `newNamespace()`            | Use a fixed name (default)                |
+| Resource in pre-existing namespace (`useNamespace()`)  | Use a fixed name (default)                |
 | Same-kind resources created multiple times in one test | `s.generateName` or numbered fixed names  |
 | Cluster-scoped resource (e.g. `ClusterRole`, `CRD`)    | `s.generateName` (no namespace isolation) |
 | Fixed name causes unintended upsert / side effects     | `s.generateName`                          |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@appthrust/kest",
-  "version": "0.16.0",
+  "version": "0.17.0",
   "description": "Kubernetes E2E testing framework designed for humans and AI alike",
   "type": "module",
   "module": "ts/index.ts",

package/ts/apis/index.ts

@@ -550,6 +550,38 @@ export interface Scenario {
     options?: undefined | ActionOptions
   ): Promise<Cluster>;
 
+  /**
+   * Obtains a {@link Namespace} interface for an existing namespace.
+   *
+   * Unlike {@link Scenario.newNamespace}, this does **not** create the namespace
+   * and does **not** register a cleanup handler. It verifies the namespace exists
+   * (via `kubectl get namespace <name>`) and returns the same namespace-scoped
+   * DSL surface.
+   *
+   * Use this when testing resources in namespaces that kest did not create, such
+   * as system namespaces or namespaces provisioned by controllers or Helm charts.
+   *
+   * @param name - The name of the existing namespace.
+   * @param options - Retry options such as timeout and polling interval.
+   *
+   * @example
+   * ```ts
+   * const istio = await s.useNamespace("istio-system");
+   * await istio.assert({
+   *   apiVersion: "v1",
+   *   kind: "ConfigMap",
+   *   name: "istio-ca-root-cert",
+   *   test() {
+   *     expect(this.data["root-cert.pem"]).toBeDefined();
+   *   },
+   * });
+   * ```
+   */
+  useNamespace(
+    name: string,
+    options?: undefined | ActionOptions
+  ): Promise<Namespace>;
+
   // BDD(behavior-driven development) actions
 
   /**
@@ -924,13 +956,44 @@ export interface Cluster {
     cluster: ClusterReference,
     options?: undefined | ActionOptions
   ): Promise<Cluster>;
+
+  /**
+   * Obtains a {@link Namespace} interface for an existing namespace in this cluster.
+   *
+   * Unlike {@link Cluster.newNamespace}, this does **not** create the namespace
+   * and does **not** register a cleanup handler. It verifies the namespace exists
+   * (via `kubectl get namespace <name>`) and returns the same namespace-scoped
+   * DSL surface.
+   *
+   * @param name - The name of the existing namespace.
+   * @param options - Retry options such as timeout and polling interval.
+   *
+   * @example
+   * ```ts
+   * const cluster = await s.useCluster({ context: "kind-kind" });
+   * const kubeSystem = await cluster.useNamespace("kube-system");
+   * await kubeSystem.assert({
+   *   apiVersion: "v1",
+   *   kind: "ConfigMap",
+   *   name: "kube-root-ca.crt",
+   *   test() {
+   *     expect(this.data["ca.crt"]).toBeDefined();
+   *   },
+   * });
+   * ```
+   */
+  useNamespace(
+    name: string,
+    options?: undefined | ActionOptions
+  ): Promise<Namespace>;
 }
 
 /**
  * Namespace-bound API surface.
  *
- * A {@link Namespace} is typically obtained via {@link Scenario.newNamespace} or
- * {@link Cluster.newNamespace}.
+ * A {@link Namespace} is typically obtained via {@link Scenario.newNamespace},
+ * {@link Scenario.useNamespace}, {@link Cluster.newNamespace}, or
+ * {@link Cluster.useNamespace}.
  *
  * Operations are scoped by setting the kubectl namespace context (equivalent to
  * passing `kubectl -n <namespace>`).

package/ts/scenario/index.ts

@@ -61,6 +61,7 @@ export function createScenario(deps: CreateScenarioOptions): InternalScenario {
     but: bdd.but(deps),
     generateName: (prefix: string) => generateRandomName(prefix),
     newNamespace: createNewNamespaceFn(deps),
+    useNamespace: createUseNamespaceFn(deps),
     useCluster: createUseClusterFn(deps),
     async cleanup(options?: { skip?: boolean }) {
       if (options?.skip) {
@@ -197,6 +198,31 @@ export const createQueryFn =
     }
   };
 
+export function buildNamespaceSurface(
+  scenarioDeps: CreateScenarioOptions,
+  namespaceName: string
+): Namespace {
+  const namespacedKubectl = scenarioDeps.kubectl.extends({
+    namespace: namespaceName,
+  });
+  const namespacedDeps = { ...scenarioDeps, kubectl: namespacedKubectl };
+  return {
+    name: namespaceName,
+    apply: createMutateFn(namespacedDeps, apply),
+    create: createMutateFn(namespacedDeps, create),
+    assertApplyError: createMutateFn(namespacedDeps, assertApplyError),
+    assertCreateError: createMutateFn(namespacedDeps, assertCreateError),
+    applyStatus: createOneWayMutateFn(namespacedDeps, applyStatus),
+    delete: createOneWayMutateFn(namespacedDeps, deleteResource),
+    label: createOneWayMutateFn(namespacedDeps, label),
+    get: createQueryFn(namespacedDeps, get),
+    assert: createQueryFn(namespacedDeps, assert),
+    assertAbsence: createQueryFn(namespacedDeps, assertAbsence),
+    assertList: createQueryFn(namespacedDeps, assertList),
+    assertOne: createQueryFn(namespacedDeps, assertOne),
+  };
+}
+
 export const createNewNamespaceFn =
   (scenarioDeps: CreateScenarioOptions) =>
   async (
@@ -207,24 +233,34 @@ export const createNewNamespaceFn =
       name,
       options
     );
-    const { kubectl } = scenarioDeps;
-    const namespacedKubectl = kubectl.extends({ namespace: namespaceName });
-    const namespacedDeps = { ...scenarioDeps, kubectl: namespacedKubectl };
-    return {
-      name: namespaceName,
-      apply: createMutateFn(namespacedDeps, apply),
-      create: createMutateFn(namespacedDeps, create),
-      assertApplyError: createMutateFn(namespacedDeps, assertApplyError),
-      assertCreateError: createMutateFn(namespacedDeps, assertCreateError),
-      applyStatus: createOneWayMutateFn(namespacedDeps, applyStatus),
-      delete: createOneWayMutateFn(namespacedDeps, deleteResource),
-      label: createOneWayMutateFn(namespacedDeps, label),
-      get: createQueryFn(namespacedDeps, get),
-      assert: createQueryFn(namespacedDeps, assert),
-      assertAbsence: createQueryFn(namespacedDeps, assertAbsence),
-      assertList: createQueryFn(namespacedDeps, assertList),
-      assertOne: createQueryFn(namespacedDeps, assertOne),
-    };
+    return buildNamespaceSurface(scenarioDeps, namespaceName);
+  };
+
+export const createUseNamespaceFn =
+  (scenarioDeps: CreateScenarioOptions) =>
+  async (
+    name: string,
+    options?: undefined | ActionOptions
+  ): Promise<Namespace> => {
+    const { kubectl, recorder } = scenarioDeps;
+    const description = `useNamespace("${name}")`;
+    recorder.record("ActionStart", { description });
+    let actionErr: undefined | Error;
+    try {
+      await retryUntil(() => kubectl.get("Namespace", name), {
+        ...options,
+        recorder,
+      });
+      return buildNamespaceSurface(scenarioDeps, name);
+    } catch (error) {
+      actionErr = error as Error;
+      throw error;
+    } finally {
+      recorder.record("ActionEnd", {
+        ok: actionErr === undefined,
+        error: actionErr,
+      });
+    }
   };
 
 const createUseClusterFn =

package/ts/scenario/use-cluster.ts

@@ -26,6 +26,7 @@ import {
   createNewNamespaceFn,
   createOneWayMutateFn,
   createQueryFn,
+  createUseNamespaceFn,
 } from "./index";
 
 function isClusterResourceReference(
@@ -56,6 +57,7 @@ export function buildClusterSurface(deps: CreateScenarioOptions): Cluster {
     assertList: createQueryFn(deps, assertList),
     assertOne: createQueryFn(deps, assertOne),
     newNamespace: createNewNamespaceFn(deps),
+    useNamespace: createUseNamespaceFn(deps),
     useCluster: (
       cluster: ClusterReference,
       options?: ActionOptions