@appthrust/kest 0.1.1 → 0.2.0

package/README.md

@@ -1,10 +1,12 @@
 # Kest
 
+![Kest – Kubernetes E2E testing designed for humans and AI alike](social-preview.svg)
+
 > **Preview Release** -- Kest is currently in `0.x` preview. The API may change based on feedback. Breaking changes can occur in any `0.x` release. A stable `1.0.0` will be released once the API solidifies. Feel free to [open an issue](https://github.com/appthrust/kest/issues/new) if you have any feedback.
 
-**TypeScript-first E2E testing framework for Kubernetes**
+**Kubernetes E2E testing designed for humans and AI alike**
 
-Kest makes it easy to write reliable end-to-end tests for Kubernetes controllers, operators, and admission webhooks. You write test scenarios in TypeScript with full type safety, autocompletion, and the familiar `expect()` API.
+Kest makes it easy to write reliable end-to-end tests for Kubernetes controllers, operators, and admission webhooks. You write test scenarios in TypeScript with full type safety, autocompletion, and the familiar `expect()` API. When a test fails, Kest generates structured Markdown reports that are easy for humans to scan and for AI assistants to parse -- making troubleshooting straightforward regardless of who (or what) is debugging.
 
 ```ts
 import { expect } from "bun:test";
@@ -335,6 +337,7 @@ The top-level API surface available in every test callback.
 | ----------------------------------------------------------------------- | ------------------------------------------------ |
 | `apply(manifest, options?)`                                             | Apply a Kubernetes manifest and register cleanup |
 | `applyStatus(manifest, options?)`                                       | Apply a status subresource (server-side apply)   |
+| `delete(resource, options?)`                                            | Delete a resource by API version, kind, and name |
 | `get(resource, options?)`                                               | Fetch a resource by API version, kind, and name  |
 | `assert(resource, options?)`                                            | Fetch a resource and run assertions with retries |
 | `assertList(resource, options?)`                                        | Fetch a list of resources and run assertions     |
@@ -345,7 +348,7 @@ The top-level API surface available in every test callback.
 
 ### Namespace / Cluster
 
-Returned by `newNamespace()` and `useCluster()` respectively. They expose the same core methods (`apply`, `applyStatus`, `get`, `assert`, `assertList`, `newNamespace`) scoped to their namespace or cluster context.
+Returned by `newNamespace()` and `useCluster()` respectively. They expose the same core methods (`apply`, `applyStatus`, `delete`, `get`, `assert`, `assertList`) scoped to their namespace or cluster context. `Cluster` additionally supports `newNamespace`.
 
 ### Action Options
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@appthrust/kest",
-  "version": "0.1.1",
-  "description": "TypeScript-first E2E testing framework for Kubernetes controllers, operators, and webhooks",
+  "version": "0.2.0",
+  "description": "Kubernetes E2E testing framework designed for humans and AI alike",
   "type": "module",
   "module": "ts/index.ts",
   "exports": {

package/ts/actions/delete.ts

@@ -0,0 +1,25 @@
+import type { K8sResource, K8sResourceReference } from "../apis";
+import type { OneWayMutateDef } from "./types";
+
+export const deleteResource = {
+  type: "oneWayMutate",
+  name: "Delete",
+  mutate:
+    ({ kubectl }) =>
+    async <T extends K8sResource>(resource: K8sResourceReference<T>) => {
+      await kubectl.delete(toKubectlType(resource), resource.name);
+      return undefined;
+    },
+} satisfies OneWayMutateDef<K8sResourceReference, void>;
+
+function toKubectlType<T extends K8sResource>(
+  resource: K8sResourceReference<T>
+): string {
+  const { kind, apiVersion } = resource;
+  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/apis/index.ts

@@ -13,7 +13,8 @@ import type { $ as BunDollar } from "bun";
  * Some actions also register cleanup ("revert") handlers which run during
  * scenario cleanup. For example, {@link Scenario.apply} registers a revert that
  * deletes the applied resource. One-way mutations such as
- * {@link Scenario.applyStatus} do not register a revert.
+ * {@link Scenario.applyStatus} and {@link Scenario.delete} do not register a
+ * revert.
  */
 
 /**
@@ -88,6 +89,31 @@ export interface Scenario {
     options?: undefined | ActionOptions
   ): Promise<void>;
 
+  /**
+   * Deletes a Kubernetes resource using `kubectl delete`.
+   *
+   * This action is retried when it throws.
+   *
+   * Note: this is a one-way mutation and does not register a cleanup handler.
+   *
+   * @template T - The expected Kubernetes resource shape.
+   * @param resource - Group/version/kind and name of the resource to delete.
+   * @param options - Retry options such as timeout and polling interval.
+   *
+   * @example
+   * ```ts
+   * await s.delete({
+   *   apiVersion: "v1",
+   *   kind: "ConfigMap",
+   *   name: "my-config",
+   * });
+   * ```
+   */
+  delete<T extends K8sResource>(
+    resource: K8sResourceReference<T>,
+    options?: undefined | ActionOptions
+  ): Promise<void>;
+
   /**
    * Fetches a Kubernetes resource and returns it as a typed object.
    *
@@ -370,6 +396,22 @@ export interface Cluster {
     options?: undefined | ActionOptions
   ): Promise<void>;
 
+  /**
+   * Deletes a Kubernetes resource in this cluster using `kubectl delete`.
+   *
+   * This action is retried when it throws.
+   *
+   * Note: this is a one-way mutation and does not register a cleanup handler.
+   *
+   * @template T - The expected Kubernetes resource shape.
+   * @param resource - Group/version/kind and name of the resource to delete.
+   * @param options - Retry options such as timeout and polling interval.
+   */
+  delete<T extends K8sResource>(
+    resource: K8sResourceReference<T>,
+    options?: undefined | ActionOptions
+  ): Promise<void>;
+
   /**
    * Fetches a Kubernetes resource by GVK and name.
    *
@@ -534,6 +576,22 @@ export interface Namespace {
     options?: undefined | ActionOptions
   ): Promise<void>;
 
+  /**
+   * Deletes a Kubernetes resource in this namespace using `kubectl delete`.
+   *
+   * This action is retried when it throws.
+   *
+   * Note: this is a one-way mutation and does not register a cleanup handler.
+   *
+   * @template T - The expected Kubernetes resource shape.
+   * @param resource - Group/version/kind and name of the resource to delete.
+   * @param options - Retry options such as timeout and polling interval.
+   */
+  delete<T extends K8sResource>(
+    resource: K8sResourceReference<T>,
+    options?: undefined | ActionOptions
+  ): Promise<void>;
+
   /**
    * Fetches a namespaced Kubernetes resource by GVK and name.
    *

package/ts/scenario/index.ts

@@ -3,6 +3,7 @@ import { applyNamespace } from "../actions/apply-namespace";
 import { applyStatus } from "../actions/apply-status";
 import { assert } from "../actions/assert";
 import { assertList } from "../actions/assert-list";
+import { deleteResource } from "../actions/delete";
 import { exec } from "../actions/exec";
 import { get } from "../actions/get";
 import type { MutateDef, OneWayMutateDef, QueryDef } from "../actions/types";
@@ -31,6 +32,7 @@ export function createScenario(deps: CreateScenarioOptions): InternalScenario {
   return {
     apply: createMutateFn(deps, apply),
     applyStatus: createOneWayMutateFn(deps, applyStatus),
+    delete: createOneWayMutateFn(deps, deleteResource),
     exec: createMutateFn(deps, exec),
     get: createQueryFn(deps, get),
     assert: createQueryFn(deps, assert),
@@ -193,6 +195,7 @@ const createNewNamespaceFn =
     return {
       apply: createMutateFn(namespacedDeps, apply),
       applyStatus: createOneWayMutateFn(namespacedDeps, applyStatus),
+      delete: createOneWayMutateFn(namespacedDeps, deleteResource),
       get: createQueryFn(namespacedDeps, get),
       assert: createQueryFn(namespacedDeps, assert),
       assertList: createQueryFn(namespacedDeps, assertList),
@@ -212,6 +215,7 @@ const createUseClusterFn =
     return {
       apply: createMutateFn(clusterDeps, apply),
       applyStatus: createOneWayMutateFn(clusterDeps, applyStatus),
+      delete: createOneWayMutateFn(clusterDeps, deleteResource),
       get: createQueryFn(clusterDeps, get),
       assert: createQueryFn(clusterDeps, assert),
       assertList: createQueryFn(clusterDeps, assertList),