@appthrust/kest 0.2.0 → 0.3.1

package/ts/reporter/markdown/renderer/index.ts

@@ -0,0 +1,296 @@
+import { codeToANSIForcedColors } from "../../shiki";
+import type { MarkdownReporterOptions } from "../index";
+import type { Action, Report } from "../model";
+
+const markdownLang = "markdown";
+const markdownTheme = "catppuccin-mocha";
+
+type StdinReplacement = Readonly<{
+  placeholder: string;
+  stdin: string;
+  stdinLanguage: string;
+}>;
+
+function normalizeStdin(stdin: string): string {
+  // Match `ts/reporter/markdown.ts` behavior: keep content stable.
+  return stdin.replace(/^\n/, "").replace(/\s+$/, "");
+}
+
+function applyStdinReplacements(
+  highlightedMarkdown: string,
+  replacements: ReadonlyArray<StdinReplacement>
+): string {
+  if (replacements.length === 0) {
+    return highlightedMarkdown;
+  }
+
+  let current = highlightedMarkdown;
+  for (const r of replacements) {
+    const lines = current.split("\n");
+    const stdinLines = r.stdin.split("\n");
+    const out: Array<string> = [];
+    for (const line of lines) {
+      if (stripAnsi(line).includes(r.placeholder)) {
+        out.push(...stdinLines);
+      } else {
+        out.push(line);
+      }
+    }
+    current = out.join("\n");
+  }
+  return current;
+}
+
+async function highlightMarkdown(
+  markdown: string,
+  stdinReplacements: ReadonlyArray<StdinReplacement>
+): Promise<string> {
+  const stripped = stripAnsi(markdown);
+  try {
+    const highlightedMarkdown = await codeToANSIForcedColors(
+      stripped,
+      markdownLang,
+      markdownTheme
+    );
+
+    if (stdinReplacements.length === 0) {
+      // Keep output shape stable: always end with a single trailing newline.
+      return highlightedMarkdown.replace(/\n+$/, "\n");
+    }
+
+    const highlightedStdinList = await Promise.all(
+      stdinReplacements.map(async (r) => {
+        const highlightedStdin = await codeToANSIForcedColors(
+          r.stdin,
+          r.stdinLanguage,
+          markdownTheme
+        );
+        // Avoid inserting an extra blank line before `EOF`.
+        const trimmed = trimFinalNewline(
+          highlightedStdin.replace(/\n+$/, "\n")
+        );
+        return { ...r, stdin: trimmed } satisfies StdinReplacement;
+      })
+    );
+
+    const replaced = applyStdinReplacements(
+      highlightedMarkdown,
+      highlightedStdinList
+    );
+    return replaced.replace(/\n+$/, "\n");
+  } catch {
+    return stripped;
+  }
+}
+
+function stripAnsi(input: string): string {
+  // Prefer Bun's built-in ANSI stripper when available.
+  if (typeof Bun !== "undefined" && typeof Bun.stripANSI === "function") {
+    return Bun.stripANSI(input);
+  }
+  // biome-ignore lint/suspicious/noControlCharactersInRegex: intended
+  return input.replace(/\u001b\[[0-9;]*m/g, "");
+}
+
+function trimFinalNewline(input: string): string {
+  return input.replace(/\n$/, "");
+}
+
+function toBddHeading(keyword: string): string {
+  if (keyword.length === 0) {
+    return keyword;
+  }
+  return keyword.charAt(0).toUpperCase() + keyword.slice(1);
+}
+
+const statusEmojiByStatus = {
+  pending: "⏳",
+  success: "✅",
+  failure: "❌",
+} as const;
+
+function statusEmoji(status: keyof typeof statusEmojiByStatus): string {
+  return statusEmojiByStatus[status];
+}
+
+// biome-ignore lint/complexity/noExcessiveCognitiveComplexity: rendering is intentionally linear and explicit
+export function renderReport(
+  report: Report,
+  options: MarkdownReporterOptions
+): Promise<string> {
+  const enableANSI = options.enableANSI ?? false;
+
+  const renderedScenarios: Array<string> = [];
+  const stdinReplacements: Array<StdinReplacement> = [];
+  let stdinSeq = 0;
+
+  for (const scenario of report.scenarios) {
+    const isEmpty =
+      scenario.overview.length === 0 &&
+      scenario.details.length === 0 &&
+      scenario.cleanup.length === 0;
+    if (isEmpty) {
+      continue;
+    }
+
+    const overviewStatusByName = new Map<
+      string,
+      "pending" | "success" | "failure"
+    >(scenario.overview.map((o) => [o.name, o.status]));
+
+    const lines: Array<string> = [];
+
+    lines.push(`# ${stripAnsi(scenario.name)}`);
+    lines.push("");
+
+    // Overview
+    lines.push("## Scenario Overview");
+    lines.push("");
+    lines.push("| # | Action | Status |");
+    lines.push("|---|--------|--------|");
+    for (const [i, item] of scenario.overview.entries()) {
+      lines.push(
+        `| ${i + 1} | ${stripAnsi(item.name)} | ${statusEmoji(item.status)} |`
+      );
+    }
+    lines.push("");
+
+    // Details
+    lines.push("## Scenario Details");
+    lines.push("");
+
+    // biome-ignore lint/complexity/noExcessiveCognitiveComplexity: rendering is intentionally linear and explicit
+    const renderAction = (action: Action) => {
+      let status = overviewStatusByName.get(action.name);
+      if (!status) {
+        if (action.error) {
+          status = "failure";
+        } else if (action.command) {
+          status = "success";
+        } else {
+          status = "pending";
+        }
+      }
+      const emoji = statusEmoji(status);
+      const attemptsSuffix =
+        status === "failure" && typeof action.attempts === "number"
+          ? ` (Failed after ${action.attempts} attempts)`
+          : "";
+
+      lines.push(`**${emoji} ${stripAnsi(action.name)}**${attemptsSuffix}`);
+      lines.push("");
+
+      const cmd = action.command;
+      if (cmd) {
+        const base = [cmd.cmd, ...cmd.args].join(" ").trim();
+        const stdin = cmd.stdin?.text;
+        const stdinLanguage = cmd.stdin?.language ?? "text";
+
+        lines.push("```shell");
+        if (typeof stdin === "string") {
+          lines.push(`${base} <<EOF`);
+          if (enableANSI) {
+            const placeholder = `__KEST_STDIN_${stdinSeq++}__`;
+            stdinReplacements.push({
+              placeholder,
+              stdin: normalizeStdin(stripAnsi(stdin)),
+              stdinLanguage,
+            });
+            lines.push(placeholder);
+          } else {
+            lines.push(stripAnsi(stdin));
+          }
+          lines.push("EOF");
+        } else {
+          lines.push(base);
+        }
+        lines.push("```");
+        lines.push("");
+
+        const stdout = stripAnsi(cmd.stdout?.text ?? "");
+        if (stdout.trim().length > 0) {
+          const lang = cmd.stdout?.language ?? "text";
+          lines.push(`\`\`\`${lang} title="stdout"`);
+          lines.push(trimFinalNewline(stdout));
+          lines.push("```");
+          lines.push("");
+        }
+
+        const stderr = stripAnsi(cmd.stderr?.text ?? "");
+        if (stderr.trim().length > 0) {
+          const lang = cmd.stderr?.language ?? "text";
+          lines.push(`\`\`\`${lang} title="stderr"`);
+          lines.push(trimFinalNewline(stderr));
+          lines.push("```");
+          lines.push("");
+        }
+      }
+
+      if (status === "failure" && action.error?.message?.text) {
+        const messageText = stripAnsi(action.error.message.text);
+        const lang = action.error.message.language ?? "text";
+        lines.push("Error:");
+        lines.push("");
+        lines.push(`\`\`\`${lang}`);
+        lines.push(trimFinalNewline(messageText));
+        lines.push("```");
+        lines.push("");
+      }
+    };
+
+    for (const item of scenario.details) {
+      if (item.type === "BDDSection") {
+        lines.push(
+          `### ${toBddHeading(item.keyword)}: ${stripAnsi(item.description)}`
+        );
+        lines.push("");
+        for (const action of item.actions) {
+          renderAction(action);
+        }
+      }
+      if (item.type === "Action") {
+        renderAction(item);
+      }
+    }
+
+    // Cleanup
+    if (scenario.cleanup.length > 0) {
+      lines.push("### Cleanup");
+      lines.push("");
+      lines.push("| # | Action | Status |");
+      lines.push("|---|--------|--------|");
+      for (const [i, item] of scenario.cleanup.entries()) {
+        lines.push(
+          `| ${i + 1} | ${stripAnsi(item.action)} | ${item.status === "success" ? "✅" : "❌"} |`
+        );
+      }
+      lines.push("");
+
+      lines.push("```shellsession");
+      for (const [i, item] of scenario.cleanup.entries()) {
+        if (i > 0) {
+          lines.push("");
+        }
+        const base = [item.command.cmd, ...item.command.args].join(" ").trim();
+        lines.push(`$ ${stripAnsi(base)}`);
+        const output = stripAnsi(item.command.output);
+        if (output.trim().length > 0) {
+          lines.push(trimFinalNewline(output));
+        }
+      }
+      lines.push("```");
+    }
+
+    renderedScenarios.push(lines.join("\n"));
+  }
+
+  if (renderedScenarios.length === 0) {
+    return Promise.resolve("");
+  }
+  const rendered = renderedScenarios.join("\n\n");
+  const markdown = rendered.endsWith("\n") ? rendered : `${rendered}\n`;
+  if (!enableANSI) {
+    return Promise.resolve(markdown);
+  }
+  return highlightMarkdown(markdown, stdinReplacements);
+}

package/ts/reporter/shiki.ts

@@ -0,0 +1,58 @@
+export type CodeToANSI = (
+  code: string,
+  language: string,
+  theme: string
+) => Promise<string>;
+
+let codeToANSIPromise: Promise<CodeToANSI> | undefined;
+
+function loadCodeToANSI(): Promise<CodeToANSI> {
+  if (codeToANSIPromise) {
+    return codeToANSIPromise;
+  }
+
+  codeToANSIPromise = (async () => {
+    const env = typeof process !== "undefined" ? process.env : undefined;
+    const prevNoColor = env?.["NO_COLOR"];
+    const prevForceColor = env?.["FORCE_COLOR"];
+
+    // `@shikijs/cli` uses `ansis`, which disables colors when NO_COLOR is set.
+    // Force ANSI output when our callers explicitly request ANSI.
+    if (env) {
+      // biome-ignore lint/performance/noDelete: required to actually unset env vars
+      delete env["NO_COLOR"];
+      env["FORCE_COLOR"] = "3";
+    }
+
+    try {
+      const mod = await import("@shikijs/cli");
+      return mod.codeToANSI as unknown as CodeToANSI;
+    } finally {
+      if (env) {
+        if (prevNoColor === undefined) {
+          // biome-ignore lint/performance/noDelete: required to restore absence
+          delete env["NO_COLOR"];
+        } else {
+          env["NO_COLOR"] = prevNoColor;
+        }
+        if (prevForceColor === undefined) {
+          // biome-ignore lint/performance/noDelete: required to restore absence
+          delete env["FORCE_COLOR"];
+        } else {
+          env["FORCE_COLOR"] = prevForceColor;
+        }
+      }
+    }
+  })();
+
+  return codeToANSIPromise;
+}
+
+export async function codeToANSIForcedColors(
+  code: string,
+  language: string,
+  theme: string
+): Promise<string> {
+  const fn = await loadCodeToANSI();
+  return await fn(code, language, theme);
+}

package/ts/retry.ts

@@ -77,7 +77,6 @@ export async function retryUntil<T>(
     }
 
     retries += 1;
-    recorder?.record("RetryAttempt", { attempt: retries });
 
     try {
       const value = await fn();
@@ -89,11 +88,6 @@ export async function retryUntil<T>(
       return value;
     } catch (err) {
       lastError = err;
-      const error = err as Error;
-      recorder?.record("RetryFailure", {
-        attempt: retries,
-        error: { name: error.name, message: error.message },
-      });
     }
   }
 

package/ts/scenario/index.ts

@@ -1,11 +1,17 @@
 import { apply } from "../actions/apply";
-import { applyNamespace } from "../actions/apply-namespace";
+import {
+  type ApplyNamespaceInput,
+  applyNamespace,
+} from "../actions/apply-namespace";
 import { applyStatus } from "../actions/apply-status";
 import { assert } from "../actions/assert";
+import { assertAbsence } from "../actions/assert-absence";
 import { assertList } from "../actions/assert-list";
+import { create } from "../actions/create";
 import { deleteResource } from "../actions/delete";
 import { exec } from "../actions/exec";
 import { get } from "../actions/get";
+import { label } from "../actions/label";
 import type { MutateDef, OneWayMutateDef, QueryDef } from "../actions/types";
 import type {
   ActionOptions,
@@ -28,14 +34,16 @@ export interface InternalScenario extends Scenario {
 
 export function createScenario(deps: CreateScenarioOptions): InternalScenario {
   const { recorder, reporter, reverting } = deps;
-  recorder.record("ScenarioStarted", { name: deps.name });
   return {
     apply: createMutateFn(deps, apply),
+    create: createMutateFn(deps, create),
     applyStatus: createOneWayMutateFn(deps, applyStatus),
     delete: createOneWayMutateFn(deps, deleteResource),
+    label: createOneWayMutateFn(deps, label),
     exec: createMutateFn(deps, exec),
     get: createQueryFn(deps, get),
     assert: createQueryFn(deps, assert),
+    assertAbsence: createQueryFn(deps, assertAbsence),
     assertList: createQueryFn(deps, assertList),
     given: bdd.given(deps),
     when: bdd.when(deps),
@@ -76,17 +84,25 @@ const createMutateFn =
     options?: undefined | ActionOptions
   ): Promise<Output> => {
     const { recorder, kubectl, reverting } = deps;
-    const { type, name, mutate } = action;
-    recorder.record("ActionStart", { action: name, phase: type });
+    const { mutate, describe } = action;
+    function recordActionStart() {
+      recorder.record("ActionStart", {
+        description: describe(input),
+      });
+    }
+    function recordActionEnd(error: undefined | Error) {
+      recorder.record("ActionEnd", { ok: error === undefined, error });
+    }
+    recordActionStart();
     const fn = mutate({ kubectl });
-    let mutateErr: unknown;
+    let mutateErr: undefined | Error;
     try {
       const { revert, output } = await retryUntil(() => fn(input), {
         ...options,
         recorder,
       });
       reverting.add(async () => {
-        recorder.record("ActionStart", { action: name, phase: "revert" });
+        recordActionStart(); // to record revert action start
         let revertErr: unknown;
         try {
           await revert();
@@ -94,25 +110,15 @@ const createMutateFn =
           revertErr = err;
           throw err;
         } finally {
-          recorder.record("ActionEnd", {
-            action: name,
-            phase: "revert",
-            ok: revertErr === undefined,
-            error: revertErr as Error,
-          });
+          recordActionEnd(revertErr as Error); // to record revert action end
         }
       });
       return output;
     } catch (error) {
-      mutateErr = error;
+      mutateErr = error as Error;
       throw error;
     } finally {
-      recorder.record("ActionEnd", {
-        action: name,
-        phase: type,
-        ok: mutateErr === undefined,
-        error: mutateErr as Error,
-      });
+      recordActionEnd(mutateErr as Error);
     }
   };
 
@@ -130,8 +136,8 @@ const createOneWayMutateFn =
     options?: undefined | ActionOptions
   ): Promise<Output> => {
     const { recorder, kubectl } = deps;
-    const { name, mutate } = action;
-    recorder.record("ActionStart", { action: name, phase: "mutate" });
+    const { mutate, describe } = action;
+    recorder.record("ActionStart", { description: describe(input) });
     const fn = mutate({ kubectl });
     let mutateErr: unknown;
     try {
@@ -141,8 +147,6 @@ const createOneWayMutateFn =
       throw error;
     } finally {
       recorder.record("ActionEnd", {
-        action: name,
-        phase: "mutate",
         ok: mutateErr === undefined,
         error: mutateErr as Error,
       });
@@ -163,26 +167,27 @@ const createQueryFn =
     options?: undefined | ActionOptions
   ): Promise<Output> => {
     const { recorder, kubectl } = deps;
-    const { type, name, query } = action;
-    recorder.record("ActionStart", { action: name, phase: type });
+    const { query, describe } = action;
+    recorder.record("ActionStart", { description: describe(input) });
     const fn = query({ kubectl });
+    let queryErr: unknown;
     try {
       return await retryUntil(() => fn(input), { ...options, recorder });
     } catch (error) {
+      queryErr = error;
+      throw error;
+    } finally {
       recorder.record("ActionEnd", {
-        action: name,
-        phase: type,
-        ok: false,
-        error: error as Error,
+        ok: queryErr === undefined,
+        error: queryErr as Error,
       });
-      throw error;
     }
   };
 
 const createNewNamespaceFn =
   (scenarioDeps: CreateScenarioOptions) =>
   async (
-    name?: undefined | string,
+    name?: ApplyNamespaceInput,
     options?: undefined | ActionOptions
   ): Promise<Namespace> => {
     const namespaceName = await createMutateFn(scenarioDeps, applyNamespace)(
@@ -193,11 +198,15 @@ const createNewNamespaceFn =
     const namespacedKubectl = kubectl.extends({ namespace: namespaceName });
     const namespacedDeps = { ...scenarioDeps, kubectl: namespacedKubectl };
     return {
+      name: namespaceName,
       apply: createMutateFn(namespacedDeps, apply),
+      create: createMutateFn(namespacedDeps, create),
       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),
     };
   };
@@ -214,10 +223,13 @@ const createUseClusterFn =
     const clusterDeps = { ...scenarioDeps, kubectl: clusterKubectl };
     return {
       apply: createMutateFn(clusterDeps, apply),
+      create: createMutateFn(clusterDeps, create),
       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),
       newNamespace: createNewNamespaceFn(clusterDeps),
     };

package/ts/test.ts

@@ -59,7 +59,7 @@ function makeScenarioTest(runner: BunTestRunner): TestFunction {
         reverting,
         reporter,
       });
-
+      recorder.record("ScenarioStart", { name: label });
       let testErr: undefined | Error;
       try {
         await fn(scenario);
@@ -67,6 +67,7 @@ function makeScenarioTest(runner: BunTestRunner): TestFunction {
         testErr = error as Error;
       }
       await scenario.cleanup();
+      recorder.record("ScenarioEnd", {});
       await report(recorder, scenario, testErr);
       if (testErr) {
         throw testErr;