@symbiote-native/test-utils 0.1.5 → 0.2.0

package/README.md

@@ -30,16 +30,21 @@ test('tap increments the counter', () => {
   const fabric = installFabric();
   mount(1, createElement(App));
 
-  const button = fabric.find((n) => n.viewName === 'RCTView' && n.props.testID === 'tap-target');
+  const button = fabric.find(
+    n => n.viewName === 'RCTView' && n.props.testID === 'tap-target',
+  );
   fabric.fireEvent(button!.instanceHandle, 'topClick', {});
 
   expect(fabric.serialize(fabric.committed)).toContain('Taps: 1');
 });
 ```
 
-Each test calls `installFabric()` fresh (or `.reset()` an existing handle between assertions in the
-same test) — the fake slot is a `globalThis` singleton, so a stale handle from a previous test would
-otherwise leak state into the next one.
+Call `installFabric()` ONCE per test file, at module scope, and `.reset()` the handle between
+tests. Do not re-install per test: the engine's `getSlot()` (`core/engine/src/fabric.ts`) reads the
+slot's methods once and caches them for the process lifetime, so a second `installFabric()` after
+anything has committed swaps the global while the engine keeps writing through the handle it
+already bound — the new recorder just stays empty, with nothing to signal why. File-level isolation
+comes from the test runner; `reset()` is what separates tests within a file.
 
 ## What `installFabric()` gives you
 
@@ -78,5 +83,5 @@ test that depends on it.
 
 ## Test it
 
-This package has no tests of its own — it *is* the test double every other package's `vitest` suite
+This package has no tests of its own — it _is_ the test double every other package's `vitest` suite
 imports.

package/build/fake-fabric.js

@@ -1,18 +1,12 @@
-// One shared fake `nativeFabricUIManager` for the unit suite. `installFabric()`
-// puts a fresh recording slot on `globalThis` and returns a handle to inspect what the
-// renderer committed. It replaces the per-file slot the smokes each copy-pasted (×65).
+// One shared fake `nativeFabricUIManager` for the unit suite. `installFabric()` puts a
+// fresh recording slot on `globalThis` and returns a handle to inspect what was committed.
 //
-// Faithful persistent (clone-on-write) semantics, identical to what the engine drives
-// against real Fabric: every clone is a NEW identity; `*NewProps` MERGES the payload onto
-// the previous props (the engine always sends a minimal diff — see `diffProps` in
-// commit.ts — and relies on native Fabric to merge it onto the retained props; a removed
-// key arrives as literal `null` and is kept as `null`, not deleted, so a test can still see
-// "explicitly reset" distinct from "never set"); the `*Children` variants reset children
-// (the engine re-appends). A persistence bug in the fake is now fixed once, here, for every
-// test, matching how the real engine's clone-on-write commit path behaves.
-// Mirrors real Fabric's clone*WithNewProps merge: `diff` is a minimal payload (only changed
-// keys, plus a removed key sent as literal `null` — kept as `null` here, not deleted, so a
-// test can tell "explicitly reset to default" apart from "never set").
+// Mirrors real Fabric's clone-on-write semantics: every clone gets a NEW identity;
+// `*NewProps` MERGES the diff onto previous props (the engine always sends a minimal diff —
+// see `diffProps` in commit.ts). A removed key arrives as literal `null` and stays `null`,
+// not deleted, so a test can tell "explicitly reset" apart from "never set". `*Children`
+// variants reset children (the engine re-appends).
+// See the header comment above for the merge/null-removal semantics this mirrors.
 function mergeFabricProps(previous, diff) {
     return { ...previous, ...diff };
 }
@@ -25,7 +19,13 @@ export function installFabric() {
     const slot = {
         createNode(tag, viewName, _rootTag, props, instanceHandle) {
             counts.createNode += 1;
-            const node = { tag, viewName, props, children: [], instanceHandle };
+            const node = {
+                tag,
+                viewName,
+                props,
+                children: [],
+                instanceHandle,
+            };
             created.push(node);
             return node;
         },
@@ -33,11 +33,19 @@ export function installFabric() {
             ...node,
             props: mergeFabricProps(node.props, newProps),
         }),
-        cloneNodeWithNewChildren: (node) => ({ ...node, children: [] }),
-        cloneNodeWithNewChildrenAndProps: (node, newProps) => ({ ...node, props: mergeFabricProps(node.props, newProps), children: [] }),
+        cloneNodeWithNewChildren: (node) => ({
+            ...node,
+            children: [],
+        }),
+        cloneNodeWithNewChildrenAndProps: (node, newProps) => ({
+            ...node,
+            props: mergeFabricProps(node.props, newProps),
+            children: [],
+        }),
         createChildSet: () => [],
         appendChild(parent, child) {
-            if (child.parentFamilyTag !== undefined && child.parentFamilyTag !== parent.tag) {
+            if (child.parentFamilyTag !== undefined &&
+                child.parentFamilyTag !== parent.tag) {
                 throw new Error(`Fabric family reparent: child ${child.viewName}#${child.tag} already belongs to parent #${child.parentFamilyTag}, cannot append to ${parent.viewName}#${parent.tag}`);
             }
             child.parentFamilyTag = parent.tag;
@@ -61,7 +69,9 @@ export function installFabric() {
     Object.assign(globalThis, { nativeFabricUIManager: slot });
     const serializeNode = (node) => {
         const text = node.viewName === 'RCTRawText' ? ` "${String(node.props.text)}"` : '';
-        const kids = node.children.length ? `(${node.children.map(serializeNode).join('')})` : '';
+        const kids = node.children.length
+            ? `(${node.children.map(serializeNode).join('')})`
+            : '';
         return `${node.viewName}${text}${kids}`;
     };
     return {

package/build/index.d.ts

@@ -1 +1,2 @@
 export * from './fake-fabric';
+export * from './wait-for';

package/build/index.js

@@ -2,3 +2,4 @@
 // the co-located tests across engine, adapters, and the example apps so the fake-Fabric
 // recorder and its helpers live in exactly one place.
 export * from './fake-fabric.js';
+export * from './wait-for.js';

package/build/wait-for.d.ts

@@ -0,0 +1,3 @@
+export declare function waitUntil(condition: () => boolean, label: string, timeoutMs?: number): Promise<void>;
+export declare function waitForQuiet(sample: () => number, label: string, stableTicks?: number, timeoutMs?: number): Promise<number>;
+export declare function advanceTicks(count: number): Promise<void>;

package/build/wait-for.js

@@ -0,0 +1,72 @@
+// Condition-based waiting, for tests that need "the framework has settled" rather than "N
+// macrotasks have elapsed".
+//
+// Nearly every suite here spells the wait as `await new Promise(r => setTimeout(r, 0))`, repeated
+// two or ten times. That is a PROXY for settling, and it holds only while the machine is idle: a
+// macrotask boundary guarantees the queue drained once, not that a batched commit, a zoneless
+// change-detection pass, or a press-timing timer has finished. Under a loaded full-suite run the
+// proxy breaks, and the failure reads as a product bug — a press that produced no event, change
+// detection that never stopped — rather than as the harness giving up early.
+//
+// Measured 2026-08-19: three tests across two adapters failed only inside a loaded `vitest run`
+// and passed in isolation, every one of them on a fixed tick count.
+//
+// Use `waitUntil` when a condition names what you are waiting for, and `waitForQuiet` when the
+// thing to wait for is the ABSENCE of further work. Do not raise a tick count to fix a flake —
+// that trades a fast failure for a slow one and keeps the race.
+const TICK_MS = 0;
+const DEFAULT_TIMEOUT_MS = 2_000;
+// Read off the host rather than imported, the same reason the engine's animations/raf.ts does:
+// this package's tsconfig carries no DOM and no Node lib, so the ambient names do not exist.
+function tick() {
+    const set = Reflect.get(globalThis, 'setTimeout');
+    if (typeof set !== 'function') {
+        throw new Error('setTimeout is not available on the host');
+    }
+    return new Promise(resolve => {
+        Reflect.apply(set, globalThis, [resolve, TICK_MS]);
+    });
+}
+function now() {
+    return Date.now();
+}
+// Polls `condition` once per macrotask until it holds, then resolves. Throws on timeout with
+// `label` in the message, so a genuine product failure still fails the test — loudly, and naming
+// what never happened.
+export async function waitUntil(condition, label, timeoutMs = DEFAULT_TIMEOUT_MS) {
+    const deadline = now() + timeoutMs;
+    while (!condition()) {
+        if (now() > deadline) {
+            throw new Error(`waitUntil timed out after ${timeoutMs}ms: ${label}`);
+        }
+        await tick();
+    }
+}
+// Waits until `sample` returns the same value across `stableTicks` consecutive macrotasks — the
+// shape for "work has stopped arriving". Returns the settled value so a caller can assert against
+// what actually happened rather than re-reading it.
+//
+// This is the honest way to write a "does not free-run" test: settle FIRST on a real condition,
+// then observe. Asserting no-growth over a fixed window without settling first only tests whether
+// the machine was fast enough.
+export async function waitForQuiet(sample, label, stableTicks = 3, timeoutMs = DEFAULT_TIMEOUT_MS) {
+    const deadline = now() + timeoutMs;
+    let last = sample();
+    let stable = 0;
+    while (stable < stableTicks) {
+        await tick();
+        const current = sample();
+        stable = current === last ? stable + 1 : 0;
+        last = current;
+        if (now() > deadline) {
+            throw new Error(`waitForQuiet timed out after ${timeoutMs}ms, still changing: ${label}`);
+        }
+    }
+    return last;
+}
+// Advances a fixed number of macrotasks. Kept for the cases where the wait genuinely is "let the
+// queue drain once" — a commit that is known to be one microtask away — rather than a settle.
+export async function advanceTicks(count) {
+    for (let index = 0; index < count; index += 1)
+        await tick();
+}

package/package.json

@@ -1,7 +1,8 @@
 {
   "name": "@symbiote-native/test-utils",
-  "version": "0.1.5",
+  "version": "0.2.0",
   "description": "Shared, framework-agnostic fake-Fabric test harness for SymbioteNative — the fake nativeFabricUIManager recorder used by the co-located test suites across the engine, every adapter, and the example apps.",
+  "license": "MIT",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/OneEyed1366/symbiote-native.git",