@symbiote-native/test-utils 0.1.1 → 0.1.3

package/README.md

@@ -1,6 +1,6 @@
 # @symbiote-native/test-utils
 
-The **shared fake-Fabric test harness** of [SymbioteNative](../../README.md) (ADR 0025) — one
+The **shared fake-Fabric test harness** of [SymbioteNative](../../README.md) — one
 `installFabric()` that puts a fresh, faithful fake `nativeFabricUIManager` on `globalThis` and
 returns a handle to inspect what a renderer committed. It replaces the per-file fake slot every
 headless test used to copy-paste (×65 across the repo) with one implementation, shared by the
@@ -44,7 +44,7 @@ otherwise leak state into the next one.
 ## What `installFabric()` gives you
 
 - **`committed`** — the child set from the most recent `completeRoot`, and **`appRoot()`** — unwraps
-  RN's synthetic `box-none` AppContainer root (ADR 0015) so a test doesn't re-check that invariant by
+  RN's synthetic `box-none` AppContainer root so a test doesn't re-check that invariant by
   hand.
 - **`created`** and **`find(predicate)`** — every node ever `createNode`'d this run (clones
   excluded), and a lookup by predicate (e.g. "the app's own `View` with this `testID`").

package/build/fake-fabric.d.ts

@@ -0,0 +1,42 @@
+export interface IFakeNode {
+    tag: number;
+    viewName: string;
+    props: Record<string, unknown>;
+    children: IFakeNode[];
+    instanceHandle: unknown;
+    /** Fabric family parent. Clones keep the same tag/family, so reparenting a family is illegal. */
+    parentFamilyTag?: number;
+}
+export type IEventHandler = (instanceHandle: unknown, topLevelType: string, nativeEvent: Record<string, unknown>) => void;
+export interface IFabricRecorder {
+    /** The child set handed to the most recent `completeRoot`. */
+    committed: IFakeNode[];
+    /** Every node ever `createNode`'d this run (clones excluded). */
+    created: IFakeNode[];
+    /** Every imperative command dispatched at a committed Fabric node. */
+    commands: Array<{
+        node: IFakeNode;
+        commandName: string;
+        args: readonly unknown[];
+    }>;
+    /** Call counters, for tests that assert "exactly N native nodes were created". */
+    counts: {
+        createNode: number;
+        completeRoot: number;
+    };
+    /**
+     * RN wraps every commit in a synthetic `box-none` AppContainer root.
+     * Returns it, asserting it is the single expected root, so each test unwraps the
+     * AppContainer the same way instead of re-checking the invariant by hand.
+     */
+    appRoot(): IFakeNode;
+    /** Find the first `createNode`'d node matching a predicate (e.g. the app's own View). */
+    find(predicate: (node: IFakeNode) => boolean): IFakeNode | undefined;
+    /** Deliver a native event to the renderer's registered handler. */
+    fireEvent(handle: unknown, topLevelType: string, nativeEvent?: Record<string, unknown>): void;
+    /** Serialize a node list to `RCTView(RCTText(RCTRawText "text"))` shorthand. */
+    serialize(nodes: IFakeNode[]): string;
+    /** Zero the counters and clear `committed` / `created` (the event handler survives). */
+    reset(): void;
+}
+export declare function installFabric(): IFabricRecorder;

package/build/fake-fabric.js

@@ -0,0 +1,100 @@
+// 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).
+//
+// 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").
+function mergeFabricProps(previous, diff) {
+    return { ...previous, ...diff };
+}
+export function installFabric() {
+    let committed = [];
+    const created = [];
+    const commands = [];
+    const counts = { createNode: 0, completeRoot: 0 };
+    let eventHandler;
+    const slot = {
+        createNode(tag, viewName, _rootTag, props, instanceHandle) {
+            counts.createNode += 1;
+            const node = { tag, viewName, props, children: [], instanceHandle };
+            created.push(node);
+            return node;
+        },
+        cloneNodeWithNewProps: (node, newProps) => ({
+            ...node,
+            props: mergeFabricProps(node.props, newProps),
+        }),
+        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) {
+                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;
+            parent.children.push(child);
+            return parent;
+        },
+        appendChildToSet(childSet, child) {
+            childSet.push(child);
+        },
+        completeRoot(_rootTag, childSet) {
+            counts.completeRoot += 1;
+            committed = childSet;
+        },
+        registerEventHandler(handler) {
+            eventHandler = handler;
+        },
+        dispatchCommand(node, commandName, args) {
+            commands.push({ node, commandName, args });
+        },
+    };
+    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('')})` : '';
+        return `${node.viewName}${text}${kids}`;
+    };
+    return {
+        get committed() {
+            return committed;
+        },
+        created,
+        commands,
+        counts,
+        appRoot() {
+            const root = committed[0];
+            if (committed.length !== 1 || root?.props.pointerEvents !== 'box-none') {
+                throw new Error(`expected a single box-none AppContainer root, got ${committed.length} node(s)`);
+            }
+            return root;
+        },
+        find(predicate) {
+            return created.find(predicate);
+        },
+        fireEvent(handle, topLevelType, nativeEvent = {}) {
+            if (!eventHandler)
+                throw new Error('no event handler registered by the renderer');
+            eventHandler(handle, topLevelType, nativeEvent);
+        },
+        serialize(nodes) {
+            return nodes.map(serializeNode).join('');
+        },
+        reset() {
+            committed = [];
+            created.length = 0;
+            commands.length = 0;
+            counts.createNode = 0;
+            counts.completeRoot = 0;
+        },
+    };
+}

package/build/index.d.ts

@@ -0,0 +1 @@
+export * from './fake-fabric';

package/build/index.js

@@ -0,0 +1,4 @@
+// @symbiote-native/test-utils: shared, framework-agnostic test harness. Imported by
+// 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';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@symbiote-native/test-utils",
-  "version": "0.1.1",
+  "version": "0.1.3",
   "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.",
   "repository": {
     "type": "git",