@equinor/fusion-framework-vitest-plugin-react-app 1.0.0-next.4 → 1.0.0-next.6

package/dist/types/scope/resolve-fusion.d.ts

@@ -9,11 +9,14 @@ import type { NavigationModule } from '@equinor/fusion-framework-module-navigati
  * given.
  *
  * @template TEnv - The application environment descriptor.
- * @param options - `env` seeds the built-in app manifest mock; navigation defaults to real
- *   browser history, matching Browser Mode. `configure` runs afterwards on the same
- *   configurator — e.g. call `enableNavigation` again to override the history, or register
- *   extra modules and service discovery entries. `fusion`, an already-built parent instance,
- *   is reused as-is and skips `configure` entirely.
+ * @param options - `env` seeds the built-in app manifest mock; navigation defaults to in-memory
+ *   history, so tests don't leak URL/history state between runs. Feature flags default to the
+ *   in-memory feature-flag mock, with none enabled, when the optional
+ *   `@equinor/fusion-framework-module-feature-flag` peer dependency is installed. `configure`
+ *   runs afterwards on the same configurator — e.g. call `enableNavigation` or
+ *   `enableFeatureFlagMock` again to override either, or register extra modules and service
+ *   discovery entries. `fusion`, an already-built parent instance, is reused as-is and skips
+ *   `configure` entirely.
  * @returns The given `fusion`, or a fresh mocked parent Fusion instance.
  */
 export declare function resolveFusion<TEnv extends AppEnv = AppEnv>(options?: {

package/dist/types/test-app.d.ts

@@ -45,8 +45,12 @@ import type { FrameworkMockConfigureFn } from '@equinor/fusion-framework/mock';
  * @example Seed a module for every test in a suite
  * ```tsx
  * describe('with a seeded context module', () => {
- *   const test = testApp.extend('configureApp', { injected: true }, () =>
- *     (configurator) => enableContextMock(configurator, (mock) => mock.setCurrentContext(projectA)),
+ *   const test = testApp.extend(
+ *     'configureApp',
+ *     { injected: true },
+ *     (): AppMockConfigureFn =>
+ *       (configurator) =>
+ *         enableContextMock(configurator, (mock) => mock.setCurrentContext(projectA)),
  *   );
  *
  *   test('starts on the seeded context', async ({ render }) => {
@@ -56,16 +60,46 @@ import type { FrameworkMockConfigureFn } from '@equinor/fusion-framework/mock';
  * });
  * ```
  *
+ * @example Type `app`'s registered modules for consumers
+ * ```tsx
+ * // `configureApp`'s `TModules` generic only types that callback's own `configurator` parameter.
+ * // `app`'s type was already fixed (to `unknown`) when the base `testApp` chain defined it, so a
+ * // later `configureApp` override does not retroactively change what `app` is typed as. Re-extend
+ * // `app` too, with the same `TModules`, to get a typed `app.navigation` in tests.
+ * const test = testApp
+ *   .extend(
+ *     'configureApp',
+ *     { injected: true },
+ *     ({ configureApp }): AppMockConfigureFn<[NavigationModule]> =>
+ *       async (configurator, args) => {
+ *         await configureApp?.(configurator, args);
+ *         enableNavigation(configurator, '/app');
+ *       },
+ *   )
+ *   .extend('app', ({ configureApp, appEnv, fusion }) =>
+ *     mockAppModules<[NavigationModule], AppEnv>(configureApp, appEnv as AppEnv, fusion),
+ *   );
+ *
+ * test('exposes the navigation module', async ({ app }) => {
+ *   expect(app.navigation).toBeDefined();
+ * });
+ * ```
+ *
  * @example Extend the parent framework mock with an application module
  * ```tsx
- * const test = testApp.extend('configureFusion', { injected: true }, () =>
- *   (configurator) => {
- *     enableFeatureFlagMock(configurator);
- *     configurator.serviceDiscovery.addServices([
- *       { key: 'people', uri: baseUrl('people') },
- *       { key: 'context', uri: baseUrl('context') },
- *     ]);
- *   },
+ * const test = testApp.extend(
+ *   'configureFusion',
+ *   { injected: true },
+ *   (): FrameworkMockConfigureFn<[AppModule, NavigationModule]> =>
+ *     (configurator) => {
+ *       // seed a specific flag rather than merely enabling the mock — that's already the
+ *       // default when the optional feature-flag peer dependency is installed
+ *       enableFeatureFlagMock(configurator, (mock) => mock.addFeature({ key: 'new-search', enabled: true }));
+ *       configurator.serviceDiscovery.addServices([
+ *         { key: 'people', uri: baseUrl('people') },
+ *         { key: 'context', uri: baseUrl('context') },
+ *       ]);
+ *     },
  * );
  * ```
  */

package/dist/types/version.d.ts

@@ -1 +1 @@
-export declare const version = "1.0.0-next.4";
+export declare const version = "1.0.0-next.6";

package/docs/advanced.md

@@ -147,15 +147,20 @@ when the custom parent must serve the app's manifest and config. Use
 ## Extend the parent framework mock with `configureFusion`
 
 `fusion` (built by [`resolveFusion`](../src/scope/resolve-fusion.ts)) always carries a mocked
-`app` module (serving this app's manifest) and a `navigation` module with real browser history,
-matching Browser Mode. `configureFusion` runs on the same configurator afterwards, so a test can
-register extra framework-level modules or override that setup, without reimplementing it:
+`app` module (serving this app's manifest) and a `navigation` module with in-memory history, so
+tests don't leak URL/history state between runs. It also mocks the `featureFlag` module — with
+no flags enabled, so `useFeature` needs no `localStorage` or URL seeding — but only when
+`@equinor/fusion-framework-module-feature-flag` (an optional peer dependency) is actually
+installed; apps that don't use feature flags aren't forced to add it. `configureFusion` runs on
+the same configurator afterwards, so a test can register extra framework-level modules or
+override that setup, without reimplementing it:
 
 ```tsx
 import { enableFeatureFlagMock } from '@equinor/fusion-framework-module-feature-flag/mock';
 
 const test = baseTest.extend('configureFusion', { injected: true }, () => (configurator) => {
-  enableFeatureFlagMock(configurator);
+  // seed a specific flag rather than merely enabling the mock — that's already the default
+  enableFeatureFlagMock(configurator, (mock) => mock.addFeature({ key: 'new-search', enabled: true }));
   configurator.serviceDiscovery.addServices([{ key: 'people', uri: baseUrl('people') }]);
 });
 ```
@@ -172,7 +177,7 @@ import { enableNavigation, createHistory } from '@equinor/fusion-framework-modul
 
 test.override('configureFusion', { injected: true }, () => (configurator) =>
   enableNavigation(configurator, {
-    configure: (config) => config.setHistory(createHistory('memory')),
+    configure: (config) => config.setHistory(createHistory('browser')),
   }),
 );
 ```

package/docs/configuration.md

@@ -92,7 +92,7 @@ export default defineProject({
       instances: [{ browser: 'chromium' }],
     },
   },
-  server: { warmup: { clientFiles: ['src/**/*.{ts,tsx}'] } },
+  server: { warmup: { clientFiles: ['src/**/*.{ts,tsx}', '!src/**/*.d.ts'] } },
 });
 ```
 

package/docs/migrating-an-existing-app.md

@@ -178,6 +178,11 @@ aren't Fusion-specific.
 Review polyfills and component replacements that may only exist for `jsdom` or `happy-dom`.
 Remove one workaround at a time and run the affected tests against the real component.
 
+A common one: a no-op `window.ResizeObserver` stub carried over from `jsdom`/`happy-dom` setup.
+Real Chromium doesn't need the stub, but leaving it in place silently breaks any component that
+measures itself through `ResizeObserver` before rendering — for example a virtualized popover
+list. Remove the stub rather than porting it.
+
 Do not remove unrelated suppressions automatically. AG Grid license messages, Lit dev-mode
 warnings, network behavior, and app-specific test doubles may still apply in Browser Mode.
 

package/docs/troubleshooting.md

@@ -18,6 +18,9 @@ resolve the app, or behaves differently in Vitest Browser Mode.
 | The app starts signed in unexpectedly | The MSAL mock defaults to `Test User` | Set `configurator.msal.setAccount(null)` before rendering |
 | State configured in one test is missing in another | Framework and app fixtures are test-scoped | Seed the required state per test or publish reusable fixture declarations with `test.extend` |
 | `vi.spyOn` fails on an imported module in Browser Mode | Native ESM module namespace objects are sealed | Use `vi.mock('./module.js', { spy: true })` as documented by Vitest Browser Mode |
+| A `<Router>` route with a catch-all or parameterized `path` never renders; every query on it times out | The navigation module's current location does not match that path yet | Push the target location through the navigation module (`app.modules.navigation.push(path)`) before rendering, not after |
+| A virtualized list or popover (for example an EDS `Autocomplete` built on `@tanstack/react-virtual`) never renders its rows | `window.ResizeObserver` was stubbed as a no-op in test setup | Remove the stub; real Chromium's `ResizeObserver` is required for virtualized layout to measure correctly |
+| `test.each` runs but a fixture in its per-case callback is `undefined` | `test.each` does not forward `test.extend` fixture context to each case | Use Vitest's `test.for` instead, which does receive fixture context |
 
 ## Verify the project wiring
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@equinor/fusion-framework-vitest-plugin-react-app",
-  "version": "1.0.0-next.4",
+  "version": "1.0.0-next.6",
   "description": "Vite plugin resolving an application's manifest, config, and module-configurator as virtual modules for testing.",
   "type": "module",
   "exports": {
@@ -47,15 +47,15 @@
     "access": "public"
   },
   "dependencies": {
-    "@equinor/fusion-framework": "8.1.0-next.1",
-    "@equinor/fusion-framework-cli": "15.2.8-next.2",
+    "@equinor/fusion-framework": "8.1.0-next.2",
+    "@equinor/fusion-framework-app": "13.0.3-next.1",
+    "@equinor/fusion-framework-cli": "15.3.0-next.1",
     "@equinor/fusion-framework-module": "6.1.3-next.0",
-    "@equinor/fusion-framework-module-app": "8.1.0-next.0",
-    "@equinor/fusion-framework-module-navigation": "7.0.8-next.0",
-    "@equinor/fusion-framework-react": "9.0.0-next.0",
-    "@equinor/fusion-framework-app": "14.0.0-next.1",
+    "@equinor/fusion-framework-module-app": "8.0.6-next.0",
+    "@equinor/fusion-framework-module-navigation": "7.0.9-next.0",
     "@equinor/fusion-framework-react-module": "4.0.3-next.0",
-    "@equinor/fusion-imports": "2.0.3-next.0"
+    "@equinor/fusion-imports": "2.0.3-next.1",
+    "@equinor/fusion-framework-react": "9.0.0-next.0"
   },
   "devDependencies": {
     "@types/react": "^19.2.7",
@@ -68,7 +68,8 @@
     "typescript": "^7.0.2",
     "vite": "^8.0.0",
     "vitest": "^4.1.10",
-    "vitest-browser-react": "^2.2.0"
+    "vitest-browser-react": "^2.2.0",
+    "@equinor/fusion-framework-module-feature-flag": "2.1.0-next.1"
   },
   "peerDependencies": {
     "@types/react": "^18.0.0 || ^19.0.0",
@@ -79,7 +80,13 @@
     "rxjs": "^7.0.0",
     "vite": "^8.0.0",
     "vitest": "^4.0.0",
-    "vitest-browser-react": "^2.2.0"
+    "vitest-browser-react": "^2.2.0",
+    "@equinor/fusion-framework-module-feature-flag": "2.1.0-next.1"
+  },
+  "peerDependenciesMeta": {
+    "@equinor/fusion-framework-module-feature-flag": {
+      "optional": true
+    }
   },
   "scripts": {
     "build": "tsc -b",

package/src/define-project.ts

@@ -68,13 +68,15 @@ export const defineProject = (override?: AppTestConfigOverride): UserWorkspaceCo
     // pre-transforms all source up front so deps only reached via lazy/code-split imports
     // (e.g. route components) are discovered before the first test request, not mid-run —
     // the latter forces Vite to reload the page and fails the in-flight test file import
-    server: { warmup: { clientFiles: ['src/**/*.{ts,tsx}'] } },
+    // `.d.ts` files are excluded: a CJS-style declaration file (e.g. one using `export =`)
+    // fails the warmup scan when loaded as ESM
+    server: { warmup: { clientFiles: ['src/**/*.{ts,tsx}', '!src/**/*.d.ts'] } },
     // same reasoning as `server.warmup` above, but for the esbuild dep scanner: without this,
     // its default entry detection can miss code-split route files entirely, so a package only
     // ever imported from one of those (e.g. react-router's own deps) is discovered mid-run
     // instead of up front — statically crawling every source file (which esbuild's scanner
     // follows through dynamic imports too) avoids that with no per-package name needed
-    optimizeDeps: { entries: ['src/**/*.{ts,tsx}'] },
+    optimizeDeps: { entries: ['src/**/*.{ts,tsx}', '!src/**/*.d.ts'] },
   };
   // a function replaces the config outright; a plain object deep-merges onto it via Vite's own mergeConfig
   const resolved =

package/src/scope/resolve-fusion.ts

@@ -1,6 +1,10 @@
 import type { AppEnv } from '@equinor/fusion-framework-app';
 import type { Fusion } from '@equinor/fusion-framework';
-import { mockFramework, type FrameworkMockConfigureFn } from '@equinor/fusion-framework/mock';
+import {
+  mockFramework,
+  type FrameworkMockConfigureFn,
+  type FrameworkMockConfigurator,
+} from '@equinor/fusion-framework/mock';
 import { enableAppManifestMock } from '@equinor/fusion-framework-app/mock';
 import type { AppModule } from '@equinor/fusion-framework-module-app';
 import { enableNavigation, createHistory } from '@equinor/fusion-framework-module-navigation';
@@ -8,17 +12,46 @@ import type { NavigationModule } from '@equinor/fusion-framework-module-navigati
 
 import { defaultAppEnv } from './default-app-env';
 
+/**
+ * Enables the feature-flag mock only when `@equinor/fusion-framework-module-feature-flag` — an
+ * optional peer dependency — is actually installed, so apps that don't use feature flags aren't
+ * forced to install a module they never reference.
+ */
+async function enableFeatureFlagMockIfAvailable(
+  configurator: FrameworkMockConfigurator<[AppModule, NavigationModule]>,
+): Promise<void> {
+  try {
+    const { enableFeatureFlagMock } = await import(
+      '@equinor/fusion-framework-module-feature-flag/mock'
+    );
+    enableFeatureFlagMock(configurator);
+  } catch (error) {
+    // re-throw anything other than the optional peer being missing, so a real
+    // registration failure isn't silently swallowed
+    if (
+      error instanceof Error &&
+      (error.message.includes('Cannot find module') || error.message.includes('MODULE_NOT_FOUND'))
+    ) {
+      return;
+    }
+    throw error;
+  }
+}
+
 /**
  * Resolves the parent Fusion instance backing an application module scope, building a
  * fresh {@link mockFramework} instance with this app's own manifest served when none is
  * given.
  *
  * @template TEnv - The application environment descriptor.
- * @param options - `env` seeds the built-in app manifest mock; navigation defaults to real
- *   browser history, matching Browser Mode. `configure` runs afterwards on the same
- *   configurator — e.g. call `enableNavigation` again to override the history, or register
- *   extra modules and service discovery entries. `fusion`, an already-built parent instance,
- *   is reused as-is and skips `configure` entirely.
+ * @param options - `env` seeds the built-in app manifest mock; navigation defaults to in-memory
+ *   history, so tests don't leak URL/history state between runs. Feature flags default to the
+ *   in-memory feature-flag mock, with none enabled, when the optional
+ *   `@equinor/fusion-framework-module-feature-flag` peer dependency is installed. `configure`
+ *   runs afterwards on the same configurator — e.g. call `enableNavigation` or
+ *   `enableFeatureFlagMock` again to override either, or register extra modules and service
+ *   discovery entries. `fusion`, an already-built parent instance, is reused as-is and skips
+ *   `configure` entirely.
  * @returns The given `fusion`, or a fresh mocked parent Fusion instance.
  */
 export async function resolveFusion<TEnv extends AppEnv = AppEnv>(options?: {
@@ -32,8 +65,9 @@ export async function resolveFusion<TEnv extends AppEnv = AppEnv>(options?: {
     mockFramework<[AppModule, NavigationModule]>(async (configurator) => {
       enableAppManifestMock(configurator, env ?? (defaultAppEnv as TEnv));
       enableNavigation(configurator, {
-        configure: (config) => config.setHistory(createHistory('browser')),
+        configure: (config) => config.setHistory(createHistory('memory')),
       });
+      await enableFeatureFlagMockIfAvailable(configurator);
       await configure?.(configurator);
     })
   );

package/src/test-app.tsx

@@ -52,8 +52,12 @@ import { defaultAppEnv, resolveFusion, createAppScopeWrapper } from './scope';
  * @example Seed a module for every test in a suite
  * ```tsx
  * describe('with a seeded context module', () => {
- *   const test = testApp.extend('configureApp', { injected: true }, () =>
- *     (configurator) => enableContextMock(configurator, (mock) => mock.setCurrentContext(projectA)),
+ *   const test = testApp.extend(
+ *     'configureApp',
+ *     { injected: true },
+ *     (): AppMockConfigureFn =>
+ *       (configurator) =>
+ *         enableContextMock(configurator, (mock) => mock.setCurrentContext(projectA)),
  *   );
  *
  *   test('starts on the seeded context', async ({ render }) => {
@@ -63,16 +67,46 @@ import { defaultAppEnv, resolveFusion, createAppScopeWrapper } from './scope';
  * });
  * ```
  *
+ * @example Type `app`'s registered modules for consumers
+ * ```tsx
+ * // `configureApp`'s `TModules` generic only types that callback's own `configurator` parameter.
+ * // `app`'s type was already fixed (to `unknown`) when the base `testApp` chain defined it, so a
+ * // later `configureApp` override does not retroactively change what `app` is typed as. Re-extend
+ * // `app` too, with the same `TModules`, to get a typed `app.navigation` in tests.
+ * const test = testApp
+ *   .extend(
+ *     'configureApp',
+ *     { injected: true },
+ *     ({ configureApp }): AppMockConfigureFn<[NavigationModule]> =>
+ *       async (configurator, args) => {
+ *         await configureApp?.(configurator, args);
+ *         enableNavigation(configurator, '/app');
+ *       },
+ *   )
+ *   .extend('app', ({ configureApp, appEnv, fusion }) =>
+ *     mockAppModules<[NavigationModule], AppEnv>(configureApp, appEnv as AppEnv, fusion),
+ *   );
+ *
+ * test('exposes the navigation module', async ({ app }) => {
+ *   expect(app.navigation).toBeDefined();
+ * });
+ * ```
+ *
  * @example Extend the parent framework mock with an application module
  * ```tsx
- * const test = testApp.extend('configureFusion', { injected: true }, () =>
- *   (configurator) => {
- *     enableFeatureFlagMock(configurator);
- *     configurator.serviceDiscovery.addServices([
- *       { key: 'people', uri: baseUrl('people') },
- *       { key: 'context', uri: baseUrl('context') },
- *     ]);
- *   },
+ * const test = testApp.extend(
+ *   'configureFusion',
+ *   { injected: true },
+ *   (): FrameworkMockConfigureFn<[AppModule, NavigationModule]> =>
+ *     (configurator) => {
+ *       // seed a specific flag rather than merely enabling the mock — that's already the
+ *       // default when the optional feature-flag peer dependency is installed
+ *       enableFeatureFlagMock(configurator, (mock) => mock.addFeature({ key: 'new-search', enabled: true }));
+ *       configurator.serviceDiscovery.addServices([
+ *         { key: 'people', uri: baseUrl('people') },
+ *         { key: 'context', uri: baseUrl('context') },
+ *       ]);
+ *     },
  * );
  * ```
  */
@@ -81,9 +115,9 @@ export const testApp = baseTest
   // `test.extend`'s plain-`value` overload rejects function types (ambiguous with the
   // resolver-`fn` overload), so a function-typed fixture default must go through `fn` instead.
   .extend('configureApp', { injected: true }, () => undefined as AppMockConfigureFn | undefined)
-  // Runs after the built-in app manifest/navigation setup, so a test can register extra
-  // framework modules, service discovery entries, or call `enableNavigation` again to
-  // override the history, without reimplementing the base setup.
+  // Runs after the built-in app manifest/navigation/feature-flag setup, so a test can register
+  // extra framework modules, service discovery entries, or call `enableNavigation`/
+  // `enableFeatureFlagMock` again to override either, without reimplementing the base setup.
   .extend(
     'configureFusion',
     { injected: true },

package/src/version.ts

@@ -1,2 +1,2 @@
 // Generated by genversion.
-export const version = '1.0.0-next.4';
+export const version = '1.0.0-next.6';

package/tsconfig.json

@@ -16,6 +16,7 @@
     { "path": "../../modules/module" },
     { "path": "../../modules/app" },
     { "path": "../../modules/navigation" },
+    { "path": "../../modules/feature-flag" },
     { "path": "../../react/framework" },
     { "path": "../../react/modules/module" },
     { "path": "../../utils/imports" }