@appthrust/kest 0.1.0

package/example/example.test.ts

@@ -0,0 +1,225 @@
+/** 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: applies ConfigMap using YAML, file import, and object literal", async (s) => {
+  s.given("a new namespace exists");
+  // A random namespace is created
+  const ns = await s.newNamespace();
+
+  s.when("I apply ConfigMaps using different formats");
+  // Example of applying YAML
+  await ns.apply(`
+    apiVersion: v1
+    kind: ConfigMap
+    metadata:
+      name: my-config-1
+    data:
+      mode: demo-1
+  `);
+  // Example of applying from a file
+  await ns.apply(import("./config-map.yaml"));
+  // Example of applying with an object literal
+  await ns.apply<ConfigMap>({
+    apiVersion: "v1",
+    kind: "ConfigMap",
+    metadata: { name: "my-config-3" },
+    data: { mode: "demo-3" },
+  });
+
+  s.then("the ConfigMap should have the expected data");
+  await ns.assert<ConfigMap>({
+    apiVersion: "v1",
+    kind: "ConfigMap",
+    name: "my-config-1",
+    // Retries until the following condition is satisfied
+    test() {
+      expect(this).toMatchObject({
+        data: {
+          mode: "demo-1",
+        },
+      });
+    },
+  });
+
+  // Resources created during the test are deleted in reverse order of creation.
+  // 1. ConfigMap/my-config-3
+  // 2. ConfigMap/my-config-2
+  // 3. ConfigMap/my-config-1
+  // 4. Namespace
+});
+
+test("Example: asserts a non-existent ConfigMap (expected to fail)", async (s) => {
+  s.given("a new namespace exists");
+  const ns = await s.newNamespace();
+
+  s.then("asserting a non-existent ConfigMap should fail");
+  // This will fail because no ConfigMap named "non-existent-config" has been created
+  await ns.assert<ConfigMap>({
+    apiVersion: "v1",
+    kind: "ConfigMap",
+    name: "non-existent-config",
+    test() {
+      expect(this).toMatchObject({
+        data: {
+          mode: "should-not-exist",
+        },
+      });
+    },
+  });
+});
+
+test("Example: manages resources across multiple clusters", async (s) => {
+  s.given("two clusters are configured");
+  // Use cluster 1
+  const cluster1 = await s.useCluster({
+    kubeconfig: ".kubeconfig.yaml", // optional
+    context: "kind-kest-test-cluster-1", // optional
+  });
+  // Use cluster 2
+  const cluster2 = await s.useCluster({
+    context: "kind-kest-test-cluster-2",
+  });
+
+  s.when("I apply ConfigMaps to each cluster");
+  // Apply ConfigMap using cluster 1
+  await cluster1.apply<ConfigMap>({
+    apiVersion: "v1",
+    kind: "ConfigMap",
+    metadata: { name: "my-config-1" },
+    data: { mode: "demo-1" },
+  });
+  // Apply ConfigMap using cluster 2
+  await cluster2.apply<ConfigMap>({
+    apiVersion: "v1",
+    kind: "ConfigMap",
+    metadata: { name: "my-config-2" },
+    data: { mode: "demo-2" },
+  });
+
+  s.then("each cluster should have its ConfigMap");
+  // Verify ConfigMap using cluster 1
+  await cluster1.assert<ConfigMap>({
+    apiVersion: "v1",
+    kind: "ConfigMap",
+    name: "my-config-1",
+    test() {
+      expect(this.data["mode"]).toBe("demo-1");
+    },
+  });
+  // Verify ConfigMap using cluster 2
+  await cluster2.assert<ConfigMap>({
+    apiVersion: "v1",
+    kind: "ConfigMap",
+    name: "my-config-2",
+    test() {
+      expect(this.data["mode"]).toBe("demo-2");
+    },
+  });
+});
+
+test("Example: executes shell commands with revert cleanup", async (s) => {
+  const name = await s.exec({
+    do: async ({ $ }) => {
+      const name = "my-secret";
+      await $`kubectl create secret generic ${name} --from-literal=username=admin --from-literal=password=123456`.quiet();
+      return name;
+    },
+    // revert is optional. If specified, it runs during revert. Useful for cleaning up resources created by do.
+    revert: async ({ $ }) => {
+      await $`kubectl delete secret my-secret`.quiet();
+    },
+  });
+  expect(name).toBe("my-secret");
+});
+
+test("Example: asserts resource presence and absence in a list", async (s) => {
+  s.given("a new namespace exists");
+  const ns = await s.newNamespace();
+
+  s.when("I apply a single ConfigMap");
+  await ns.apply<ConfigMap>({
+    apiVersion: "v1",
+    kind: "ConfigMap",
+    metadata: { name: "my-config-1" },
+    data: { mode: "demo-1" },
+  });
+
+  s.then("the list should contain only the applied ConfigMap");
+  await ns.assertList<ConfigMap>({
+    apiVersion: "v1",
+    kind: "ConfigMap",
+    test() {
+      // Verify existence
+      expect(this.some((c) => c.metadata.name === "my-config-1")).toBe(true);
+      // Verify non-existence
+      expect(this.some((c) => c.metadata.name === "my-config-2")).toBe(false);
+    },
+  });
+});
+
+test("Example: applies status subresource to custom resource", async (s) => {
+  s.given("a HelloWorld custom resource definition exists");
+  await s.apply(import("./hello-world-crd.yaml"));
+
+  s.given("a new namespace exists");
+  const ns = await s.newNamespace();
+
+  s.given("a HelloWorld custom resource is created");
+  await ns.apply({
+    apiVersion: "example.com/v2",
+    kind: "HelloWorld",
+    metadata: { name: "my-hello-world" },
+  });
+
+  s.when("I apply a status with Ready condition");
+  await ns.applyStatus({
+    apiVersion: "example.com/v2",
+    kind: "HelloWorld",
+    metadata: { name: "my-hello-world" },
+    status: {
+      conditions: [
+        {
+          type: "Ready",
+          status: "True",
+          lastTransitionTime: "2026-02-05T00:00:00Z",
+          reason: "ManuallySet",
+          message: "Ready condition set to True via server-side apply.",
+        },
+      ],
+    },
+  });
+
+  s.then("the HelloWorld should have the Ready status");
+  await ns.assert({
+    apiVersion: "example.com/v2",
+    kind: "HelloWorld",
+    name: "my-hello-world",
+    test() {
+      expect(this).toMatchObject({
+        status: {
+          conditions: [
+            {
+              type: "Ready",
+              status: "True",
+              lastTransitionTime: "2026-02-05T00:00:00Z",
+              reason: "ManuallySet",
+              message: "Ready condition set to True via server-side apply.",
+            },
+          ],
+        },
+      });
+    },
+  });
+});

package/example/hello-world-crd.yaml

@@ -0,0 +1,145 @@
+apiVersion: apiextensions.k8s.io/v1
+kind: CustomResourceDefinition
+metadata:
+  name: helloworlds.example.com
+spec:
+  group: example.com
+  names:
+    kind: HelloWorld
+    listKind: HelloWorldList
+    plural: helloworlds
+    singular: helloworld
+  scope: Namespaced
+  versions:
+    - name: v1
+      served: true
+      storage: true
+      subresources:
+        status: {}
+      schema:
+        openAPIV3Schema:
+          type: object
+          properties:
+            apiVersion:
+              type: string
+            kind:
+              type: string
+            metadata:
+              type: object
+            status:
+              description: HelloWorldStatus defines the observed state of HelloWorld.
+              type: object
+              properties:
+                conditions:
+                  description: Conditions represent the latest available observations of an object's state.
+                  type: array
+                  x-kubernetes-list-type: map
+                  x-kubernetes-list-map-keys:
+                    - type
+                  items:
+                    description: Condition contains details for one aspect of the current state of this API Resource.
+                    type: object
+                    required:
+                      - type
+                      - status
+                      - lastTransitionTime
+                      - reason
+                      - message
+                    properties:
+                      type:
+                        description: Type of condition in CamelCase or in foo.example.com/CamelCase.
+                        type: string
+                        maxLength: 316
+                        pattern: ^[A-Za-z0-9]([A-Za-z0-9_.-]*[A-Za-z0-9])?$
+                      status:
+                        description: Status of the condition, one of True, False, Unknown.
+                        type: string
+                        enum:
+                          - "True"
+                          - "False"
+                          - "Unknown"
+                      observedGeneration:
+                        description: observedGeneration represents the .metadata.generation that the condition was set based upon.
+                        type: integer
+                        format: int64
+                        minimum: 0
+                      lastTransitionTime:
+                        description: lastTransitionTime is the last time the condition transitioned from one status to another.
+                        type: string
+                        format: date-time
+                      reason:
+                        description: reason contains a programmatic identifier indicating the reason for the condition's last transition.
+                        type: string
+                        minLength: 1
+                        maxLength: 1024
+                        pattern: ^[A-Za-z]([A-Za-z0-9_,:]*[A-Za-z0-9_])?$
+                      message:
+                        description: message is a human readable message indicating details about the transition.
+                        type: string
+                        maxLength: 32768
+    - name: v2
+      served: true
+      storage: false
+      subresources:
+        status: {}
+      schema:
+        openAPIV3Schema:
+          type: object
+          properties:
+            apiVersion:
+              type: string
+            kind:
+              type: string
+            metadata:
+              type: object
+            status:
+              description: HelloWorldStatus defines the observed state of HelloWorld.
+              type: object
+              properties:
+                conditions:
+                  description: Conditions represent the latest available observations of an object's state.
+                  type: array
+                  x-kubernetes-list-type: map
+                  x-kubernetes-list-map-keys:
+                    - type
+                  items:
+                    description: Condition contains details for one aspect of the current state of this API Resource.
+                    type: object
+                    required:
+                      - type
+                      - status
+                      - lastTransitionTime
+                      - reason
+                      - message
+                    properties:
+                      type:
+                        description: Type of condition in CamelCase or in foo.example.com/CamelCase.
+                        type: string
+                        maxLength: 316
+                        pattern: ^[A-Za-z0-9]([A-Za-z0-9_.-]*[A-Za-z0-9])?$
+                      status:
+                        description: Status of the condition, one of True, False, Unknown.
+                        type: string
+                        enum:
+                          - "True"
+                          - "False"
+                          - "Unknown"
+                      observedGeneration:
+                        description: observedGeneration represents the .metadata.generation that the condition was set based upon.
+                        type: integer
+                        format: int64
+                        minimum: 0
+                      lastTransitionTime:
+                        description: lastTransitionTime is the last time the condition transitioned from one status to another.
+                        type: string
+                        format: date-time
+                      reason:
+                        description: reason contains a programmatic identifier indicating the reason for the condition's last transition.
+                        type: string
+                        minLength: 1
+                        maxLength: 1024
+                        pattern: ^[A-Za-z]([A-Za-z0-9_,:]*[A-Za-z0-9_])?$
+                      message:
+                        description: message is a human readable message indicating details about the transition.
+                        type: string
+                        maxLength: 32768

package/package.json

@@ -0,0 +1,62 @@
+{
+  "name": "@appthrust/kest",
+  "version": "0.1.0",
+  "description": "TypeScript-first E2E testing framework for Kubernetes controllers, operators, and webhooks",
+  "type": "module",
+  "module": "ts/index.ts",
+  "exports": {
+    ".": {
+      "types": "./ts/index.ts",
+      "default": "./ts/index.ts"
+    }
+  },
+  "files": [
+    "ts/**/*.ts",
+    "!ts/**/*.test.ts",
+    "example/",
+    "LICENSE",
+    "README.md"
+  ],
+  "keywords": [
+    "kubernetes",
+    "k8s",
+    "e2e",
+    "testing",
+    "bun",
+    "kubectl",
+    "operator",
+    "controller",
+    "webhook",
+    "typescript"
+  ],
+  "author": "appthrust",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/appthrust/kest.git"
+  },
+  "homepage": "https://github.com/appthrust/kest#readme",
+  "bugs": {
+    "url": "https://github.com/appthrust/kest/issues"
+  },
+  "engines": {
+    "bun": ">=1.3.8"
+  },
+  "peerDependencies": {
+    "typescript": "^5"
+  },
+  "dependencies": {
+    "@shikijs/cli": "^3.21.0",
+    "@suin/shell-escape-arg": "^0.1.2"
+  },
+  "devDependencies": {
+    "@biomejs/biome": "^2.3.13",
+    "@suin/biome.json": "^0.1.0",
+    "@tsconfig/bun": "^1.0.10",
+    "@tsconfig/strictest": "^2.0.8",
+    "@types/bun": "^1.3.7",
+    "bun": "^1.3.8",
+    "outdent": "^0.8.0",
+    "oxfmt": "^0.28.0"
+  }
+}

package/ts/actions/apply-namespace.ts

@@ -0,0 +1,29 @@
+import { apply } from "./apply";
+import type { MutateDef } from "./types";
+
+export const applyNamespace = {
+  type: "mutate",
+  name: "ApplyNamespace",
+  mutate:
+    ({ kubectl }) =>
+    async (namespaceName) => {
+      const name = namespaceName ?? `kest-${randomConsonantDigits(5)}`;
+      const { revert } = await apply.mutate({ kubectl })({
+        apiVersion: "v1",
+        kind: "Namespace",
+        metadata: {
+          name,
+        },
+      });
+      return { revert, output: name };
+    },
+} satisfies MutateDef<undefined | string, string>;
+
+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;
+}

package/ts/actions/apply-status.ts

@@ -0,0 +1,23 @@
+import type { ApplyingManifest } from "../apis";
+import { parseK8sResourceAny } from "../k8s-resource";
+import type { OneWayMutateDef } from "./types";
+
+export const applyStatus = {
+  type: "oneWayMutate",
+  name: "ApplyStatus",
+  mutate:
+    ({ kubectl }) =>
+    async (manifest) => {
+      const result = await parseK8sResourceAny(manifest);
+      if (!result.ok) {
+        throw new Error(
+          `Invalid Kubernetes resource: ${result.violations.join(", ")}`
+        );
+      }
+      if (result.value["status"] === undefined) {
+        throw new Error("Invalid Kubernetes resource: status is required");
+      }
+      await kubectl.applyStatus(result.value);
+      return undefined;
+    },
+} satisfies OneWayMutateDef<ApplyingManifest, void>;

package/ts/actions/apply.ts

@@ -0,0 +1,25 @@
+import type { ApplyingManifest } from "../apis";
+import { parseK8sResourceAny } from "../k8s-resource";
+import type { MutateDef } from "./types";
+
+export const apply = {
+  type: "mutate",
+  name: "Apply",
+  mutate:
+    ({ kubectl }) =>
+    async (manifest) => {
+      const result = await parseK8sResourceAny(manifest);
+      if (!result.ok) {
+        throw new Error(
+          `Invalid Kubernetes resource: ${result.violations.join(", ")}`
+        );
+      }
+      await kubectl.apply(result.value);
+      return {
+        async revert() {
+          await kubectl.delete(result.value.kind, result.value.metadata.name);
+        },
+        output: undefined,
+      };
+    },
+} satisfies MutateDef<ApplyingManifest, void>;

package/ts/actions/assert-list.ts

@@ -0,0 +1,63 @@
+import { YAML } from "bun";
+import type { K8sResource, ResourceListTest } from "../apis";
+import { parseK8sResourceListYaml } from "../k8s-resource";
+import type { Deps, QueryDef } from "./types";
+
+export const assertList = {
+  type: "query",
+  name: "AssertList",
+  query:
+    ({ kubectl }: Deps) =>
+    async <T extends K8sResource>(
+      condition: ResourceListTest<T>
+    ): Promise<Array<T>> => {
+      const yaml = await kubectl.list(toKubectlType(condition));
+      const result = parseK8sResourceListYaml(yaml);
+      if (!result.ok) {
+        throw new Error(
+          `Invalid Kubernetes resource list: ${result.violations.join(", ")}`
+        );
+      }
+
+      const fetched = result.value;
+      for (const item of fetched) {
+        assertSameGVK(condition, item);
+      }
+
+      const typed = fetched as Array<T>;
+      await condition.test.call(typed, typed);
+      return typed;
+    },
+} satisfies QueryDef<ResourceListTest, Array<K8sResource>>;
+
+function isSameGVK<T extends K8sResource>(
+  finding: Pick<ResourceListTest<T>, "apiVersion" | "kind">,
+  fetched: K8sResource
+): fetched is T {
+  return (
+    finding.apiVersion === fetched.apiVersion && finding.kind === fetched.kind
+  );
+}
+
+function assertSameGVK<T extends K8sResource>(
+  finding: Pick<ResourceListTest<T>, "apiVersion" | "kind">,
+  fetched: K8sResource
+): void {
+  if (!isSameGVK(finding, fetched)) {
+    throw new Error(
+      `Fetched Kubernetes resource: ${YAML.stringify(fetched)} is not expected: ${YAML.stringify(finding)}`
+    );
+  }
+}
+
+function toKubectlType<T extends K8sResource>(
+  condition: Pick<ResourceListTest<T>, "apiVersion" | "kind">
+): string {
+  const { kind, apiVersion } = condition;
+  const [group, version] = apiVersion.split("/");
+  if (version === undefined) {
+    // core group cannot include version in the type
+    return kind;
+  }
+  return [kind, version, group].filter(Boolean).join(".");
+}

package/ts/actions/assert.ts

@@ -0,0 +1,34 @@
+import type { K8sResource, ResourceTest } from "../apis";
+import { parseK8sResourceYaml } from "../k8s-resource";
+import type { Deps, QueryDef } from "./types";
+
+export const assert = {
+  type: "query",
+  name: "Assert",
+  query:
+    ({ kubectl }: Deps) =>
+    async <T extends K8sResource>(condition: ResourceTest<T>): Promise<T> => {
+      const yaml = await kubectl.get(toKubectlType(condition), condition.name);
+      const result = parseK8sResourceYaml(yaml);
+      if (!result.ok) {
+        throw new Error(
+          `Invalid Kubernetes resource: ${result.violations.join(", ")}`
+        );
+      }
+      const fetched = result.value as T;
+      await condition.test.call(fetched, fetched);
+      return fetched;
+    },
+} satisfies QueryDef<ResourceTest, K8sResource>;
+
+function toKubectlType<T extends K8sResource>(
+  condition: ResourceTest<T>
+): string {
+  const { kind, apiVersion } = condition;
+  const [group, version] = apiVersion.split("/");
+  if (version === undefined) {
+    // core group cannot include version in the type
+    return kind;
+  }
+  return [kind, version, group].filter(Boolean).join(".");
+}

package/ts/actions/exec.ts

@@ -0,0 +1,21 @@
+import { $ as bunShell } from "bun";
+import type { ExecContext, ExecInput } from "../apis";
+import type { MutateDef } from "./types";
+
+const noopRevert = (): Promise<void> => Promise.resolve();
+
+/** Executes arbitrary processing and registers optional revert. */
+export const exec = {
+  type: "mutate",
+  name: "Exec",
+  mutate: () => async (input) => {
+    const context: ExecContext = { $: bunShell };
+    const output = await input.do(context);
+    const revert = input.revert;
+    return {
+      output,
+      revert: revert ? () => revert(context) : noopRevert,
+    };
+  },
+  // biome-ignore lint/suspicious/noExplicitAny: 本当はunknownにしたいが、createMutateFnとの噛み合せが難しいためanyにしている
+} satisfies MutateDef<ExecInput<any>, unknown>;

package/ts/actions/get.ts

@@ -0,0 +1,40 @@
+import { YAML } from "bun";
+import type { K8sResource, K8sResourceReference } from "../apis";
+import { assert } from "./assert";
+import type { QueryDef } from "./types";
+
+export const get = {
+  type: "query",
+  name: "Get",
+  query:
+    ({ kubectl }) =>
+    async <T extends K8sResource>(
+      finding: K8sResourceReference<T>
+    ): Promise<T> =>
+      assert.query({ kubectl })({
+        ...finding,
+        test: (fetched) => assertSameGVK<T>(finding, fetched),
+      }),
+} satisfies QueryDef<K8sResourceReference, K8sResource>;
+
+function isSameGVK<T extends K8sResource>(
+  finding: K8sResourceReference<T>,
+  fetched: K8sResource
+): fetched is T {
+  return (
+    finding.apiVersion === fetched.apiVersion &&
+    finding.kind === fetched.kind &&
+    finding.name === fetched.metadata.name
+  );
+}
+
+function assertSameGVK<T extends K8sResource>(
+  finding: K8sResourceReference<T>,
+  fetched: K8sResource
+): void {
+  if (!isSameGVK<T>(finding, fetched)) {
+    throw new Error(
+      `Fetched Kubernetes resource: ${YAML.stringify(fetched)} is not expected: ${YAML.stringify(finding)}`
+    );
+  }
+}