feat(test): mock main route and local storage in setup (#11578) (#11579)

* feat(test): mock main route and local storage in setup (#11578)

* fix(test): use Neo namespace helper in setup mocks (#11578)

---------

Co-authored-by: tobiu <tobiasuhlig78@gmail.com>

Author: neo-gpt

learn/guides/testing/UnitTesting.md

@@ -70,6 +70,19 @@ In a Unit Test:
 2.  We import **both** the App Worker classes and the VDom Worker classes into the same Node.js scope.
 3.  The `setup()` function mocks the messaging layer, allowing them to talk directly.
 
+### Runtime Facade Mocks
+
+`test/playwright/setup.mjs` also installs minimal runtime facades that production-shaped component trees expect during construction:
+
+```javascript
+setup({
+    mockMain        : true, // provides Neo.Main.setRoute()
+    mockLocalStorage: true  // provides Neo.main.addon.LocalStorage
+});
+```
+
+Both flags default to `true`. This lets downstream apps smoke-test a root `Neo.container.Viewport` with a real `Neo.controller.Component` controller, including `defaultHash` routing and persisted UI state reads, without wiring the browser main-thread runtime. Set either flag to `false` when a spec intentionally installs a richer route or storage mock before calling `setup()`.
+
 ### Understanding Imports (Critical)
 
 Because we are bypassing the standard build/worker loading process, you must manually import the dependencies your test needs.

test/playwright/setup.mjs

@@ -28,8 +28,22 @@ globalThis.DOMRect = class DOMRect {
 // This file sets up the Node.js global scope to run Neo.mjs
 // VDOM unit tests without a browser or jsdom.
 
+/**
+ * Configures the single-threaded Playwright unit-test runtime with the minimal
+ * Neo globals required by App Worker and VDom Worker classes.
+ * @param {Object} options={}
+ * @param {Object} options.appConfig={} App facade overrides.
+ * @param {Boolean} options.mockLocalStorage=true True installs minimal `Neo.main.addon.LocalStorage` methods.
+ * @param {Boolean} options.mockMain=true True installs a minimal `Neo.Main.setRoute()` method.
+ * @param {Object} options.neoConfig={} Neo.config overrides.
+ */
 export function setup(options = {}) {
-    const { neoConfig = {}, appConfig = {} } = options;
+    const {
+        appConfig        = {},
+        mockLocalStorage = true,
+        mockMain         = true,
+        neoConfig        = {}
+    } = options;
 
     const defaultNeoConfig = {
         environment : 'development',
@@ -55,6 +69,10 @@ export function setup(options = {}) {
     // Standardized Global Mocks to prevent cross-contamination in Playwright worker reuse
     Neo.applyDeltas ??= async () => {};
 
+    if (mockMain) {
+        Neo.ns('Neo.Main', true).setRoute ??= () => {};
+    }
+
     Neo.main ??= {
         addon: {
             DragDrop: {},
@@ -82,6 +100,18 @@ export function setup(options = {}) {
         }
     };
 
+    if (mockLocalStorage) {
+        const localStorage = Neo.ns('Neo.main.addon.LocalStorage', true);
+
+        localStorage.createLocalStorageItem  ??= async () => {};
+        localStorage.destroyLocalStorageItem ??= async () => {};
+        localStorage.readLocalStorageItem    ??= async ({key} = {}) => ({
+            key,
+            value: Array.isArray(key) ? Object.fromEntries(key.map(item => [item, null])) : null
+        });
+        localStorage.updateLocalStorageItem  ??= async () => {};
+    }
+
     Neo.currentWorker ??= {
         getAddon: async () => ({
             register  : () => {},

test/playwright/unit/container/ViewportSetupMocks.spec.mjs

@@ -0,0 +1,158 @@
+import {setup} from '../../setup.mjs';
+
+const appName = 'ContainerViewportSetupMocksTest';
+
+setup({
+    appConfig: {
+        name: appName
+    },
+    mockLocalStorage: false,
+    mockMain        : false
+});
+
+import {test, expect}       from '@playwright/test';
+import Neo                  from '../../../../src/Neo.mjs';
+import * as core            from '../../../../src/core/_export.mjs';
+import ComponentController  from '../../../../src/controller/Component.mjs';
+import Viewport             from '../../../../src/container/Viewport.mjs';
+
+/**
+ * @summary Test controller for exercising setup-level route and storage mocks.
+ *
+ * The controller combines default-hash routing with a construction-time LocalStorage
+ * read to mirror production-shaped root viewport controllers in downstream apps.
+ * @class Test.Unit.Container.ViewportSetupMocksController
+ * @extends Neo.controller.Component
+ */
+class TestController extends ComponentController {
+    static config = {
+        className  : 'Test.Unit.Container.ViewportSetupMocksController',
+        defaultHash: '/home'
+    }
+
+    onComponentConstructed() {
+        this.storagePromise = Neo.main.addon.LocalStorage.readLocalStorageItem({
+            key     : ['viewportSetupTheme', 'viewportSetupLayout'],
+            windowId: this.windowId
+        });
+    }
+}
+TestController = Neo.setupClass(TestController);
+
+/**
+ * @summary Test viewport for the setup runtime-facade smoke path.
+ *
+ * The viewport disables browser-only body mounting behavior so the unit test can
+ * focus on controller construction without requiring a real main-thread DOM.
+ * @class Test.Unit.Container.ViewportSetupMocksViewport
+ * @extends Neo.container.Viewport
+ */
+class TestViewport extends Viewport {
+    static config = {
+        applyBodyCls: false,
+        autoMount   : false,
+        className   : 'Test.Unit.Container.ViewportSetupMocksViewport',
+        controller  : TestController
+    }
+}
+TestViewport = Neo.setupClass(TestViewport);
+
+test.describe('test/playwright/setup.mjs viewport mocks', () => {
+    let previousMain, previousLocalStorage, viewport;
+
+    test.beforeEach(() => {
+        previousMain         = Neo.Main;
+        previousLocalStorage = Neo.main?.addon?.LocalStorage;
+        viewport             = null;
+
+        delete Neo.Main;
+
+        if (Neo.main?.addon) {
+            delete Neo.main.addon.LocalStorage;
+        }
+    });
+
+    test.afterEach(() => {
+        viewport?.destroy();
+
+        if (previousMain === undefined) {
+            delete Neo.Main;
+        } else {
+            Neo.Main = previousMain;
+        }
+
+        if (previousLocalStorage === undefined) {
+            delete Neo.main.addon.LocalStorage;
+        } else {
+            Neo.main.addon.LocalStorage = previousLocalStorage;
+        }
+    });
+
+    test('setup() provides default Neo.Main and LocalStorage mocks for viewport controller smoke tests', async () => {
+        setup({
+            appConfig: {
+                name: appName
+            }
+        });
+
+        expect(Neo.Main.setRoute).toBeInstanceOf(Function);
+        expect(Neo.main.addon.LocalStorage.readLocalStorageItem).toBeInstanceOf(Function);
+        expect(Neo.main.addon.LocalStorage.updateLocalStorageItem).toBeInstanceOf(Function);
+        expect(Neo.main.addon.LocalStorage.destroyLocalStorageItem).toBeInstanceOf(Function);
+
+        viewport = Neo.create(TestViewport, {appName});
+
+        await viewport.controller.ready();
+        await viewport.controller.storagePromise;
+
+        expect(viewport.controller.isReady).toBe(true);
+    });
+
+    test('setup() preserves pre-installed Neo.Main and LocalStorage mocks', async () => {
+        const routeCalls = [];
+        const storageReads = [];
+
+        Neo.Main = {
+            setRoute: data => routeCalls.push(data)
+        };
+
+        Neo.main.addon.LocalStorage = {
+            destroyLocalStorageItem: async () => {},
+            readLocalStorageItem: async data => {
+                storageReads.push(data);
+                return {key: data.key, value: Object.fromEntries(data.key.map(item => [item, null]))}
+            },
+            updateLocalStorageItem: async () => {}
+        };
+
+        setup({
+            appConfig: {
+                name: appName
+            }
+        });
+
+        viewport = Neo.create(TestViewport, {appName});
+
+        await viewport.controller.ready();
+        await viewport.controller.storagePromise;
+
+        expect(routeCalls).toEqual([{value: '/home', windowId: null}]);
+        expect(storageReads).toEqual([{
+            key     : ['viewportSetupTheme', 'viewportSetupLayout'],
+            windowId: null
+        }]);
+    });
+
+    test('setup() can opt out of Neo.Main and LocalStorage mocks', () => {
+        setup({
+            appConfig: {
+                name: appName
+            },
+            mockLocalStorage: false,
+            mockMain        : false
+        });
+
+        expect(Neo.Main).toBeUndefined();
+        expect(Neo.main.addon.LocalStorage).toBeUndefined();
+    });
+});