@appthrust/kest 0.15.0 → 0.17.0

package/README.md

@@ -185,6 +185,77 @@ 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:
+
+1. Poll the CAPI `Cluster` resource until it reports ready
+2. Fetch the kubeconfig from the `<name>-kubeconfig` Secret (data key `value`)
+3. Write a temporary kubeconfig file and bind kubectl to it
+4. Register cleanup to delete the temp file when the test ends
+
+```ts
+test("CAPI multi-hop: management → child → workload", async (s) => {
+  // 1. Connect to the permanent management cluster
+  const pmc = await s.useCluster({ context: "kind-pmc" });
+
+  // 2. Wait for the child cluster to become ready, then connect
+  const cc = await pmc.useCluster({
+    apiVersion: "cluster.x-k8s.io/v1beta1",
+    kind: "Cluster",
+    name: "child-cluster",
+    namespace: "capi-system",
+  });
+
+  // 3. Chain further — the child cluster manages a workload cluster
+  const wlc = await cc.useCluster({
+    apiVersion: "cluster.x-k8s.io/v1beta1",
+    kind: "Cluster",
+    name: "workload-cluster",
+    namespace: "default",
+  });
+
+  const ns = await wlc.newNamespace();
+  await ns.apply(/* ... */);
+});
+```
+
+**Readiness conditions:**
+
+| API version                     | Condition type |
+| ------------------------------- | -------------- |
+| `cluster.x-k8s.io/v1beta1`     | `Ready`        |
+| `cluster.x-k8s.io/v1beta2`     | `Available`    |
+
+**Secret convention:** Kest reads the kubeconfig from a Secret named `${clusterName}-kubeconfig` with the data key `value`. This follows the default CAPI convention. Your RBAC must grant `get` on Secrets in the namespace where the Cluster resource lives.
+
+**Temp kubeconfig cleanup:** The temporary kubeconfig file is deleted automatically during test cleanup. Set `KEST_PRESERVE_ON_FAILURE=1` to skip cleanup on failure, which keeps the temp file for debugging.
+
 ### Status Subresource Support
 
 Simulate controller behavior by applying status subresources via server-side apply:
@@ -533,14 +604,15 @@ 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)`                                                       | Create a cluster-bound API surface                          |
+| `useCluster(ref, options?)`                                             | 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`, `create`, `assertApplyError`, `assertCreateError`, `applyStatus`, `delete`, `label`, `get`, `assert`, `assertAbsence`, `assertList`, `assertOne`) scoped to their namespace or cluster context. `Cluster` additionally supports `newNamespace`.
+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:
 
@@ -993,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/example/dynamic-cluster.test.ts

@@ -0,0 +1,157 @@
+/** biome-ignore-all lint/style/noDoneCallback: that's not the done callback */
+import { expect } from "bun:test";
+import { type K8sResource, test } from "@appthrust/kest";
+
+interface ConfigMap extends K8sResource {
+  apiVersion: "v1";
+  kind: "ConfigMap";
+  metadata: {
+    name: string;
+  };
+  data: {
+    [key: string]: string;
+  };
+}
+
+test(
+  "Example: provision a CAPI child cluster, connect, and create resources",
+  async (s) => {
+    s.given("a management cluster with CAPI and k0smotron installed");
+    const mgmt = await s.useCluster({ context: "kind-kest-test-cluster-1" });
+
+    s.when("I provision a child cluster via CAPI");
+    await mgmt.apply({
+      apiVersion: "infrastructure.cluster.x-k8s.io/v1beta1",
+      kind: "DockerMachineTemplate",
+      metadata: { name: "child-cluster-worker-mt", namespace: "default" },
+      spec: { template: { spec: {} } },
+    });
+    await mgmt.apply({
+      apiVersion: "bootstrap.cluster.x-k8s.io/v1beta1",
+      kind: "K0sWorkerConfigTemplate",
+      metadata: { name: "child-cluster-worker-config", namespace: "default" },
+      spec: { template: { spec: { version: "v1.31.2+k0s.0" } } },
+    });
+    await mgmt.apply({
+      apiVersion: "infrastructure.cluster.x-k8s.io/v1beta1",
+      kind: "DockerCluster",
+      metadata: {
+        name: "child-cluster",
+        namespace: "default",
+        annotations: { "cluster.x-k8s.io/managed-by": "k0smotron" },
+      },
+      spec: {},
+    });
+    await mgmt.apply({
+      apiVersion: "controlplane.cluster.x-k8s.io/v1beta1",
+      kind: "K0smotronControlPlane",
+      metadata: { name: "child-cluster-cp", namespace: "default" },
+      spec: {
+        version: "v1.31.2-k0s.0",
+        persistence: { type: "emptyDir" },
+        service: {
+          type: "LoadBalancer",
+          apiPort: 6443,
+          konnectivityPort: 8132,
+        },
+        k0sConfig: {
+          apiVersion: "k0s.k0sproject.io/v1beta1",
+          kind: "ClusterConfig",
+          spec: { telemetry: { enabled: false } },
+        },
+      },
+    });
+    await mgmt.apply({
+      apiVersion: "cluster.x-k8s.io/v1beta1",
+      kind: "MachineDeployment",
+      metadata: { name: "child-cluster-workers", namespace: "default" },
+      spec: {
+        clusterName: "child-cluster",
+        replicas: 1,
+        selector: {
+          matchLabels: {
+            "cluster.x-k8s.io/cluster-name": "child-cluster",
+            pool: "worker-pool",
+          },
+        },
+        template: {
+          metadata: {
+            labels: {
+              "cluster.x-k8s.io/cluster-name": "child-cluster",
+              pool: "worker-pool",
+            },
+          },
+          spec: {
+            clusterName: "child-cluster",
+            version: "v1.31.2",
+            bootstrap: {
+              configRef: {
+                apiVersion: "bootstrap.cluster.x-k8s.io/v1beta1",
+                kind: "K0sWorkerConfigTemplate",
+                name: "child-cluster-worker-config",
+              },
+            },
+            infrastructureRef: {
+              apiVersion: "infrastructure.cluster.x-k8s.io/v1beta1",
+              kind: "DockerMachineTemplate",
+              name: "child-cluster-worker-mt",
+            },
+          },
+        },
+      },
+    });
+    await mgmt.apply({
+      apiVersion: "cluster.x-k8s.io/v1beta1",
+      kind: "Cluster",
+      metadata: { name: "child-cluster", namespace: "default" },
+      spec: {
+        clusterNetwork: {
+          pods: { cidrBlocks: ["192.168.0.0/16"] },
+          serviceDomain: "cluster.local",
+          services: { cidrBlocks: ["10.128.0.0/12"] },
+        },
+        controlPlaneRef: {
+          apiVersion: "controlplane.cluster.x-k8s.io/v1beta1",
+          kind: "K0smotronControlPlane",
+          name: "child-cluster-cp",
+        },
+        infrastructureRef: {
+          apiVersion: "infrastructure.cluster.x-k8s.io/v1beta1",
+          kind: "DockerCluster",
+          name: "child-cluster",
+        },
+      },
+    });
+
+    s.and("the child cluster becomes ready");
+    const child = await mgmt.useCluster(
+      {
+        apiVersion: "cluster.x-k8s.io/v1beta1",
+        kind: "Cluster",
+        name: "child-cluster",
+        namespace: "default",
+      },
+      { timeout: "10m", interval: "5s" }
+    );
+
+    s.and("I create a namespace and apply a ConfigMap on the child cluster");
+    const ns = await child.newNamespace();
+    await ns.apply<ConfigMap>({
+      apiVersion: "v1",
+      kind: "ConfigMap",
+      metadata: { name: "hello-from-capi" },
+      data: { source: "management-cluster" },
+    });
+
+    s.then("the ConfigMap should exist on the child cluster");
+    await ns.assert<ConfigMap>({
+      apiVersion: "v1",
+      kind: "ConfigMap",
+      name: "hello-from-capi",
+      test() {
+        expect(this.data["source"]).toBe("management-cluster");
+      },
+    });
+  },
+  { timeout: "15m" }
+);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@appthrust/kest",
-  "version": "0.15.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

@@ -518,10 +518,12 @@ export interface Scenario {
    * The returned {@link Cluster} uses the provided kubeconfig/context for all
    * actions. It does not create any resources by itself.
    *
-   * @param cluster - Target kubeconfig and/or context.
+   * @param cluster - Target cluster reference (static kubeconfig/context or CAPI resource).
+   * @param options - Retry options such as timeout and polling interval.
    *
    * @example
    * ```ts
+   * // Static cluster reference
    * const c = await s.useCluster({ context: "kind-kind" });
    * const ns = await c.newNamespace("my-ns");
    * await ns.apply({
@@ -531,8 +533,54 @@ export interface Scenario {
    *   data: { mode: "cluster" },
    * });
    * ```
+   *
+   * @example
+   * ```ts
+   * // CAPI cluster resource reference
+   * const c = await s.useCluster({
+   *   apiVersion: "cluster.x-k8s.io/v1beta1",
+   *   kind: "Cluster",
+   *   name: "workload-1",
+   *   namespace: "default",
+   * });
+   * ```
+   */
+  useCluster(
+    cluster: ClusterReference,
+    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();
+   *   },
+   * });
+   * ```
    */
-  useCluster(cluster: ClusterReference): Promise<Cluster>;
+  useNamespace(
+    name: string,
+    options?: undefined | ActionOptions
+  ): Promise<Namespace>;
 
   // BDD(behavior-driven development) actions
 
@@ -879,13 +927,73 @@ export interface Cluster {
     name?: undefined | string | { readonly generateName: string },
     options?: undefined | ActionOptions
   ): Promise<Namespace>;
+
+  // Multi-cluster actions
+
+  /**
+   * Creates a cluster-bound API surface from this cluster.
+   *
+   * This enables multi-hop cluster access — for example, using a management
+   * cluster to reach a CAPI-provisioned workload cluster.
+   *
+   * @param cluster - Target cluster reference (static or CAPI resource).
+   * @param options - Retry options such as timeout and polling interval.
+   *
+   * @example
+   * ```ts
+   * // From a management cluster, obtain a workload cluster handle
+   * const mgmt = await s.useCluster({ context: "kind-mgmt" });
+   * const workload = await mgmt.useCluster({
+   *   apiVersion: "cluster.x-k8s.io/v1beta1",
+   *   kind: "Cluster",
+   *   name: "workload-1",
+   *   namespace: "default",
+   * });
+   * const ns = await workload.newNamespace("test");
+   * ```
+   */
+  useCluster(
+    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>`).
@@ -1483,9 +1591,14 @@ export interface AssertCreateErrorInput<T extends K8sResource = K8sResource> {
 }
 
 /**
- * Kubernetes cluster selector for {@link Scenario.useCluster}.
+ * Static cluster selector that points to an existing kubeconfig/context.
+ *
+ * Use this when the cluster is already provisioned and you have direct access
+ * to its kubeconfig file or context name.
+ *
+ * @see {@link ClusterReference} — the union accepted by {@link Scenario.useCluster}.
  */
-export interface ClusterReference {
+export interface StaticClusterReference {
   /**
    * Path to a kubeconfig file to use for this cluster.
    */
@@ -1497,6 +1610,63 @@ export interface ClusterReference {
   readonly context?: undefined | string;
 }
 
+/**
+ * Supported Cluster API versions for CAPI-provisioned clusters.
+ */
+export type CapiClusterApiVersion =
+  | "cluster.x-k8s.io/v1beta1"
+  | "cluster.x-k8s.io/v1beta2";
+
+/**
+ * Reference to a CAPI-provisioned cluster resource.
+ *
+ * Kest resolves the cluster's kubeconfig by reading the corresponding
+ * `<name>-kubeconfig` Secret from the management cluster and passes it to
+ * kubectl automatically.
+ *
+ * @example
+ * ```ts
+ * const c = await s.useCluster({
+ *   apiVersion: "cluster.x-k8s.io/v1beta1",
+ *   kind: "Cluster",
+ *   name: "workload-1",
+ *   namespace: "default",
+ * });
+ * ```
+ */
+export interface CapiClusterResourceReference {
+  /** Cluster API group version. */
+  readonly apiVersion: CapiClusterApiVersion;
+
+  /** Must be `"Cluster"`. */
+  readonly kind: "Cluster";
+
+  /** Name of the CAPI Cluster resource. */
+  readonly name: string;
+
+  /** Namespace where the CAPI Cluster resource lives. */
+  readonly namespace: string;
+}
+
+/**
+ * Union of cluster resource reference types.
+ *
+ * Currently only CAPI clusters are supported, but this alias leaves room for
+ * additional providers in the future.
+ */
+export type ClusterResourceReference = CapiClusterResourceReference;
+
+/**
+ * Kubernetes cluster selector for {@link Scenario.useCluster} and
+ * {@link Cluster.useCluster}.
+ *
+ * - {@link StaticClusterReference} — points to an existing kubeconfig/context.
+ * - {@link ClusterResourceReference} — references a CAPI Cluster resource.
+ */
+export type ClusterReference =
+  | StaticClusterReference
+  | ClusterResourceReference;
+
 /**
  * A Kubernetes manifest accepted by Kest actions.
  *

package/ts/kubectl/index.ts

@@ -155,6 +155,26 @@ export interface Kubectl {
     labels: Readonly<Record<string, string | null>>,
     options?: KubectlLabelOptions
   ): Promise<string>;
+
+  /**
+   * Retrieves and base64-decodes a single key from a Kubernetes Secret.
+   *
+   * Runs: `kubectl get secret <name> -o jsonpath='{.data.<key>}'`
+   *
+   * The raw secret value is **not** recorded; the recorded stdout is replaced
+   * with `"<redacted>"` to avoid leaking sensitive data into reports/logs.
+   *
+   * @param name - The name of the Secret resource
+   * @param key - The data key to retrieve (e.g., "password", "kubeconfig")
+   * @param context - Optional context overrides for this call
+   * @returns The base64-decoded value of the requested key
+   * @throws Error if kubectl exits with non-zero code
+   */
+  getSecretData(
+    name: string,
+    key: string,
+    context?: KubectlContext
+  ): Promise<string>;
 }
 
 export interface KubectlDeleteOptions {
@@ -317,6 +337,21 @@ export class RealKubectl implements Kubectl {
     });
   }
 
+  async getSecretData(
+    name: string,
+    key: string,
+    context?: KubectlContext
+  ): Promise<string> {
+    const stdout = await this.runKubectl({
+      args: ["get", "secret", name, "-o", `jsonpath={.data.${key}}`],
+      stdoutLanguage: "text",
+      stderrLanguage: "text",
+      overrideContext: context,
+      redactStdout: true,
+    });
+    return Buffer.from(stdout, "base64").toString("utf-8");
+  }
+
   async label(
     resource: string,
     name: string,
@@ -377,7 +412,7 @@ export class RealKubectl implements Kubectl {
     };
     this.recorder.record("CommandResult", {
       exitCode,
-      stdout,
+      stdout: params.redactStdout ? "<redacted>" : stdout,
       stderr,
       stdoutLanguage: params.stdoutLanguage,
       stderrLanguage: params.stderrLanguage,
@@ -406,6 +441,7 @@ interface ExecParams {
   readonly stdoutLanguage?: undefined | string;
   readonly stderrLanguage?: undefined | string;
   readonly overrideContext?: undefined | KubectlContext;
+  readonly redactStdout?: undefined | boolean;
 }
 
 function stringifyPatch(patch: KubectlPatch): string {

package/ts/scenario/index.ts

@@ -30,6 +30,7 @@ import type { Recorder } from "../recording";
 import type { Reporter } from "../reporter/interface";
 import { retryUntil } from "../retry";
 import type { Reverting } from "../reverting";
+import { resolveCluster } from "./use-cluster";
 
 export interface InternalScenario extends Scenario {
   cleanup(options?: { skip?: boolean }): Promise<void>;
@@ -60,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) {
@@ -74,7 +76,7 @@ export function createScenario(deps: CreateScenarioOptions): InternalScenario {
   };
 }
 
-interface CreateScenarioOptions {
+export interface CreateScenarioOptions {
   readonly name: string;
   readonly recorder: Recorder;
   readonly kubectl: Kubectl;
@@ -82,7 +84,7 @@ interface CreateScenarioOptions {
   readonly reporter: Reporter;
 }
 
-const createMutateFn =
+export const createMutateFn =
   <
     const Action extends MutateDef<Input, Output>,
     Input = Action extends MutateDef<infer I, infer _> ? I : never,
@@ -134,7 +136,7 @@ const createMutateFn =
     }
   };
 
-const createOneWayMutateFn =
+export const createOneWayMutateFn =
   <
     const Action extends OneWayMutateDef<Input, Output>,
     Input = Action extends OneWayMutateDef<infer I, infer _> ? I : never,
@@ -165,7 +167,7 @@ const createOneWayMutateFn =
     }
   };
 
-const createQueryFn =
+export const createQueryFn =
   <
     const Action extends QueryDef<Input, Output>,
     Input = Action extends QueryDef<infer I, infer _> ? I : never,
@@ -196,7 +198,32 @@ const createQueryFn =
     }
   };
 
-const createNewNamespaceFn =
+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 (
     name?: CreateNamespaceInput,
@@ -206,49 +233,38 @@ 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 =
   (scenarioDeps: CreateScenarioOptions) =>
-  // biome-ignore lint/suspicious/useAwait: 将来的にクラスターの接続確認などを行うため、今から async を使用する
-  async (cluster: ClusterReference): Promise<Cluster> => {
-    const { kubectl } = scenarioDeps;
-    const clusterKubectl = kubectl.extends({
-      context: cluster.context,
-      kubeconfig: cluster.kubeconfig,
-    });
-    const clusterDeps = { ...scenarioDeps, kubectl: clusterKubectl };
-    return {
-      apply: createMutateFn(clusterDeps, apply),
-      create: createMutateFn(clusterDeps, create),
-      assertApplyError: createMutateFn(clusterDeps, assertApplyError),
-      assertCreateError: createMutateFn(clusterDeps, assertCreateError),
-      applyStatus: createOneWayMutateFn(clusterDeps, applyStatus),
-      delete: createOneWayMutateFn(clusterDeps, deleteResource),
-      label: createOneWayMutateFn(clusterDeps, label),
-      get: createQueryFn(clusterDeps, get),
-      assert: createQueryFn(clusterDeps, assert),
-      assertAbsence: createQueryFn(clusterDeps, assertAbsence),
-      assertList: createQueryFn(clusterDeps, assertList),
-      assertOne: createQueryFn(clusterDeps, assertOne),
-      newNamespace: createNewNamespaceFn(clusterDeps),
-    };
+  (cluster: ClusterReference, options?: ActionOptions): Promise<Cluster> => {
+    return resolveCluster(scenarioDeps, cluster, options);
   };

package/ts/scenario/use-cluster.ts

@@ -0,0 +1,187 @@
+import { mkdir, unlink } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { apply } from "../actions/apply";
+import { applyStatus } from "../actions/apply-status";
+import { assert } from "../actions/assert";
+import { assertAbsence } from "../actions/assert-absence";
+import { assertApplyError } from "../actions/assert-apply-error";
+import { assertCreateError } from "../actions/assert-create-error";
+import { assertList } from "../actions/assert-list";
+import { assertOne } from "../actions/assert-one";
+import { create } from "../actions/create";
+import { deleteResource } from "../actions/delete";
+import { get } from "../actions/get";
+import { label } from "../actions/label";
+import type {
+  ActionOptions,
+  Cluster,
+  ClusterReference,
+  ClusterResourceReference,
+} from "../apis";
+import { retryUntil } from "../retry";
+import { parseYaml } from "../yaml";
+import {
+  type CreateScenarioOptions,
+  createMutateFn,
+  createNewNamespaceFn,
+  createOneWayMutateFn,
+  createQueryFn,
+  createUseNamespaceFn,
+} from "./index";
+
+function isClusterResourceReference(
+  ref: ClusterReference
+): ref is ClusterResourceReference {
+  return (
+    "apiVersion" in ref &&
+    "kind" in ref &&
+    (ref as unknown as Record<string, unknown>)["kind"] === "Cluster"
+  );
+}
+
+/**
+ * Builds a {@link Cluster} object with all action methods wired to the given deps.
+ */
+export function buildClusterSurface(deps: CreateScenarioOptions): Cluster {
+  return {
+    apply: createMutateFn(deps, apply),
+    create: createMutateFn(deps, create),
+    assertApplyError: createMutateFn(deps, assertApplyError),
+    assertCreateError: createMutateFn(deps, assertCreateError),
+    applyStatus: createOneWayMutateFn(deps, applyStatus),
+    delete: createOneWayMutateFn(deps, deleteResource),
+    label: createOneWayMutateFn(deps, label),
+    get: createQueryFn(deps, get),
+    assert: createQueryFn(deps, assert),
+    assertAbsence: createQueryFn(deps, assertAbsence),
+    assertList: createQueryFn(deps, assertList),
+    assertOne: createQueryFn(deps, assertOne),
+    newNamespace: createNewNamespaceFn(deps),
+    useNamespace: createUseNamespaceFn(deps),
+    useCluster: (
+      cluster: ClusterReference,
+      options?: ActionOptions
+    ): Promise<Cluster> => {
+      return resolveCluster(deps, cluster, options);
+    },
+  };
+}
+
+/**
+ * Resolves a {@link ClusterReference} to a fully-wired {@link Cluster} surface.
+ *
+ * - For {@link StaticClusterReference}: extends kubectl with context/kubeconfig.
+ * - For {@link ClusterResourceReference}: polls CAPI until the cluster is ready,
+ *   fetches the kubeconfig secret, writes a temp file, and returns a Cluster
+ *   bound to that kubeconfig.
+ */
+export async function resolveCluster(
+  deps: CreateScenarioOptions,
+  cluster: ClusterReference,
+  options?: ActionOptions
+): Promise<Cluster> {
+  if (!isClusterResourceReference(cluster)) {
+    // Static cluster reference — same as the original implementation.
+    const clusterKubectl = deps.kubectl.extends({
+      context: cluster.context,
+      kubeconfig: cluster.kubeconfig,
+    });
+    return buildClusterSurface({ ...deps, kubectl: clusterKubectl });
+  }
+
+  // CAPI cluster resource reference
+  const { apiVersion, name, namespace } = cluster;
+  const { recorder, kubectl, reverting } = deps;
+
+  const resourceType = `Cluster.${apiVersion.split("/")[1]}.${apiVersion.split("/")[0]}`;
+  const description = `useCluster(${apiVersion} Cluster "${name}" in "${namespace}")`;
+
+  recorder.record("ActionStart", { description });
+
+  let actionErr: undefined | Error;
+  try {
+    // Poll until the CAPI Cluster is ready.
+    await retryUntil(
+      async () => {
+        const yaml = await kubectl.get(resourceType, name, { namespace });
+        const resource = parseYaml(yaml) as Record<string, unknown>;
+        const status = resource["status"] as
+          | Record<string, unknown>
+          | undefined;
+        if (!status) {
+          throw new Error(
+            `Cluster "${name}" in "${namespace}" has no status yet`
+          );
+        }
+
+        const version = apiVersion.split("/")[1]; // "v1beta1" or "v1beta2"
+        let conditions: Array<Record<string, unknown>> | undefined;
+        let targetType: string;
+
+        if (version === "v1beta1") {
+          conditions = status["conditions"] as
+            | Array<Record<string, unknown>>
+            | undefined;
+          targetType = "Ready";
+        } else if (version === "v1beta2") {
+          const v1beta2 = status["v1beta2"] as
+            | Record<string, unknown>
+            | undefined;
+          conditions = v1beta2?.["conditions"] as
+            | Array<Record<string, unknown>>
+            | undefined;
+          targetType = "Available";
+        } else {
+          throw new Error(`Unsupported CAPI API version: ${apiVersion}`);
+        }
+
+        if (!conditions) {
+          throw new Error(
+            `Cluster "${name}" in "${namespace}" has no conditions`
+          );
+        }
+
+        const condition = conditions.find((c) => c["type"] === targetType);
+        if (!condition || condition["status"] !== "True") {
+          throw new Error(
+            `Cluster "${name}" in "${namespace}" is not ready (${targetType} != True)`
+          );
+        }
+      },
+      { ...options, recorder }
+    );
+
+    // Fetch kubeconfig from the cluster's secret.
+    const kubeconfigData = await retryUntil(
+      () => kubectl.getSecretData(`${name}-kubeconfig`, "value", { namespace }),
+      { timeout: "30s", interval: "1s", recorder }
+    );
+
+    // Write kubeconfig to a temp file.
+    const dir = `${tmpdir()}/kest/kubeconfigs`;
+    await mkdir(dir, { recursive: true });
+    const tempPath = `${dir}/capi-${namespace}-${name}-${crypto.randomUUID()}.yaml`;
+    await Bun.write(tempPath, kubeconfigData);
+
+    // Register cleanup to delete the temp file.
+    reverting.add(async () => {
+      await unlink(tempPath);
+    });
+
+    // Clear the parent's context so kubectl uses the current-context from the
+    // child kubeconfig file rather than the management cluster's context name.
+    const clusterKubectl = kubectl.extends({
+      kubeconfig: tempPath,
+      context: undefined,
+    });
+    return buildClusterSurface({ ...deps, kubectl: clusterKubectl });
+  } catch (error) {
+    actionErr = error as Error;
+    throw error;
+  } finally {
+    recorder.record("ActionEnd", {
+      ok: actionErr === undefined,
+      error: actionErr,
+    });
+  }
+}

package/example/example-report-with-duration.md

@@ -1,142 +0,0 @@
-bun test v1.3.8 (b64edcb4)
-
-example/example.test.ts:
-# Example: applies ConfigMap using YAML, file import, and object literal
-
-## Scenario Overview
-
-| # | Action | Status | Duration |
-|---|--------|--------|----------|
-| 1 | Create `Namespace` with auto-generated name | ✅ | 186ms |
-| 2 | Apply `ConfigMap` "my-config-1" | ✅ | 55ms |
-| 3 | Apply a resource | ✅ | 117ms |
-| 4 | Apply `ConfigMap` "my-config-3" | ✅ | 135ms |
-| 5 | Assert `ConfigMap` "my-config-1" | ✅ | 63ms |
-
-## Scenario Details
-
-### Given: a new namespace exists
-
-**✅ Create `Namespace` with auto-generated name**
-
-```shell
-kubectl create -f - <<EOF
-apiVersion: v1
-kind: Namespace
-metadata: 
-  name: kest-x173q
-EOF
-```
-
-```text title="stdout"
-namespace/kest-x173q created
-```
-
-### When: I apply ConfigMaps using different formats
-
-**✅ Apply `ConfigMap` "my-config-1"**
-
-```shell
-kubectl apply -f - -n kest-x173q <<EOF
-apiVersion: v1
-kind: ConfigMap
-metadata: 
-  name: my-config-1
-data: 
-  mode: demo-1
-EOF
-```
-
-```text title="stdout"
-configmap/my-config-1 created
-```
-
-**✅ Apply a resource**
-
-```shell
-kubectl apply -f - -n kest-x173q <<EOF
-apiVersion: v1
-kind: ConfigMap
-metadata: 
-  name: my-config-2
-data: 
-  mode: demo-2
-EOF
-```
-
-```text title="stdout"
-configmap/my-config-2 created
-```
-
-**✅ Apply `ConfigMap` "my-config-3"**
-
-```shell
-kubectl apply -f - -n kest-x173q <<EOF
-apiVersion: v1
-kind: ConfigMap
-metadata: 
-  name: my-config-3
-data: 
-  mode: demo-3
-EOF
-```
-
-```text title="stdout"
-configmap/my-config-3 created
-```
-
-### Then: the ConfigMap should have the expected data
-
-**✅ Assert `ConfigMap` "my-config-1"**
-
-```shell
-kubectl get ConfigMap my-config-1 -o yaml -n kest-x173q
-```
-
-```yaml title="stdout"
-apiVersion: v1
-data:
-  mode: demo-1
-kind: ConfigMap
-metadata:
-  annotations:
-    kubectl.kubernetes.io/last-applied-configuration: |
-      {"apiVersion":"v1","data":{"mode":"demo-1"},"kind":"ConfigMap","metadata":{"annotations":{},"name":"my-config-1","namespace":"kest-x173q"}}
-  creationTimestamp: "2026-03-02T02:39:15Z"
-  name: my-config-1
-  namespace: kest-x173q
-  resourceVersion: "585"
-  uid: 25339d11-cf6b-44a5-a680-1548d1e80252
-```
-
-### Cleanup
-
-| # | Action | Status | Duration |
-|---|--------|--------|----------|
-| 1 | Apply `ConfigMap` "my-config-3" | ✅ | 75ms |
-| 2 | Apply a resource | ✅ | 41ms |
-| 3 | Apply `ConfigMap` "my-config-1" | ✅ | 36ms |
-| 4 | Create `Namespace` with auto-generated name | ✅ | 5.103s |
-
-```shellsession
-$ kubectl delete ConfigMap/my-config-3 --ignore-not-found -n kest-x173q
-configmap "my-config-3" deleted
-
-$ kubectl delete ConfigMap/my-config-2 --ignore-not-found -n kest-x173q
-configmap "my-config-2" deleted
-
-$ kubectl delete ConfigMap/my-config-1 --ignore-not-found -n kest-x173q
-configmap "my-config-1" deleted
-
-$ kubectl delete Namespace/kest-x173q --ignore-not-found
-namespace "kest-x173q" deleted
-```
-
-**Total: 5.815s** (Actions: 556ms, Cleanup: 5.255s)
-
-
- 1 pass
- 7 filtered out
- 0 fail
- 1 expect() calls
-Ran 1 test across 1 file. [6.04s]