@appthrust/kest 0.11.0 → 0.13.0

package/README.md

@@ -1168,12 +1168,45 @@ await ns.assert<MyCustomResource>({
 });
 ```
 
+## Tips
+
+### Debugging failed tests
+
+By default, Kest cleans up all resources after every test -- even when the test fails. This keeps the cluster tidy but destroys the state you need for debugging. To preserve resources on failure, set `KEST_PRESERVE_ON_FAILURE=1`:
+
+```sh
+KEST_PRESERVE_ON_FAILURE=1 bun test
+```
+
+When active, Kest skips cleanup for failed scenarios so you can inspect the cluster with `kubectl`. The test report will show a "Cleanup (skipped)" notice instead of the usual cleanup table. Remember to delete the leftover resources manually once you're done investigating.
+
+### Biome configuration
+
+If you use [Biome](https://biomejs.dev/) for linting, the `noDoneCallback` rule may flag kest's `test` callback parameter as a false positive. The parameter is a `Scenario` object, not a done callback.
+
+To suppress this, extend kest's shareable Biome config in your `biome.json`:
+
+```json
+{
+  "extends": ["@appthrust/kest/biome/recommended.json"]
+}
+```
+
+This disables `lint/style/noDoneCallback` while leaving all other rules untouched. If you already extend another config, add kest's config after it:
+
+```json
+{
+  "extends": ["@suin/biome.json", "@appthrust/kest/biome/recommended.json"]
+}
+```
+
 ## Environment Variables
 
-| Variable           | Description                                                             |
-| ------------------ | ----------------------------------------------------------------------- |
-| `KEST_SHOW_REPORT` | Set to `"1"` to show Markdown reports for all tests (not just failures) |
-| `KEST_SHOW_EVENTS` | Set to `"1"` to dump raw recorder events for debugging                  |
+| Variable                    | Description                                                             |
+| --------------------------- | ----------------------------------------------------------------------- |
+| `KEST_SHOW_REPORT`          | Set to `"1"` to show Markdown reports for all tests (not just failures) |
+| `KEST_SHOW_EVENTS`          | Set to `"1"` to dump raw recorder events for debugging                  |
+| `KEST_PRESERVE_ON_FAILURE`  | Set to `"1"` to skip cleanup when a test fails, preserving cluster state for debugging |
 
 ## License
 

package/biome/recommended.json

@@ -0,0 +1,10 @@
+{
+  "$schema": "https://biomejs.dev/schemas/2.3.13/schema.json",
+  "linter": {
+    "rules": {
+      "style": {
+        "noDoneCallback": "off"
+      }
+    }
+  }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@appthrust/kest",
-  "version": "0.11.0",
+  "version": "0.13.0",
   "description": "Kubernetes E2E testing framework designed for humans and AI alike",
   "type": "module",
   "module": "ts/index.ts",
@@ -8,11 +8,13 @@
     ".": {
       "types": "./ts/index.ts",
       "default": "./ts/index.ts"
-    }
+    },
+    "./biome/recommended.json": "./biome/recommended.json"
   },
   "files": [
     "ts/**/*.ts",
     "!ts/**/*.test.ts",
+    "biome/",
     "example/",
     "LICENSE",
     "README.md"

package/ts/recording/index.ts

@@ -71,7 +71,8 @@ type RetryEvent =
 
 type RevertingsEvent =
   | BaseEvent<"RevertingsStart">
-  | BaseEvent<"RevertingsEnd">;
+  | BaseEvent<"RevertingsEnd">
+  | BaseEvent<"RevertingsSkipped">;
 
 type BDDEvent =
   | BaseEvent<"BDDGiven", { readonly description: string }>

package/ts/reporter/markdown/model.ts

@@ -7,6 +7,7 @@ export interface Scenario {
   overview: Array<OverviewItem>;
   details: Array<Tagged<"BDDSection", BDDSection> | Tagged<"Action", Action>>;
   cleanup: Array<CleanupItem>;
+  cleanupSkipped?: boolean;
 }
 
 type Tagged<Tag extends string, Target extends object> = Target & {

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

@@ -75,6 +75,11 @@ function handleNonBDDEvent(state: ParseState, event: Event): void {
       state.inCleanup = false;
       clearCurrentActionState(state);
       return;
+    case "RevertingsSkipped": {
+      const scenario = ensureScenario(state.currentScenario, state.report);
+      scenario.cleanupSkipped = true;
+      return;
+    }
     case "ActionStart":
       handleActionStart(state, event);
       return;

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

@@ -157,7 +157,8 @@ export async function renderReport(
     const isEmpty =
       scenario.overview.length === 0 &&
       scenario.details.length === 0 &&
-      scenario.cleanup.length === 0;
+      scenario.cleanup.length === 0 &&
+      !scenario.cleanupSkipped;
     if (isEmpty) {
       continue;
     }
@@ -294,7 +295,19 @@ export async function renderReport(
     }
 
     // Cleanup
-    if (scenario.cleanup.length > 0) {
+    if (scenario.cleanupSkipped) {
+      lines.push("### Cleanup (skipped)");
+      lines.push("");
+      lines.push(
+        "Cleanup was skipped because `KEST_PRESERVE_ON_FAILURE=1` is set."
+      );
+      lines.push(
+        "Resources created during this scenario were **not** deleted."
+      );
+      lines.push(
+        "To clean up manually, run the revert commands from a passing test run."
+      );
+    } else if (scenario.cleanup.length > 0) {
       lines.push("### Cleanup");
       lines.push("");
       lines.push("| # | Action | Status |");

package/ts/reverting/index.ts

@@ -26,6 +26,9 @@ export function createReverting(deps: Deps) {
         recorder.record("RevertingsEnd", {});
       }
     },
+    skip(): void {
+      recorder.record("RevertingsSkipped", {});
+    },
   };
 }
 

package/ts/scenario/index.ts

@@ -32,7 +32,7 @@ import { retryUntil } from "../retry";
 import type { Reverting } from "../reverting";
 
 export interface InternalScenario extends Scenario {
-  cleanup(): Promise<void>;
+  cleanup(options?: { skip?: boolean }): Promise<void>;
   getReport(): Promise<string>;
 }
 
@@ -61,8 +61,12 @@ export function createScenario(deps: CreateScenarioOptions): InternalScenario {
     generateName: (prefix: string) => generateRandomName(prefix),
     newNamespace: createNewNamespaceFn(deps),
     useCluster: createUseClusterFn(deps),
-    async cleanup() {
-      await reverting.revert();
+    async cleanup(options?: { skip?: boolean }) {
+      if (options?.skip) {
+        reverting.skip();
+      } else {
+        await reverting.revert();
+      }
     },
     async getReport() {
       return await reporter.report(recorder.getEvents());

package/ts/test.ts

@@ -43,6 +43,7 @@ type BunTestRunner = (
 const workspaceRoot = await getWorkspaceRoot();
 const showReport = process.env["KEST_SHOW_REPORT"] === "1";
 const showEvents = process.env["KEST_SHOW_EVENTS"] === "1";
+const preserveOnFailure = process.env["KEST_PRESERVE_ON_FAILURE"] === "1";
 
 function makeScenarioTest(runner: BunTestRunner): TestFunction {
   return (label, fn, options) => {
@@ -66,7 +67,9 @@ function makeScenarioTest(runner: BunTestRunner): TestFunction {
       } catch (error) {
         testErr = error as Error;
       }
-      await scenario.cleanup();
+      await scenario.cleanup({
+        skip: preserveOnFailure && testErr !== undefined,
+      });
       recorder.record("ScenarioEnd", {});
       await report(recorder, scenario, testErr);
       if (testErr) {