@voltro/testing 0.33.0 → 0.35.0

package/README.md

@@ -2,7 +2,7 @@
 
 # @voltro/testing
 
-**Test utilities for Voltro apps — deterministic clock, captured emails, queued LLM responses, scoped subject/tenant runners, and a cross-dialect parity harness.**
+**Test utilities for Voltro apps — deterministic clock, subject and row factories, a handler-level invoke and a request-level app harness, queued LLM responses, scoped subject/tenant runners, and a cross-dialect parity harness.**
 
 [📖 Documentation](https://docs.voltro.dev/docs/testing/overview) · [voltro.dev](https://voltro.dev) · [Voltro Cloud](https://voltro.cloud)
 

package/dist/client.d.ts

@@ -1,9 +1,40 @@
+import { Effect } from 'effect';
+import { Exit } from 'effect/Exit';
 import { ReactElement } from 'react';
 import { ReactNode } from 'react';
+import { RunForkOptions } from 'effect/Runtime';
+import { RuntimeFiber } from 'effect/Fiber';
+
+/**
+ * The runtime the hooks get. EXPORTED so it can be guarded.
+ *
+ * `runPromiseExit` is required, not optional: every write hook goes through
+ * `runRpcPromise`, which reads the exit and re-throws `Cause.squash(...)` so a
+ * rejection carries its `_tag` — and it calls `runtime.runPromiseExit`, not
+ * `runPromise`. A fake missing the method makes `mutate()` throw
+ * `runtime.runPromiseExit is not a function` into a `void`ed promise: no handler
+ * runs, nothing is recorded, and the component renders perfectly. This harness
+ * kept a two-method runtime for a release after the write path moved, and the
+ * failure read as "the click did not register".
+ *
+ * It is a module constant rather than a per-instance literal for one reason:
+ * `fakeRuntimeParity.test.ts` derives the required method set from the client's
+ * own source and checks it against THIS object, so the next method the client
+ * starts calling goes red here instead of in whichever hook reaches it first.
+ */
+export declare const FAKE_RUNTIME: {
+    runPromise: <A, E>(effect: Effect.Effect<A, E, never>, options?: {
+        readonly signal?: AbortSignal | undefined;
+    } | undefined) => Promise<A>;
+    runPromiseExit: <A, E>(effect: Effect.Effect<A, E, never>, options?: {
+        readonly signal?: AbortSignal;
+    } | undefined) => Promise< Exit<A, E>>;
+    runFork: <A, E>(effect: Effect.Effect<A, E>, options?: RunForkOptions) => RuntimeFiber<A, E>;
+    dispose: () => Effect.Effect<void, never, never>;
+};
 
 declare type Handler = (input: never) => unknown;
 
-/** Build a fake api context for tests. See the module comment. */
 export declare const makeVoltroTestClient: (config?: VoltroTestClientConfig) => VoltroTestClient;
 
 /** One recorded write, so a test can assert WHAT was called with WHICH input. */
@@ -13,13 +44,29 @@ export declare interface RecordedCall {
     readonly input: unknown;
 }
 
+/**
+ * The parts of a snapshot that are NOT the data.
+ *
+ * They exist because real pages render them: the notes template greys out rows
+ * while `pendingPatches > 0` and prints the time of the last delta from
+ * `emittedAt`. The harness hardcoded both, so a page that renders either had a
+ * state no test could reach — the gap you only find by pointing the harness at
+ * an app that was written before it.
+ */
+export declare interface SnapshotMeta {
+    /** Optimistic patches awaiting confirmation. Drives "n pending" affordances. */
+    readonly pendingPatches?: number;
+    /** When the server emitted this delta, in ms. */
+    readonly emittedAt?: number;
+}
+
 export declare interface VoltroTestClient {
     /** Wrap the component under test. */
     readonly Provider: (props: {
         readonly children: ReactNode;
     }) => ReactElement;
     /** Push new data for a tag — components re-render, like a server delta. */
-    readonly setSubscription: (tag: string, data: unknown) => void;
+    readonly setSubscription: (tag: string, data: unknown, meta?: SnapshotMeta) => void;
     /** Put a tag into the COLD-START error state (no snapshot + an error). */
     readonly failSubscription: (tag: string, error: unknown) => void;
     /** Return a tag to the loading state (no snapshot yet). */

package/dist/client.js

@@ -2,36 +2,45 @@ import { Effect as e } from "effect";
 import { createElement as t } from "react";
 import { FrameworkRuntimesContext as n, RpcErrorBus as r } from "@voltro/client";
 //#region src/client.tsx
-var i = (i = {}) => {
-	let a = i.apiName ?? "app", o = /* @__PURE__ */ new Map(), s = /* @__PURE__ */ new Map(), c = /* @__PURE__ */ new Map(), l = [];
-	for (let [e, t] of Object.entries(i.subscriptions ?? {})) o.set(e, {
+var i = {
+	runPromise: e.runPromise,
+	runPromiseExit: e.runPromiseExit,
+	runFork: e.runFork,
+	dispose: () => e.void
+}, a = (a = {}) => {
+	let o = a.apiName ?? "app", s = /* @__PURE__ */ new Map(), c = /* @__PURE__ */ new Map(), l = /* @__PURE__ */ new Map(), u = [];
+	for (let [e, t] of Object.entries(a.subscriptions ?? {})) s.set(e, {
 		data: t,
 		error: void 0,
-		revision: 0
+		revision: 0,
+		pendingPatches: 0,
+		emittedAt: void 0
 	});
-	let u = (e) => o.get(e) ?? {
+	let d = (e) => s.get(e) ?? {
 		data: void 0,
 		error: void 0,
-		revision: -1
-	}, d = (e) => {
-		c.delete(e);
-		for (let t of s.get(e) ?? []) t();
-	}, f = (e) => String(e[0] ?? ""), p = {
+		revision: -1,
+		pendingPatches: 0,
+		emittedAt: void 0
+	}, f = (e) => {
+		l.delete(e);
+		for (let t of c.get(e) ?? []) t();
+	}, p = (e) => String(e[0] ?? ""), m = {
 		peek: (e) => {
-			let t = f(e), n = c.get(t);
+			let t = p(e), n = l.get(t);
 			if (n) return n;
-			let r = u(t), i = {
+			let r = d(t), i = {
 				data: r.data,
 				revision: r.revision,
-				emittedAt: void 0,
+				emittedAt: r.emittedAt,
 				error: r.error,
-				pendingPatches: 0
+				pendingPatches: r.pendingPatches
 			};
-			return c.set(t, i), i;
+			return l.set(t, i), i;
 		},
 		subscribe: (e, t, n, r) => {
-			let i = f(e), a = s.get(i) ?? /* @__PURE__ */ new Set();
-			return a.add(r), s.set(i, a), { unsubscribe: () => {
+			let i = p(e), a = c.get(i) ?? /* @__PURE__ */ new Set();
+			return a.add(r), c.set(i, a), { unsubscribe: () => {
 				a.delete(r);
 			} };
 		},
@@ -41,11 +50,11 @@ var i = (i = {}) => {
 		update: () => {},
 		forTag: () => ({ patchedCount: 0 }),
 		refreshAll: () => {}
-	}, m = {}, h = (t, n, r) => {
-		let i = t.split("."), a = m;
+	}, h = {}, g = (t, n, r) => {
+		let i = t.split("."), a = h;
 		for (let e of i.slice(0, -1)) a[e] = a[e] ?? {}, a = a[e];
 		a[i[i.length - 1]] = (i) => e.tryPromise({
-			try: async () => (l.push({
+			try: async () => (u.push({
 				kind: n,
 				tag: t,
 				input: i
@@ -53,47 +62,48 @@ var i = (i = {}) => {
 			catch: (e) => e
 		});
 	};
-	for (let [e, t] of Object.entries(i.mutations ?? {})) h(e, "mutation", t);
-	for (let [e, t] of Object.entries(i.actions ?? {})) h(e, "action", t);
-	let g = {
-		runtime: {
-			runPromise: e.runPromise,
-			runFork: e.runFork
-		},
-		cache: p,
-		client: m,
+	for (let [e, t] of Object.entries(a.mutations ?? {})) g(e, "mutation", t);
+	for (let [e, t] of Object.entries(a.actions ?? {})) g(e, "action", t);
+	let _ = {
+		runtime: i,
+		cache: m,
+		client: h,
 		descriptors: {},
 		inspectBaseUrl: "http://test.local",
 		errorBus: new r()
-	}, _ = {
+	}, v = {
 		get: (e) => {
-			if (e !== a) throw Error(`makeVoltroTestClient: component asked for api '${e}' but the harness was built for '${a}'. Pass { apiName: '${e}' }.`);
-			return g;
+			if (e !== o) throw Error(`makeVoltroTestClient: component asked for api '${e}' but the harness was built for '${o}'. Pass { apiName: '${e}' }.`);
+			return _;
 		},
-		names: [a]
+		names: [o]
 	};
 	return {
-		Provider: ({ children: e }) => t(n.Provider, { value: _ }, e),
-		setSubscription: (e, t) => {
-			let n = u(e);
-			o.set(e, {
+		Provider: ({ children: e }) => t(n.Provider, { value: v }, e),
+		setSubscription: (e, t, n) => {
+			let r = d(e);
+			s.set(e, {
 				data: t,
 				error: void 0,
-				revision: n.revision + 1
-			}), d(e);
+				revision: r.revision + 1,
+				pendingPatches: n?.pendingPatches ?? 0,
+				emittedAt: n?.emittedAt
+			}), f(e);
 		},
 		failSubscription: (e, t) => {
-			o.set(e, {
+			s.set(e, {
 				data: void 0,
 				error: t,
-				revision: -1
-			}), d(e);
+				revision: -1,
+				pendingPatches: 0,
+				emittedAt: void 0
+			}), f(e);
 		},
 		resetSubscription: (e) => {
-			o.delete(e), d(e);
+			s.delete(e), f(e);
 		},
-		calls: l
+		calls: u
 	};
 };
 //#endregion
-export { i as makeVoltroTestClient };
+export { i as FAKE_RUNTIME, a as makeVoltroTestClient };