@appthrust/kest 0.13.0 → 0.14.0

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

@@ -0,0 +1,142 @@
+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]

package/package.json

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

package/ts/recording/index.ts

@@ -87,13 +87,14 @@ interface BaseEvent<
 > {
   readonly kind: Kind;
   readonly data: Data;
+  readonly timestamp: number;
 }
 
 export class Recorder {
   private readonly events: Array<Event> = [];
 
   record<T extends Event>(kind: T["kind"], data: T["data"]) {
-    this.events.push({ kind, data } as T);
+    this.events.push({ kind, data, timestamp: Date.now() } as T);
   }
 
   getEvents(): Array<Event> {

package/ts/reporter/markdown/model.ts

@@ -1,3 +1,5 @@
+import type { Duration } from "../../duration";
+
 export interface Report {
   scenarios: Array<Scenario>;
 }
@@ -8,6 +10,7 @@ export interface Scenario {
   details: Array<Tagged<"BDDSection", BDDSection> | Tagged<"Action", Action>>;
   cleanup: Array<CleanupItem>;
   cleanupSkipped?: boolean;
+  duration?: undefined | Duration;
 }
 
 type Tagged<Tag extends string, Target extends object> = Target & {
@@ -17,6 +20,7 @@ type Tagged<Tag extends string, Target extends object> = Target & {
 export interface OverviewItem {
   name: string;
   status: "pending" | "success" | "failure";
+  duration?: undefined | Duration;
 }
 
 export interface BDDSection {
@@ -30,6 +34,7 @@ export interface Action {
   attempts?: undefined | number;
   commands: Array<Command>;
   error?: undefined | Error;
+  duration?: undefined | Duration;
 }
 
 export interface Command {
@@ -55,6 +60,7 @@ export interface CleanupItem {
   resource?: undefined | string;
   status: "success" | "failure";
   command: CleanupCommand;
+  duration?: undefined | Duration;
 }
 
 export interface CleanupCommand {

package/ts/reporter/markdown/parser/index.ts

@@ -1,3 +1,4 @@
+import { Duration } from "../../../duration";
 import type { Event } from "../../../recording";
 import type {
   Action,
@@ -30,6 +31,8 @@ interface ParseState {
   currentAction: Action | undefined;
   currentOverviewIndex: number | undefined;
   currentCleanup: CleanupItem | undefined;
+  currentActionStartTimestamp: number | undefined;
+  scenarioStartTimestamp: number | undefined;
 }
 
 export function parseEvents(events: ReadonlyArray<Event>): Report {
@@ -41,6 +44,8 @@ export function parseEvents(events: ReadonlyArray<Event>): Report {
     currentAction: undefined,
     currentOverviewIndex: undefined,
     currentCleanup: undefined,
+    currentActionStartTimestamp: undefined,
+    scenarioStartTimestamp: undefined,
   };
 
   for (const event of events) {
@@ -64,9 +69,19 @@ function handleNonBDDEvent(state: ParseState, event: Event): void {
     case "ScenarioStart":
       handleScenarioStart(state, event);
       return;
-    case "ScenarioEnd":
+    case "ScenarioEnd": {
+      if (state.currentScenario) {
+        const duration = computeDuration(
+          state.scenarioStartTimestamp,
+          event.timestamp
+        );
+        if (duration) {
+          state.currentScenario.duration = duration;
+        }
+      }
       clearScenarioProgressState(state);
       return;
+    }
     case "RevertingsStart":
       state.inCleanup = true;
       clearCurrentActionState(state);
@@ -109,6 +124,7 @@ function handleActionStart(
   state: ParseState,
   event: Extract<Event, { kind: "ActionStart" }>
 ): void {
+  state.currentActionStartTimestamp = event.timestamp;
   const scenario = ensureScenario(state.currentScenario, state.report);
   if (state.inCleanup) {
     const cleanup: CleanupItem = {
@@ -156,10 +172,17 @@ function applyRegularActionEnd(
     return;
   }
 
+  const duration = computeDuration(
+    state.currentActionStartTimestamp,
+    event.timestamp
+  );
+  currentAction.duration = duration;
+
   if (state.currentOverviewIndex !== undefined) {
     const overviewItem = currentScenario.overview[state.currentOverviewIndex];
     if (overviewItem) {
       overviewItem.status = event.data.ok ? "success" : "failure";
+      overviewItem.duration = duration;
     }
   }
 
@@ -177,6 +200,7 @@ function applyRegularActionEnd(
 
   state.currentAction = undefined;
   state.currentOverviewIndex = undefined;
+  state.currentActionStartTimestamp = undefined;
 }
 
 function handleCommandResult(
@@ -247,6 +271,7 @@ function handleScenarioStart(
   };
   state.report.scenarios.push(state.currentScenario);
   clearScenarioProgressState(state);
+  state.scenarioStartTimestamp = event.timestamp;
 }
 
 function handleActionEnd(
@@ -270,8 +295,16 @@ function handleCleanupActionEnd(
 
   if (state.currentCleanup) {
     state.currentCleanup.status = event.data.ok ? "success" : "failure";
+    const duration = computeDuration(
+      state.currentActionStartTimestamp,
+      event.timestamp
+    );
+    if (duration) {
+      state.currentCleanup.duration = duration;
+    }
   }
   state.currentCleanup = undefined;
+  state.currentActionStartTimestamp = undefined;
   return true;
 }
 
@@ -344,9 +377,24 @@ function ensureScenario(
   return created;
 }
 
+function computeDuration(
+  start: number | undefined,
+  end: number | undefined
+): Duration | undefined {
+  if (typeof start !== "number" || typeof end !== "number") {
+    return undefined;
+  }
+  const ms = end - start;
+  if (ms < 0 || !Number.isFinite(ms) || !Number.isInteger(ms)) {
+    return undefined;
+  }
+  return new Duration(ms);
+}
+
 function clearScenarioProgressState(state: ParseState): void {
   state.currentBDDSection = undefined;
   state.inCleanup = false;
+  state.scenarioStartTimestamp = undefined;
   clearCurrentActionState(state);
 }
 
@@ -354,6 +402,7 @@ function clearCurrentActionState(state: ParseState): void {
   state.currentAction = undefined;
   state.currentOverviewIndex = undefined;
   state.currentCleanup = undefined;
+  state.currentActionStartTimestamp = undefined;
 }
 
 function bddFromEvent(event: Event): BDDSection | undefined {

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

@@ -1,3 +1,4 @@
+import { Duration } from "../../../duration";
 import { codeToANSIForcedColors } from "../../shiki";
 import type { MarkdownReporterOptions } from "../index";
 import type { Action, Report } from "../model";
@@ -174,14 +175,26 @@ export async function renderReport(
     lines.push("");
 
     // Overview
+    const overviewHasDuration = scenario.overview.some((o) => o.duration);
     lines.push("## Scenario Overview");
     lines.push("");
-    lines.push("| # | Action | Status |");
-    lines.push("|---|--------|--------|");
+    if (overviewHasDuration) {
+      lines.push("| # | Action | Status | Duration |");
+      lines.push("|---|--------|--------|----------|");
+    } else {
+      lines.push("| # | Action | Status |");
+      lines.push("|---|--------|--------|");
+    }
     for (const [i, item] of scenario.overview.entries()) {
-      lines.push(
-        `| ${i + 1} | ${stripAnsi(item.name)} | ${statusEmoji(item.status)} |`
-      );
+      if (overviewHasDuration) {
+        lines.push(
+          `| ${i + 1} | ${stripAnsi(item.name)} | ${statusEmoji(item.status)} | ${item.duration?.toString() ?? ""} |`
+        );
+      } else {
+        lines.push(
+          `| ${i + 1} | ${stripAnsi(item.name)} | ${statusEmoji(item.status)} |`
+        );
+      }
     }
     lines.push("");
 
@@ -308,14 +321,26 @@ export async function renderReport(
         "To clean up manually, run the revert commands from a passing test run."
       );
     } else if (scenario.cleanup.length > 0) {
+      const cleanupHasDuration = scenario.cleanup.some((c) => c.duration);
       lines.push("### Cleanup");
       lines.push("");
-      lines.push("| # | Action | Status |");
-      lines.push("|---|--------|--------|");
+      if (cleanupHasDuration) {
+        lines.push("| # | Action | Status | Duration |");
+        lines.push("|---|--------|--------|----------|");
+      } else {
+        lines.push("| # | Action | Status |");
+        lines.push("|---|--------|--------|");
+      }
       for (const [i, item] of scenario.cleanup.entries()) {
-        lines.push(
-          `| ${i + 1} | ${stripAnsi(item.action)} | ${item.status === "success" ? "✅" : "❌"} |`
-        );
+        if (cleanupHasDuration) {
+          lines.push(
+            `| ${i + 1} | ${stripAnsi(item.action)} | ${item.status === "success" ? "✅" : "❌"} | ${item.duration?.toString() ?? ""} |`
+          );
+        } else {
+          lines.push(
+            `| ${i + 1} | ${stripAnsi(item.action)} | ${item.status === "success" ? "✅" : "❌"} |`
+          );
+        }
       }
       lines.push("");
 
@@ -334,6 +359,33 @@ export async function renderReport(
       lines.push("```");
     }
 
+    // Total duration summary
+    if (scenario.duration) {
+      lines.push("");
+      const actionsDurationMs = scenario.overview.reduce(
+        (sum, o) => sum + (o.duration?.milliseconds ?? 0),
+        0
+      );
+      const cleanupDurationMs = scenario.cleanup.reduce(
+        (sum, c) => sum + (c.duration?.milliseconds ?? 0),
+        0
+      );
+      const parts: Array<string> = [];
+      if (actionsDurationMs > 0) {
+        parts.push(`Actions: ${new Duration(actionsDurationMs).toString()}`);
+      }
+      if (cleanupDurationMs > 0) {
+        parts.push(`Cleanup: ${new Duration(cleanupDurationMs).toString()}`);
+      }
+      if (parts.length > 0) {
+        lines.push(
+          `**Total: ${scenario.duration.toString()}** (${parts.join(", ")})`
+        );
+      } else {
+        lines.push(`**Total: ${scenario.duration.toString()}**`);
+      }
+    }
+
     renderedScenarios.push(lines.join("\n"));
   }
 

package/ts/test.ts

@@ -17,8 +17,7 @@ interface TestOptions {
   timeout?: string;
 }
 
-const defaultTimeout = 60_000;
-setDefaultTimeout(defaultTimeout);
+setDefaultTimeout(60_000);
 
 type Callback = (scenario: Scenario) => Promise<unknown>;
 
@@ -98,12 +97,12 @@ function makeScenarioTest(runner: BunTestRunner): TestFunction {
 function convertTestOptions(
   options?: undefined | TestOptions
 ): undefined | BunTestOptions {
-  const timeout = options?.timeout
-    ? parseDuration(options.timeout).toMilliseconds()
-    : defaultTimeout;
+  if (!options?.timeout) {
+    return undefined;
+  }
   return {
     ...options,
-    timeout,
+    timeout: parseDuration(options.timeout).toMilliseconds(),
   };
 }