@specific.dev/spectest 0.31.0 → 0.32.1

package/dist/browser.js

@@ -32,7 +32,7 @@ import { readFileSync } from "node:fs";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
 import { generateId } from "./ids.js";
-import { recordBrowser, reserveEvent, truncateUtf8 } from "./recorder.js";
+import { recordBrowser, reserveBackdated, reserveEvent, truncateUtf8 } from "./recorder.js";
 import { wrap } from "./inspect.js";
 import { describeUrlPattern, matchesUrl } from "./url-match.js";
 import { attachBrowserProbe, DEFAULT_ACTION_TIMEOUT_MS, desktopStrategy, makeLocator, mobileStrategy, } from "./locator.js";
@@ -1407,7 +1407,9 @@ function buildBackend(holder, recorder, buildOpts) {
             // No page work — the matcher already read the value via silentRead. We
             // only mint the timeline anchor: the seq the assertion nests under, plus
             // `sessionTimestamp` (post-settle wall clock) so the dashboard seeks the
-            // replay to the frame the assertion observed.
+            // replay to the frame the assertion observed. The offset is backdated to
+            // where the matcher started polling, since that's what `tOffsetMs` means
+            // everywhere else (the ops that reserve up front stamp their start).
             const endT = Date.now();
             const seq = recordBrowser({
                 action,
@@ -1417,7 +1419,7 @@ function buildBackend(holder, recorder, buildOpts) {
                     : {}),
                 durationMs: waitedMs,
                 ...(error ? { error } : {}),
-            });
+            }, reserveBackdated(waitedMs));
             // Drain the rrweb the page buffered while the matcher waited into this
             // step's chunk, so `settledTarget` has bounds to seek into.
             await drain(action);

package/dist/components/index.d.ts

@@ -1,7 +1,7 @@
 export { postgres, type PostgresOptions, type PostgresHelpers, } from "./postgres.js";
 export { s3, type S3Options, type S3Helpers, } from "./s3.js";
 export { SQL, type SqlClient, type SqlOptions } from "../sql.js";
-export { k3s, type K3sOptions, type K3sHelpers, type K3sClient, } from "./k3s.js";
+export { k3s, type K3sOptions, type K3sHelpers, type K3sClient, type TaggedObjectApi, type KubernetesObjectRef, type ApplyOptions, type RolloutTarget, type WaitOptions, type LogsOptions, type KubernetesObject, type KubernetesListObject, } from "./k3s.js";
 export { expo, type ExpoOptions, type ExpoHelpers, } from "./expo.js";
 export { supabase, type SupabaseOptions, type SupabaseHelpers, type SupabaseStack, } from "./supabase.js";
 export { email, type EmailOptions, type EmailHelpers, type EmailMessage, type EmailSummary, type EmailMatch, type EmailAttachment, } from "./email.js";

package/dist/components/k3s.d.ts

@@ -1,6 +1,7 @@
-import { AppsV1Api, CoreV1Api, KubeConfig, KubernetesObjectApi, type KubernetesObject } from "@kubernetes/client-node";
+import { AppsV1Api, BatchV1Api, CoreV1Api, KubeConfig, PatchStrategy, type KubernetesListObject, type KubernetesObject, type V1DeleteOptions, type V1Job, type V1Status } from "@kubernetes/client-node";
 import type { ServiceHelpersContext } from "../index.js";
 import type { Wrapped } from "../inspect.js";
+export type { KubernetesObject, KubernetesListObject, } from "@kubernetes/client-node";
 export interface K3sOptions {
     /** Image tag for the official `rancher/k3s` image. Default `"v1.30.6-k3s1"`. */
     version?: string;
@@ -109,6 +110,50 @@ export interface K3sOptions {
 type Tagged<T> = {
     [K in keyof T]: T[K] extends (...args: infer A) => Promise<infer R> ? (...args: A) => Promise<Wrapped<R>> : T[K];
 };
+/**
+ * `{ apiVersion, kind, metadata: { name } }` — enough to address an
+ * existing object. Redeclared here because `@kubernetes/client-node`
+ * keeps its equivalent (`KubernetesObjectHeader`) module-private.
+ */
+export type KubernetesObjectRef<T extends KubernetesObject = KubernetesObject> = Pick<T, "apiVersion" | "kind"> & {
+    metadata: {
+        name: string;
+        namespace?: string;
+    };
+};
+/**
+ * The dynamic object API, hand-declared rather than derived through
+ * {@link Tagged}.
+ *
+ * `Tagged<T>` infers each method from its *erased* signature, and a mapped
+ * type can't reintroduce a type parameter (TypeScript has no higher-kinded
+ * types). For `CoreV1Api`/`AppsV1Api` that's invisible — their methods
+ * return concrete types — but `KubernetesObjectApi.read<T>`/`list<T>` are
+ * generic, so mapping them collapsed `read<MyCustomResource>(…)` to
+ * `Promise<Wrapped<KubernetesObject>>`: `Expected 0 type arguments, but got
+ * 1`, then `Property 'spec' does not exist on type 'KubernetesObject'` —
+ * precisely on the custom resources this API exists to reach. Worse, the
+ * degraded value made `expect(...)` resolve to the *locator* overload, so
+ * the reported error was a baffling `Property 'toBe' does not exist on type
+ * 'LocatorAssertion'` three lines further down.
+ *
+ * So the generic methods are written out. Arguments match the library's
+ * (positional, as it declares them); only the resolved value becomes
+ * {@link Wrapped}. See {@link K3sHelpers.list} for an options-object
+ * wrapper over the positional `list`.
+ */
+export interface TaggedObjectApi {
+    create<T extends KubernetesObject>(spec: T, pretty?: string, dryRun?: string, fieldManager?: string): Promise<Wrapped<T>>;
+    patch<T extends KubernetesObject>(spec: T, pretty?: string, dryRun?: string, fieldManager?: string, force?: boolean, patchStrategy?: PatchStrategy): Promise<Wrapped<T>>;
+    /** Read one object. **Throws** on 404 — to assert something is *gone*,
+     *  prefer {@link K3sHelpers.list} with a `metadata.name` field selector
+     *  and assert the returned `items` are empty (a throw carries no value
+     *  to assert on, and no provenance link). */
+    read<T extends KubernetesObject>(spec: KubernetesObjectRef<T>, pretty?: string, exact?: boolean, exportt?: boolean): Promise<Wrapped<T>>;
+    replace<T extends KubernetesObject>(spec: T, pretty?: string, dryRun?: string, fieldManager?: string): Promise<Wrapped<T>>;
+    delete(spec: KubernetesObject, pretty?: string, dryRun?: string, gracePeriodSeconds?: number, orphanDependents?: boolean, propagationPolicy?: string, body?: V1DeleteOptions): Promise<Wrapped<V1Status>>;
+    list<T extends KubernetesObject>(apiVersion: string, kind: string, namespace?: string, pretty?: string, exact?: boolean, exportt?: boolean, fieldSelector?: string, labelSelector?: string, limit?: number, continueToken?: string): Promise<Wrapped<KubernetesListObject<T>>>;
+}
 /**
  * Pre-instantiated `@kubernetes/client-node` API clients sharing the
  * same recording HTTP transport. Every method call lands on the test
@@ -118,9 +163,55 @@ type Tagged<T> = {
 export interface K3sClient {
     core: Tagged<CoreV1Api>;
     apps: Tagged<AppsV1Api>;
-    /** Generic object API — `create()`, `read()`, `patch()`, `delete()`
-     *  against any Kubernetes resource (custom resources included). */
-    objects: Tagged<KubernetesObjectApi>;
+    batch: Tagged<BatchV1Api>;
+    /** Generic object API — `create()`, `read()`, `patch()`, `delete()`,
+     *  `list()` against any Kubernetes resource, custom resources included.
+     *  Generic in the resource type: `objects.read<MyCr>({ … })` resolves to
+     *  `Wrapped<MyCr>`. */
+    objects: TaggedObjectApi;
+}
+/** Options for {@link K3sHelpers.apply}. */
+export interface ApplyOptions {
+    /** Namespace for documents that don't declare one (cluster-scoped kinds
+     *  are unaffected). Defaults to `default`, like `kubectl`. */
+    namespace?: string;
+    /** Server-side-apply field manager. Default `"spectest"`. Keep it stable
+     *  across runs — that's what makes re-applying an *update* rather than a
+     *  conflict. */
+    fieldManager?: string;
+    /** Take ownership of fields another manager owns, i.e. `kubectl apply
+     *  --force-conflicts`. Default `true`: a test environment has one owner
+     *  and a conflict is noise. */
+    force?: boolean;
+    /** Total budget for converging the whole manifest set, including retries
+     *  of documents whose CRD/webhook isn't up yet. Default 120 s. */
+    timeoutMs?: number;
+}
+/** A workload to wait on: `"web"`, `"deployment/web"`,
+ *  `"statefulset/db"`, `"daemonset/agent"`, or an object with
+ *  `kind`/`metadata` (e.g. an element of {@link K3sHelpers.apply}'s
+ *  result). Bare names are Deployments. */
+export type RolloutTarget = string | KubernetesObject | KubernetesObjectRef;
+/** Options for the wait helpers. */
+export interface WaitOptions {
+    /** Namespace of the object. Default `default`, or the object's own. */
+    namespace?: string;
+    /** Give up after this long. Default 120 s. */
+    timeoutMs?: number;
+    /** Poll interval. Default 500 ms. */
+    intervalMs?: number;
+}
+/** Which pods to read logs from — see {@link K3sHelpers.logs}. */
+export interface LogsOptions {
+    /** A single pod by name. */
+    pod?: string;
+    /** All pods matching a label selector (`"app=web"`). */
+    selector?: string;
+    namespace?: string;
+    /** Container within the pod (required only for multi-container pods). */
+    container?: string;
+    /** Tail this many lines per pod. Default 200. */
+    tailLines?: number;
 }
 /** Helpers a `k3s(...)` service exposes on `ctx.svc.<name>`. */
 export interface K3sHelpers {
@@ -136,13 +227,86 @@ export interface K3sHelpers {
     /** Pre-built API clients. */
     client: K3sClient;
     /**
-     * Apply a (multi-document) YAML manifest. Each parsed document is
-     * created via `KubernetesObjectApi.create`. Returns the API server's
-     * response objects in input order — each element inspect-wrapped (the
-     * array container itself is plain), so `expect(created[0]!.metadata.uid)`
-     * links to its create call.
+     * Apply a (multi-document) YAML manifest with **server-side apply**
+     * semantics — the API equivalent of `kubectl apply --server-side
+     * --force-conflicts`. Each document is `PATCH`ed with
+     * `application/apply-patch+yaml`, so applying is create-or-update:
+     * re-applying an edited manifest converges instead of failing
+     * `AlreadyExists`, which is what makes it usable for real manifest sets
+     * (and for a `dependsOn` child re-applying over its parent's state).
+     *
+     * Documents that can't land *yet* are retried until `opts.timeoutMs`:
+     * a CR whose CRD is in the same manifest, or a resource an admission
+     * webhook rejects while its own pod is still coming up, both resolve on
+     * a later round instead of failing the run. A document that keeps
+     * failing throws with the API server's own message.
+     *
+     * Returns the API server's response objects in input order — each
+     * element inspect-wrapped (the array container itself is plain), so
+     * `expect(applied[0]!.metadata.uid)` links to its apply call.
+     *
+     * Nothing here shells out to `kubectl`; the cluster is driven over its
+     * API from the daemon.
+     */
+    apply(manifest: string, opts?: ApplyOptions): Promise<Wrapped<KubernetesObject>[]>;
+    /**
+     * Wait until a Deployment / StatefulSet / DaemonSet has actually rolled
+     * out: the controller has observed the current generation, every replica
+     * is updated, and the desired number are Ready (the checks `kubectl
+     * rollout status` makes). Throws on timeout with the last-seen status
+     * plus pod phases, container reasons and recent Warning events from the
+     * namespace, so a stuck image pull or CrashLoop is readable from the
+     * failure alone.
+     *
+     * ```ts
+     * await ctx.svc.k8s.apply(manifest);
+     * await ctx.svc.k8s.waitForRollout("web");
+     * await ctx.svc.k8s.waitForRollout("statefulset/db", { namespace: "data" });
+     * ```
+     */
+    waitForRollout(target: RolloutTarget, opts?: WaitOptions): Promise<void>;
+    /**
+     * Wait for a Job to finish. Resolves with the completed Job (Complete
+     * condition, or `succeeded` at the requested completion count) and
+     * throws if it fails — with the failed pods' logs attached, which is
+     * the thing you actually want when a migration or seed Job dies.
+     *
+     * ```ts
+     * await ctx.svc.k8s.apply(migrateJob);
+     * const job = await ctx.svc.k8s.waitForJob("migrate");
+     * expect(job.status?.succeeded).toBe(1);
+     * ```
+     */
+    waitForJob(name: string, opts?: WaitOptions): Promise<Wrapped<V1Job>>;
+    /**
+     * Read pod logs — one pod by `pod`, or every pod matching `selector`
+     * (concatenated, each preceded by a `==> <pod> <==` header). The
+     * diagnostic companion to the wait helpers.
+     */
+    logs(opts: LogsOptions): Promise<Wrapped<string>>;
+    /**
+     * List objects of any kind by options object rather than the library's
+     * ten positional parameters (`list(apiVersion, kind, namespace, pretty,
+     * exact, exportt, fieldSelector, …)`). Generic in the resource type, so
+     * custom resources keep their shape:
+     *
+     * ```ts
+     * // "the Branch is gone" — without a 404 throw to catch
+     * const left = await ctx.svc.k8s.list<Branch>({
+     *   apiVersion: "xata.io/v1", kind: "Branch",
+     *   fieldSelector: `metadata.name=${name}`,
+     * });
+     * expect(left.items).toHaveLength(0);
+     * ```
      */
-    apply: (manifest: string) => Promise<Wrapped<KubernetesObject>[]>;
+    list<T extends KubernetesObject = KubernetesObject>(opts: {
+        apiVersion: string;
+        kind: string;
+        namespace?: string;
+        fieldSelector?: string;
+        labelSelector?: string;
+        limit?: number;
+    }): Promise<Wrapped<KubernetesListObject<T>>>;
 }
 export declare function k3s(opts?: K3sOptions): {
     readyCheck: {
@@ -154,7 +318,7 @@ export declare function k3s(opts?: K3sOptions): {
         name: string;
         helpers: K3sHelpers;
     }) => Promise<void>;
-    helpers: ({ name, exec }: ServiceHelpersContext) => Promise<K3sHelpers>;
+    helpers: ({ name, exec, poll }: ServiceHelpersContext) => Promise<K3sHelpers>;
     files?: {
         path: string;
         content: string;
@@ -169,4 +333,3 @@ export declare function k3s(opts?: K3sOptions): {
     cgroupns: string;
     ports: number[];
 };
-export {};