@appthrust/kest 0.1.0

package/ts/retry.ts

@@ -0,0 +1,112 @@
+import { Duration, parseDuration } from "./duration";
+import type { Recorder } from "./recording";
+
+export interface RetryOptions {
+  /**
+   * Timeout duration (e.g. "5s", "200ms").
+   *
+   * @default "5s"
+   */
+  timeout?: undefined | string | Duration;
+  /**
+   * Polling interval duration (e.g. "200ms").
+   *
+   * @default "200ms"
+   */
+  interval?: undefined | string | Duration;
+
+  /**
+   * Optional recorder for retry events.
+   */
+  recorder?: undefined | Recorder;
+}
+
+function toDuration(
+  value: undefined | string | Duration,
+  fallback: Duration
+): Duration {
+  if (value === undefined) {
+    return fallback;
+  }
+  if (value instanceof Duration) {
+    return value;
+  }
+  return parseDuration(value);
+}
+
+/**
+ * Retries `fn` until it resolves, or times out.
+ *
+ * Useful for eventually-consistent systems (e.g. Kubernetes).
+ */
+export async function retryUntil<T>(
+  fn: () => Promise<T>,
+  options?: undefined | RetryOptions
+): Promise<T> {
+  const timeout = toDuration(options?.timeout, new Duration(5000));
+  const interval = toDuration(options?.interval, new Duration(200));
+
+  const timeoutMs = timeout.toMilliseconds();
+  const intervalMs = interval.toMilliseconds();
+
+  const startedAtMs = Date.now();
+  const deadline = startedAtMs + timeoutMs;
+
+  let lastError: unknown;
+  // The first call is not a "retry". Retry events start from the second call.
+  try {
+    return await fn();
+  } catch (err) {
+    lastError = err;
+  }
+
+  let retries = 0;
+  const { recorder } = options ?? {};
+  recorder?.record("RetryStart", {});
+
+  while (Date.now() < deadline) {
+    const nowMs = Date.now();
+    const remainingMs = Math.max(0, deadline - nowMs);
+    const sleepMs = Math.min(intervalMs, Math.max(0, remainingMs));
+    if (sleepMs > 0) {
+      await Bun.sleep(sleepMs);
+    }
+
+    if (Date.now() >= deadline) {
+      break;
+    }
+
+    retries += 1;
+    recorder?.record("RetryAttempt", { attempt: retries });
+
+    try {
+      const value = await fn();
+      recorder?.record("RetryEnd", {
+        attempts: retries,
+        success: true,
+        reason: "success",
+      });
+      return value;
+    } catch (err) {
+      lastError = err;
+      const error = err as Error;
+      recorder?.record("RetryFailure", {
+        attempt: retries,
+        error: { name: error.name, message: error.message },
+      });
+    }
+  }
+
+  lastError = lastError ?? new Error(`Timed out after ${timeout.toString()}`);
+
+  if (retries > 0) {
+    recorder?.record("RetryEnd", {
+      attempts: retries,
+      error: lastError as Error,
+      success: false,
+      reason: "timeout",
+    });
+  }
+
+  throw lastError;
+}

package/ts/reverting/index.ts

@@ -0,0 +1,36 @@
+import type { Revert } from "../actions/types";
+import type { Recorder } from "../recording";
+
+export function createReverting(deps: Deps) {
+  const { recorder } = deps;
+  const revertFns: Array<Revert> = [];
+  return {
+    add(revert: Revert): void {
+      revertFns.push(revert);
+    },
+    async revert(): Promise<void> {
+      recorder.record("RevertingsStart", {});
+      let revertFn: undefined | Revert;
+      try {
+        for (;;) {
+          revertFn = revertFns.pop();
+          if (!revertFn) {
+            break;
+          }
+          await revertFn();
+        }
+      } finally {
+        if (revertFn) {
+          revertFns.push(revertFn);
+        }
+        recorder.record("RevertingsEnd", {});
+      }
+    },
+  };
+}
+
+export type Reverting = ReturnType<typeof createReverting>;
+
+interface Deps {
+  readonly recorder: Recorder;
+}

package/ts/scenario/index.ts

@@ -0,0 +1,220 @@
+import { apply } from "../actions/apply";
+import { applyNamespace } from "../actions/apply-namespace";
+import { applyStatus } from "../actions/apply-status";
+import { assert } from "../actions/assert";
+import { assertList } from "../actions/assert-list";
+import { exec } from "../actions/exec";
+import { get } from "../actions/get";
+import type { MutateDef, OneWayMutateDef, QueryDef } from "../actions/types";
+import type {
+  ActionOptions,
+  Cluster,
+  ClusterReference,
+  Namespace,
+  Scenario,
+} from "../apis";
+import bdd from "../bdd";
+import type { Kubectl } from "../kubectl";
+import type { Recorder } from "../recording";
+import type { Reporter } from "../reporter/interface";
+import { retryUntil } from "../retry";
+import type { Reverting } from "../reverting";
+
+export interface InternalScenario extends Scenario {
+  cleanup(): Promise<void>;
+  getReport(): Promise<string>;
+}
+
+export function createScenario(deps: CreateScenarioOptions): InternalScenario {
+  const { recorder, reporter, reverting } = deps;
+  recorder.record("ScenarioStarted", { name: deps.name });
+  return {
+    apply: createMutateFn(deps, apply),
+    applyStatus: createOneWayMutateFn(deps, applyStatus),
+    exec: createMutateFn(deps, exec),
+    get: createQueryFn(deps, get),
+    assert: createQueryFn(deps, assert),
+    assertList: createQueryFn(deps, assertList),
+    given: bdd.given(deps),
+    when: bdd.when(deps),
+    // biome-ignore lint/suspicious/noThenProperty: BDD DSL uses `then()` method name
+    then: bdd.then(deps),
+    and: bdd.and(deps),
+    but: bdd.but(deps),
+    newNamespace: createNewNamespaceFn(deps),
+    useCluster: createUseClusterFn(deps),
+    async cleanup() {
+      await reverting.revert();
+    },
+    async getReport() {
+      return await reporter.report(recorder.getEvents());
+    },
+  };
+}
+
+interface CreateScenarioOptions {
+  readonly name: string;
+  readonly recorder: Recorder;
+  readonly kubectl: Kubectl;
+  readonly reverting: Reverting;
+  readonly reporter: Reporter;
+}
+
+const createMutateFn =
+  <
+    const Action extends MutateDef<Input, Output>,
+    Input = Action extends MutateDef<infer I, infer _> ? I : never,
+    Output = Action extends MutateDef<infer _, infer O> ? O : never,
+  >(
+    deps: CreateScenarioOptions,
+    action: Action
+  ) =>
+  async (
+    input: Input,
+    options?: undefined | ActionOptions
+  ): Promise<Output> => {
+    const { recorder, kubectl, reverting } = deps;
+    const { type, name, mutate } = action;
+    recorder.record("ActionStart", { action: name, phase: type });
+    const fn = mutate({ kubectl });
+    let mutateErr: unknown;
+    try {
+      const { revert, output } = await retryUntil(() => fn(input), {
+        ...options,
+        recorder,
+      });
+      reverting.add(async () => {
+        recorder.record("ActionStart", { action: name, phase: "revert" });
+        let revertErr: unknown;
+        try {
+          await revert();
+        } catch (err) {
+          revertErr = err;
+          throw err;
+        } finally {
+          recorder.record("ActionEnd", {
+            action: name,
+            phase: "revert",
+            ok: revertErr === undefined,
+            error: revertErr as Error,
+          });
+        }
+      });
+      return output;
+    } catch (error) {
+      mutateErr = error;
+      throw error;
+    } finally {
+      recorder.record("ActionEnd", {
+        action: name,
+        phase: type,
+        ok: mutateErr === undefined,
+        error: mutateErr as Error,
+      });
+    }
+  };
+
+const createOneWayMutateFn =
+  <
+    const Action extends OneWayMutateDef<Input, Output>,
+    Input = Action extends OneWayMutateDef<infer I, infer _> ? I : never,
+    Output = Action extends OneWayMutateDef<infer _, infer O> ? O : never,
+  >(
+    deps: CreateScenarioOptions,
+    action: Action
+  ) =>
+  async (
+    input: Input,
+    options?: undefined | ActionOptions
+  ): Promise<Output> => {
+    const { recorder, kubectl } = deps;
+    const { name, mutate } = action;
+    recorder.record("ActionStart", { action: name, phase: "mutate" });
+    const fn = mutate({ kubectl });
+    let mutateErr: unknown;
+    try {
+      return await retryUntil(() => fn(input), { ...options, recorder });
+    } catch (error) {
+      mutateErr = error;
+      throw error;
+    } finally {
+      recorder.record("ActionEnd", {
+        action: name,
+        phase: "mutate",
+        ok: mutateErr === undefined,
+        error: mutateErr as Error,
+      });
+    }
+  };
+
+const createQueryFn =
+  <
+    const Action extends QueryDef<Input, Output>,
+    Input = Action extends QueryDef<infer I, infer _> ? I : never,
+    Output = Action extends QueryDef<infer _, infer O> ? O : never,
+  >(
+    deps: CreateScenarioOptions,
+    action: Action
+  ) =>
+  async (
+    input: Input,
+    options?: undefined | ActionOptions
+  ): Promise<Output> => {
+    const { recorder, kubectl } = deps;
+    const { type, name, query } = action;
+    recorder.record("ActionStart", { action: name, phase: type });
+    const fn = query({ kubectl });
+    try {
+      return await retryUntil(() => fn(input), { ...options, recorder });
+    } catch (error) {
+      recorder.record("ActionEnd", {
+        action: name,
+        phase: type,
+        ok: false,
+        error: error as Error,
+      });
+      throw error;
+    }
+  };
+
+const createNewNamespaceFn =
+  (scenarioDeps: CreateScenarioOptions) =>
+  async (
+    name?: undefined | string,
+    options?: undefined | ActionOptions
+  ): Promise<Namespace> => {
+    const namespaceName = await createMutateFn(scenarioDeps, applyNamespace)(
+      name,
+      options
+    );
+    const { kubectl } = scenarioDeps;
+    const namespacedKubectl = kubectl.extends({ namespace: namespaceName });
+    const namespacedDeps = { ...scenarioDeps, kubectl: namespacedKubectl };
+    return {
+      apply: createMutateFn(namespacedDeps, apply),
+      applyStatus: createOneWayMutateFn(namespacedDeps, applyStatus),
+      get: createQueryFn(namespacedDeps, get),
+      assert: createQueryFn(namespacedDeps, assert),
+      assertList: createQueryFn(namespacedDeps, assertList),
+    };
+  };
+
+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),
+      applyStatus: createOneWayMutateFn(clusterDeps, applyStatus),
+      get: createQueryFn(clusterDeps, get),
+      assert: createQueryFn(clusterDeps, assert),
+      assertList: createQueryFn(clusterDeps, assertList),
+      newNamespace: createNewNamespaceFn(clusterDeps),
+    };
+  };

package/ts/test.ts

@@ -0,0 +1,127 @@
+import {
+  type TestOptions as BunTestOptions,
+  test as bunTest,
+  setDefaultTimeout,
+} from "bun:test";
+import { YAML } from "bun";
+import type { Scenario } from "./apis";
+import { parseDuration } from "./duration";
+import { createKubectl } from "./kubectl";
+import { Recorder } from "./recording";
+import { newMarkdownReporter } from "./reporter/markdown";
+import { createReverting } from "./reverting";
+import { createScenario, type InternalScenario } from "./scenario";
+import { getWorkspaceRoot } from "./workspace";
+
+interface TestOptions {
+  timeout?: string;
+}
+
+const defaultTimeout = 60_000;
+setDefaultTimeout(defaultTimeout);
+
+type Callback = (scenario: Scenario) => Promise<unknown>;
+
+type TestFunction = (
+  label: string,
+  fn: Callback,
+  options?: TestOptions
+) => void;
+
+type Test = TestFunction & {
+  only: TestFunction;
+  skip: TestFunction;
+  todo: TestFunction;
+};
+
+type BunTestRunner = (
+  label: string,
+  fn: () => Promise<unknown> | undefined,
+  options?: number | BunTestOptions
+) => unknown;
+
+const workspaceRoot = await getWorkspaceRoot();
+const showReport = process.env["KEST_SHOW_REPORT"] === "1";
+const showEvents = process.env["KEST_SHOW_EVENTS"] === "1";
+
+function makeScenarioTest(runner: BunTestRunner): TestFunction {
+  return (label, fn, options) => {
+    const bunTestOptions = convertTestOptions(options);
+    const testFn = async () => {
+      const recorder = new Recorder();
+      const kubectl = createKubectl({ recorder, cwd: workspaceRoot });
+      const reverting = createReverting({ recorder });
+      const reporter = newMarkdownReporter({ enableANSI: true });
+      const scenario = createScenario({
+        name: label,
+        recorder,
+        kubectl,
+        reverting,
+        reporter,
+      });
+
+      let testErr: undefined | Error;
+      try {
+        await fn(scenario);
+      } catch (error) {
+        testErr = error as Error;
+      }
+      await scenario.cleanup();
+      await report(recorder, scenario, testErr);
+      if (testErr) {
+        throw testErr;
+      }
+    };
+    const report = async (
+      recorder: Recorder,
+      scenario: InternalScenario,
+      testErr: undefined | Error
+    ) => {
+      const report: undefined | string =
+        testErr || showReport ? await scenario.getReport() : undefined;
+      if (report) {
+        console.log(report);
+      }
+      if (showEvents) {
+        console.log("---- debug events ----");
+        console.log(YAML.stringify(recorder.getEvents(), null, 2));
+      }
+    };
+    return runner(label, testFn, bunTestOptions);
+  };
+}
+
+function convertTestOptions(
+  options?: undefined | TestOptions
+): undefined | BunTestOptions {
+  const timeout = options?.timeout
+    ? parseDuration(options.timeout).toMilliseconds()
+    : defaultTimeout;
+  return {
+    ...options,
+    timeout,
+  };
+}
+
+const test: TestFunction = makeScenarioTest(bunTest);
+Object.defineProperties(test, {
+  // `only` must be a getter (not a value) because Bun throws an error when
+  // accessing `bunTest.only` in CI environments (CI=true). Using a getter
+  // defers the access until `test.only` is actually used, allowing the error
+  // to surface at the appropriate time rather than at module initialization.
+  only: {
+    get() {
+      return makeScenarioTest(bunTest.only);
+    },
+  },
+  skip: {
+    value: makeScenarioTest(bunTest.skip),
+  },
+  todo: {
+    value: makeScenarioTest(bunTest.todo),
+  },
+});
+
+const test_ = test as Test;
+
+export { test_ as it, test_ as test };

package/ts/workspace/find-up.ts

@@ -0,0 +1,20 @@
+import { dirname, join } from "node:path";
+
+/**
+ * Finds a file by walking up parent directories.
+ * Returns the path to the file if found, or undefined if not found.
+ */
+export async function findUp(filename: string): Promise<string | undefined> {
+  let dir = process.cwd();
+  while (true) {
+    const filePath = join(dir, filename);
+    if (await Bun.file(filePath).exists()) {
+      return filePath;
+    }
+    const parent = dirname(dir);
+    if (parent === dir) {
+      return undefined;
+    }
+    dir = parent;
+  }
+}

package/ts/workspace/index.ts

@@ -0,0 +1,25 @@
+import { dirname } from "node:path";
+import { findUp } from "./find-up.ts";
+
+const CONFIG_FILE = "kest.config.ts";
+const PACKAGE_JSON = "package.json";
+
+/**
+ * Gets the workspace root directory.
+ *
+ * Uses find-up approach to locate `kest.config.ts`.
+ * If found, the directory containing the config file is the workspace root.
+ * If not found, tries to find `package.json` instead.
+ * If neither found, the current directory is used as the workspace root.
+ */
+export async function getWorkspaceRoot(): Promise<string> {
+  const configPath = await findUp(CONFIG_FILE);
+  if (configPath) {
+    return dirname(configPath);
+  }
+  const packageJsonPath = await findUp(PACKAGE_JSON);
+  if (packageJsonPath) {
+    return dirname(packageJsonPath);
+  }
+  return process.cwd();
+}

package/ts/yaml/index.ts

@@ -0,0 +1,14 @@
+import { YAML } from "bun";
+
+export function parseYaml(yaml: string): unknown {
+  // Check if the YAML contains stream separators (---)
+  // This includes multiple documents or single document with explicit start
+  if (/^---\s*$/m.test(yaml)) {
+    throw new Error("YAML stream is not supported");
+  }
+  return YAML.parse(yaml);
+}
+
+export function stringifyYaml(value: unknown): string {
+  return YAML.stringify(value, null, 2);
+}